# Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/spaces/space-integrations.md

# Space integrations

This API handles the registration and removal of integrations, automating how data flows between GitBook and your chosen external services.

## GET /spaces/{spaceId}/integrations

> List integrations enabled in a space

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"space-integrations","description":"This API handles the registration and removal of integrations, automating how data flows between GitBook and your chosen external services.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"spaceId":{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}},"integrationSearchQuery":{"name":"search","in":"query","description":"A search string to filter integrations by name\n","schema":{"type":"string"}}},"schemas":{"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"Integration":{"type":"object","properties":{"object":{"type":"string","enum":["integration"]},"name":{"type":"string","description":"Unique named identifier for the integration"},"version":{"type":"number","description":"Version of the integration"},"title":{"$ref":"#/components/schemas/IntegrationTitle"},"description":{"$ref":"#/components/schemas/IntegrationDescription"},"summary":{"$ref":"#/components/schemas/IntegrationSummary"},"previewImages":{"type":"array","description":"URLs of images to showcase the integration","maxItems":3,"items":{"type":"string"}},"target":{"$ref":"#/components/schemas/IntegrationTarget"},"verified":{"type":"boolean","description":"If true, the integration has been verified by the GitBook team"},"visibility":{"$ref":"#/components/schemas/IntegrationVisibility"},"scopes":{"$ref":"#/components/schemas/IntegrationScopes"},"categories":{"$ref":"#/components/schemas/IntegrationCategories"},"blocks":{"$ref":"#/components/schemas/IntegrationBlocks"},"contentSources":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationContentSource"}},"configurations":{"$ref":"#/components/schemas/IntegrationConfigurations"},"externalLinks":{"$ref":"#/components/schemas/IntegrationExternalLinks"},"owner":{"$ref":"#/components/schemas/Organization"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the integration in the API","format":"uri"},"icon":{"type":"string","description":"URL of the icon associated to the integration","format":"uri"},"app":{"type":"string","description":"URL of the integration in the application","format":"uri"},"assets":{"type":"string","description":"URL of the integration's assets.","format":"uri"},"publicEndpoint":{"type":"string","description":"Public HTTP endpoint for the integration","format":"uri"}},"required":["location","app","assets","publicEndpoint"]},"permissions":{"type":"object","description":"The set of permissions for the integration","properties":{"admin":{"type":"boolean"}},"required":["admin"]},"contentSecurityPolicy":{"$ref":"#/components/schemas/IntegrationContentSecurityPolicy"}},"required":["object","name","version","title","scopes","categories","visibility","target","verified","previewImages","externalLinks","owner","permissions","urls"]},"IntegrationTitle":{"type":"string","description":"Title of the integration","minLength":2,"maxLength":30},"IntegrationDescription":{"type":"string","description":"Description of the integration","maxLength":100},"IntegrationSummary":{"type":"string","description":"Long form markdown summary of the integration","maxLength":2048},"IntegrationTarget":{"type":"string","description":"The target on which the integration can operate and needs to be configured for","enum":["all","site","space","organization"]},"IntegrationVisibility":{"type":"string","enum":["public","private","unlisted"]},"IntegrationScopes":{"type":"array","description":"Permissions that should be granted to the integration","items":{"$ref":"#/components/schemas/IntegrationScope"}},"IntegrationScope":{"type":"string","enum":["space:content:read","space:content:write","space:metadata:read","space:metadata:write","space:git:sync","page:feedback:read","site:metadata:read","site:views:read","site:script:inject","site:script:cookies","site:visitor:auth","site:adaptive:read","site:adaptive:write","openapi:read","openapi:write","conversations:ingest"]},"IntegrationCategories":{"type":"array","description":"Categories for which the integration is listed in the marketplace","items":{"$ref":"#/components/schemas/IntegrationCategory"}},"IntegrationCategory":{"type":"string","enum":["analytics","collaboration","content","gitsync","marketing","visitor-auth","other"]},"IntegrationBlocks":{"type":"array","description":"Custom blocks defined by this integration.","items":{"$ref":"#/components/schemas/IntegrationBlock"}},"IntegrationBlock":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID in the integration for the block. It also represents the UI component used."},"title":{"type":"string","description":"Short descriptive title for the block.","minLength":2,"maxLength":40},"description":{"type":"string","description":"Long descriptive text for the block.","minLength":0,"maxLength":150},"icon":{"type":"string","description":"URL of the icon to represent this block."},"urlUnfurl":{"type":"array","description":"URLs patterns to convert as this block.","items":{"type":"string"}},"markdown":{"$ref":"#/components/schemas/IntegrationBlockMarkdown"}},"required":["id","title"]},"IntegrationBlockMarkdown":{"oneOf":[{"type":"object","description":"Format the custom block as a codeblock","properties":{"codeblock":{"description":"Code block syntax to use to identify the block.","type":"string"},"body":{"description":"Key of the property to use as body of the codeblock.","type":"string"}},"required":["codeblock","body"]}]},"IntegrationContentSource":{"type":"object","description":"Definition of a content source provided by the integration.","properties":{"id":{"type":"string","description":"Unique ID in the integration for the source."},"title":{"type":"string","description":"Short descriptive title for the source.","minLength":2,"maxLength":40},"description":{"type":"string","description":"Long descriptive text for the source.","minLength":0,"maxLength":150},"icon":{"type":"string","description":"URL of the icon to represent this source."},"configuration":{"$ref":"#/components/schemas/IntegrationConfigurationComponent"}},"required":["id","title","configuration"]},"IntegrationConfigurationComponent":{"type":"object","description":"ContentKit component for configuration","properties":{"componentId":{"type":"string","description":"ID of the ContentKit component defined in the integration"}},"required":["componentId"]},"IntegrationConfigurations":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/IntegrationConfiguration"},"space":{"$ref":"#/components/schemas/IntegrationConfiguration"},"site":{"$ref":"#/components/schemas/IntegrationConfiguration"}}},"IntegrationConfiguration":{"oneOf":[{"$ref":"#/components/schemas/IntegrationConfigurationSchema"},{"$ref":"#/components/schemas/IntegrationConfigurationComponent"}]},"IntegrationConfigurationSchema":{"type":"object","description":"Schema for a configuration","properties":{"properties":{"type":"object","additionalProperties":{"allOf":[{"type":"object","properties":{"title":{"$ref":"#/components/schemas/IntegrationPropertyTitle"},"description":{"type":"string","maxLength":100}}},{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["string"]},"default":{"type":"string"},"completion_url":{"description":"If specified, this URL will be called to fetch suggestions for auto-completing the property.","type":"string"},"enum":{"type":"array","description":"If specified, only values from this array are allowed as inputs.","items":{"type":"string"}}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["number"]},"default":{"type":"number"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["boolean"]},"default":{"type":"boolean"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["button"]},"callback_url":{"type":"string"},"button_text":{"type":"string"}},"required":["type","callback_url","button_text"]}]}]}},"required":{"type":"array","uniqueItems":true,"items":{"type":"string"}}},"required":["properties"]},"IntegrationPropertyTitle":{"type":"string","description":"Property title for an integration configuration property","minLength":2,"maxLength":50},"IntegrationExternalLinks":{"type":"array","description":"External urls configured by the developer of the integration","maxItems":5,"items":{"type":"object","properties":{"url":{"$ref":"#/components/schemas/URL"},"label":{"type":"string"}},"required":["url","label"]}},"URL":{"type":"string","format":"uri","maxLength":2048},"Organization":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"organization\"","enum":["organization"]},"id":{"type":"string","description":"Unique identifier for the organization"},"title":{"$ref":"#/components/schemas/OrganizationTitle"},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"emailDomains":{"$ref":"#/components/schemas/OrganizationEmailDomains"},"hostname":{"$ref":"#/components/schemas/OrganizationHostname"},"type":{"$ref":"#/components/schemas/OrganizationType"},"useCase":{"$ref":"#/components/schemas/OrganizationUseCase"},"communityType":{"$ref":"#/components/schemas/OrganizationCommunityType"},"defaultRole":{"$ref":"#/components/schemas/MemberRoleOrGuest"},"defaultContent":{"$ref":"#/components/schemas/OrganizationDefaultContent"},"sso":{"description":"Whether SSO is enforced organization-wide","type":"boolean"},"ai":{"description":"If true, the organization is configured to use all our AI features.","type":"boolean"},"inviteLinks":{"description":"If true, invite links are enabled for this organization.","type":"boolean"},"plan":{"$ref":"#/components/schemas/BillingProduct"},"billing":{"description":"Billing details, only available for org members.","$ref":"#/components/schemas/OrganizationBilling"},"mergeRules":{"$ref":"#/components/schemas/MergeRulesStandaloneConfiguration"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the organization in the API","format":"uri"},"app":{"type":"string","description":"URL of the organization in the application","format":"uri"},"logo":{"description":"URL of the logo of this organization, if defined.","$ref":"#/components/schemas/URL"}},"required":["app","location"]},"trial":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/BillingTrialStatus"},"count":{"type":"integer","description":"Number of trials the organization has consumed."},"endDate":{"description":"The trial's end date, if the organization has or had a trial.","$ref":"#/components/schemas/Timestamp"},"decision":{"type":"string","description":"The decision taken by the user at the end of the trial","enum":["downgrade"]}},"required":["status","count"]},"customHostname":{"description":"Custom hostname linked to this organization","type":"string"},"blocked":{"type":"object","description":"If the organization is blocked, information about the block will appear here","properties":{"source":{"$ref":"#/components/schemas/BlockSource"},"reason":{"$ref":"#/components/schemas/BlockReason"}},"required":["reason"]},"internal_billingMigration":{"type":"object","properties":{"deadline":{"description":"When we will upgrade the organization onto new pricing, if they haven't already.","$ref":"#/components/schemas/Timestamp"},"discountPercent":{"description":"A discount the organization may have received thanks to migrating early.","type":"number"},"discountEndDate":{"description":"The expiration date of the discount, after wich regular pricing resumes.","$ref":"#/components/schemas/Timestamp"}}},"permissions":{"type":"object","description":"The set of permissions for the organization","properties":{"view":{"type":"boolean","description":"Can the user view the organization."},"access":{"type":"boolean","description":"Can the user view the organization in the application."},"admin":{"type":"boolean","description":"Can the user manage the title, members, etc."},"ownTeam":{"type":"boolean","description":"Is the user a team owner."},"createContent":{"type":"boolean","description":"Can the user create new spaces/collections in the organization."},"createOpenAPISpec":{"type":"boolean","description":"Can the user create new OpenAPI specifications."},"ingestConversations":{"type":"boolean","description":"Can the user ingest conversations in the organization."},"viewBilling":{"type":"boolean","description":"Can the user view the billing details of the organization."},"listMembers":{"type":"boolean","description":"Can the user list the members of the organization."},"listTeams":{"type":"boolean","description":"Can the user list the teams in the organization."},"listIntegrations":{"type":"boolean","description":"Can the user list the integrations in the organization."},"listInstallations":{"type":"boolean","description":"Can the user list the integration installations in the organization."},"installIntegration":{"type":"boolean","description":"Can the user install integrations in the organization."}},"required":["view","access","admin","ownTeam","createContent","createOpenAPISpec","ingestConversations","viewBilling","listMembers","listTeams","listIntegrations","listInstallations","installIntegration"]}},"required":["object","id","plan","title","createdAt","inviteLinks","type","emailDomains","mergeRules","urls","trial","permissions"]},"OrganizationTitle":{"type":"string","description":"Name of the organization","minLength":2,"maxLength":255},"Timestamp":{"type":"string","format":"date-time"},"OrganizationEmailDomains":{"type":"array","items":{"type":"string"}},"OrganizationHostname":{"type":"string","description":"Default hostname for the organization's public content, e.g. <org-hostname>.gitbook.io","minLength":3,"maxLength":32},"OrganizationType":{"type":"string","enum":["business","community"]},"OrganizationUseCase":{"type":"string","enum":["internalDocs","docsSite","audienceControlledSite","productDocs","teamKnowledgeBase","designSystem","openSourceDocs","notes","other"]},"OrganizationCommunityType":{"type":"string","enum":["nonProfit","openSource","education"]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"string","nullable":true,"enum":[null]}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]},"OrganizationDefaultContent":{"description":"The default content for the organization","oneOf":[{"$ref":"#/components/schemas/SitePointer"}]},"SitePointer":{"type":"object","properties":{"type":{"type":"string","enum":["site"]},"site":{"type":"string","description":"Unique identifier for the site"}},"required":["type","site"]},"BillingProduct":{"type":"string","description":"Name of the product","enum":["free_2024","plus_2024","pro_2024","enterprise_2024","community_2024","free","plus","pro","internal"]},"OrganizationBilling":{"type":"object","properties":{"interval":{"$ref":"#/components/schemas/BillingInterval"},"endDate":{"$ref":"#/components/schemas/Timestamp","nullable":true},"hasPaymentFailed":{"description":"If true, we were unable to collect the last payment","type":"boolean"},"isScheduledToCancel":{"description":"If true, the billing is set to cancel at the end of its current period","type":"boolean"},"pricing":{"description":"Pricing information for the organization","$ref":"#/components/schemas/OrganizationPricing"},"usageAddons":{"description":"Configuration for the usage-based addons","type":"object","additionalProperties":{"$ref":"#/components/schemas/BillingMeterAddon"}},"minUsers":{"description":"The minimum number of members allowed for this organization.","type":"number"},"maxUsers":{"description":"The maximum number of members allowed for this organization","type":"number"},"paidMembers":{"description":"The number of paid members on the current subscription.","type":"number"}},"required":["interval","endDate","hasPaymentFailed","isScheduledToCancel","pricing","usageAddons"]},"BillingInterval":{"type":"string","description":"Interval for a billing subscription","enum":["monthly","yearly"]},"OrganizationPricing":{"type":"object","description":"Pricing information for an organization","properties":{"members":{"type":"object","description":"Pricing for members (organization plan)","properties":{"plus_2024":{"$ref":"#/components/schemas/OrganizationPricePair"},"pro_2024":{"$ref":"#/components/schemas/OrganizationPricePair"}},"required":["plus_2024","pro_2024"],"additionalProperties":false},"sites":{"type":"object","description":"Pricing for site types (site plans)","properties":{"premium":{"$ref":"#/components/schemas/OrganizationPricePair"},"ultimate":{"$ref":"#/components/schemas/OrganizationPricePair"}},"required":["premium","ultimate"],"additionalProperties":false}},"required":["members","sites"]},"OrganizationPricePair":{"type":"object","description":"Pricing pair for monthly and yearly intervals","properties":{"monthly":{"type":"number","description":"Monthly price in USD","minimum":0},"yearly":{"type":"number","description":"Yearly price in USD (per month)","minimum":0}},"required":["monthly","yearly"]},"BillingMeterAddon":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"MergeRulesStandaloneConfiguration":{"oneOf":[{"$ref":"#/components/schemas/MergeRulesConfigurationRules"},{"$ref":"#/components/schemas/MergeRulesConfigurationNone"}]},"MergeRulesConfigurationRules":{"type":"object","description":"The merge rules are composed of individual rules that must all pass.","properties":{"type":{"type":"string","enum":["rules"]},"rules":{"type":"array","items":{"$ref":"#/components/schemas/MergeRule"}}},"required":["type","rules"]},"MergeRule":{"oneOf":[{"type":"object","properties":{"rule":{"type":"string","enum":["require_specific_reviewers"]},"users":{"type":"array","description":"List of user IDs.","items":{"type":"string"}}},"required":["rule","users"]},{"type":"object","properties":{"rule":{"type":"string","enum":["require_one_of_specific_reviewers"]},"users":{"type":"array","description":"List of user IDs.","items":{"type":"string"}}},"required":["rule","users"]},{"type":"object","properties":{"rule":{"type":"string","enum":["allow_bypass"]},"users":{"type":"array","description":"List of user IDs.","items":{"type":"string"}}},"required":["rule","users"]},{"type":"object","properties":{"rule":{"type":"string","enum":["require_at_least_one_review","require_at_least_one_approved_review","require_all_reviews_approved","require_agent_review","require_up_to_date_change_request","require_change_request_subject","require_change_request_description","require_author_to_merge"]}},"required":["rule"]},{"type":"object","description":"The merge rule is written in the advanced custom expression syntax.","properties":{"rule":{"type":"string","enum":["custom"]},"expression":{"$ref":"#/components/schemas/Expression"}},"required":["rule","expression"]}]},"Expression":{"type":"string","description":"Expression to evaluate","minLength":0,"maxLength":1024},"MergeRulesConfigurationNone":{"type":"object","description":"The merge rules are disabled, change requests can be merged without review.","properties":{"type":{"type":"string","enum":["none"]}},"required":["type"]},"BillingTrialStatus":{"type":"string","description":"- notapplicable, no trial can be started for this organization. - none, no trial has been started yet. - active, trial is active. - ended, the trial has ended and the user has choosen to stay on the free plan or has upgraded to a paid plan. - expired, the trial has ended but the user hasn't deciced yet what to do.\n","enum":["notapplicable","none","active","ended","expired"]},"BlockSource":{"type":"string","description":"Source for an organization block","enum":["backoffice","external","internal"]},"BlockReason":{"type":"string","description":"A short description giving context on the reason for the block.","minLength":1,"maxLength":255},"IntegrationContentSecurityPolicy":{"description":"Security policy to validate the content of the integrations scripts and Contentkit. Will be sent as \nheaders when processing the script fetch event and the blocks fetch events.\n","oneOf":[{"type":"string"},{"type":"object","properties":{"base-uri":{"type":"string"},"block-all-mixed-content":{"type":"string"},"child-src":{"type":"string"},"connect-src":{"type":"string"},"default-src":{"type":"string"},"font-src":{"type":"string"},"form-action":{"type":"string"},"frame-ancestors":{"type":"string"},"frame-src":{"type":"string"},"img-src":{"type":"string"},"manifest-src":{"type":"string"},"media-src":{"type":"string"},"navigate-to":{"type":"string"},"object-src":{"type":"string"},"plugin-types":{"type":"string"},"prefetch-src":{"type":"string"},"referrer":{"type":"string"},"report-to":{"type":"string"},"report-uri":{"type":"string"},"require-sri-for":{"type":"string"},"require-trusted-types-for":{"type":"string"},"sandbox":{"type":"string"},"script-src":{"type":"string"},"script-src-attr":{"type":"string"},"script-src-elem":{"type":"string"},"style-src":{"type":"string"},"style-src-attr":{"type":"string"},"style-src-elem":{"type":"string"},"trusted-types":{"type":"string"},"upgrade-insecure-requests":{"type":"string"},"worker-src":{"type":"string"}}}]}}},"paths":{"/spaces/{spaceId}/integrations":{"get":{"operationId":"listSpaceIntegrations","summary":"List integrations enabled in a space","tags":["space-integrations"],"parameters":[{"$ref":"#/components/parameters/spaceId"},{"$ref":"#/components/parameters/integrationSearchQuery"}],"responses":{"200":{"description":"Listing of integrations enabled in the space.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Integration"}}}}]}}}}}}}}}
```

## GET /spaces/{spaceId}/integration-blocks

> List all space integrations blocks

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"space-integrations","description":"This API handles the registration and removal of integrations, automating how data flows between GitBook and your chosen external services.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]},{"user-internal":[]},{"user-staff":[]},{"user-internal-or-staff":[]},{"integration":[]},{"integration-installation":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"},"user-internal":{"type":"http","scheme":"bearer"},"user-staff":{"type":"http","scheme":"bearer"},"user-internal-or-staff":{"type":"http","scheme":"bearer"},"integration":{"type":"http","scheme":"bearer"},"integration-installation":{"type":"http","scheme":"bearer"}},"parameters":{"spaceId":{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}}},"schemas":{"SpaceIntegrationBlocks":{"type":"array","items":{"type":"object","required":["name","blocks"],"properties":{"name":{"type":"string","description":"Unique named identifier for the integration"},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationBlock"}}}}},"IntegrationBlock":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID in the integration for the block. It also represents the UI component used."},"title":{"type":"string","description":"Short descriptive title for the block.","minLength":2,"maxLength":40},"description":{"type":"string","description":"Long descriptive text for the block.","minLength":0,"maxLength":150},"icon":{"type":"string","description":"URL of the icon to represent this block."},"urlUnfurl":{"type":"array","description":"URLs patterns to convert as this block.","items":{"type":"string"}},"markdown":{"$ref":"#/components/schemas/IntegrationBlockMarkdown"}},"required":["id","title"]},"IntegrationBlockMarkdown":{"oneOf":[{"type":"object","description":"Format the custom block as a codeblock","properties":{"codeblock":{"description":"Code block syntax to use to identify the block.","type":"string"},"body":{"description":"Key of the property to use as body of the codeblock.","type":"string"}},"required":["codeblock","body"]}]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/spaces/{spaceId}/integration-blocks":{"get":{"operationId":"listSpaceIntegrationsBlocks","summary":"List all space integrations blocks","tags":["space-integrations"],"parameters":[{"$ref":"#/components/parameters/spaceId"}],"responses":{"200":{"description":"list of installed integration blocks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpaceIntegrationBlocks"}}}},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```