Integrations

An integration is the entity for an app developed on the GitBook Integrations Platform

POST an integration to the GitBook Integrations Platform

Publish an integration

POSThttps://api.gitbook.com/v1/integrations/{integrationName}
Authorization
Path parameters
integrationName*string

Name of the integration.

Pattern: ^[a-zA-Z0-9-_.]+$
Body
iconstring (byte)

Base64 content of the icon

title*IntegrationTitle (string)

Title of the integration

description*IntegrationDescription (string)

Description of the integration

summaryIntegrationSummary (string)

Long form markdown summary of the integration

previewImagesarray of string (byte)
visibilityIntegrationVisibility (enum)
publicprivateunlisted
targetIntegrationTarget (enum)

The target on which the integration can operate and needs to be configured for

allsitespaceorganization
scopes*IntegrationScopes (array of IntegrationScope (enum))

Permissions that should be granted to the integration

categoriesIntegrationCategories (array of IntegrationCategory (enum))

Categories for which the integration is listed in the marketplace

blocksIntegrationBlocks (array of IntegrationBlock (object))

Custom blocks defined by this integration.

contentSourcesarray of IntegrationContentSource (object)
externalLinksIntegrationExternalLinks (array of object)

External urls configured by the developer of the integration

configurationsIntegrationConfigurations (object)
script*string

Content of the script to use

organization*string

The ID or subdomain of the organization under which the integration should be published

secretsIntegrationSecrets (object)

Secrets stored on the integration and passed at runtime.

contentSecurityPolicyIntegrationContentSecurityPolicy (one of)

Security policy to validate the content of the integrations scripts and Contentkit. Will be sent as headers when processing the script fetch event and the blocks fetch events.

Response

OK

Body
object*enum
integration
name*string

Unique named identifier for the integration

version*number

Version of the integration

title*IntegrationTitle (string)

Title of the integration

descriptionIntegrationDescription (string)

Description of the integration

summaryIntegrationSummary (string)

Long form markdown summary of the integration

previewImages*array of string

URLs of images to showcase the integration

target*IntegrationTarget (enum)

The target on which the integration can operate and needs to be configured for

allsitespaceorganization
verified*boolean

If true, the integration has been verified by the GitBook team

visibility*IntegrationVisibility (enum)
publicprivateunlisted
scopes*IntegrationScopes (array of IntegrationScope (enum))

Permissions that should be granted to the integration

categories*IntegrationCategories (array of IntegrationCategory (enum))

Categories for which the integration is listed in the marketplace

blocksIntegrationBlocks (array of IntegrationBlock (object))

Custom blocks defined by this integration.

contentSourcesarray of IntegrationContentSource (object)
configurationsIntegrationConfigurations (object)
externalLinks*IntegrationExternalLinks (array of object)

External urls configured by the developer of the integration

owner*Organization (object)
urls*object

URLs associated with the object

permissions*object

The set of permissions for the integration

contentSecurityPolicyIntegrationContentSecurityPolicy (one of)

Security policy to validate the content of the integrations scripts and Contentkit. Will be sent as headers when processing the script fetch event and the blocks fetch events.

Request
const response = await fetch('https://api.gitbook.com/v1/integrations/{integrationName}', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "organization": "text",
      "title": "text",
      "description": "text",
      "script": "text",
      "scopes": [
        "snippets:read"
      ]
    }),
});
const data = await response.json();
Response
{
  "object": "integration",
  "name": "text",
  "version": 0,
  "title": "text",
  "description": "text",
  "summary": "text",
  "previewImages": [
    "text"
  ],
  "target": "all",
  "verified": false,
  "visibility": "public",
  "scopes": [
    "snippets:read"
  ],
  "categories": [
    "analytics"
  ],
  "blocks": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "icon": "text",
      "urlUnfurl": [
        "text"
      ],
      "markdown": {
        "codeblock": "text",
        "body": "text"
      }
    }
  ],
  "contentSources": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "icon": "text",
      "configuration": {
        "componentId": "text"
      }
    }
  ],
  "configurations": {
    "account": {
      "required": [
        "text"
      ]
    },
    "space": {
      "required": [
        "text"
      ]
    },
    "site": {
      "required": [
        "text"
      ]
    }
  },
  "externalLinks": [
    {
      "url": "https://example.com",
      "label": "text"
    }
  ],
  "owner": {
    "object": "organization",
    "id": "text",
    "title": "text",
    "createdAt": "2025-01-26T01:49:25.968Z",
    "emailDomains": [
      "text"
    ],
    "hostname": "text",
    "type": "business",
    "useCase": "internalDocs",
    "communityType": "nonProfit",
    "defaultRole": "admin",
    "defaultContent": {
      "type": "site",
      "site": "text"
    },
    "sso": false,
    "ai": false,
    "inviteLinks": false,
    "plan": "free_2024",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "logo": "https://example.com"
    },
    "trialDecision": "downgrade",
    "customHostname": "text",
    "blocked": {
      "reason": "security"
    },
    "internal_isUsingSnippets": false,
    "internal_isOnNewTrial": false,
    "permissions": {
      "admin": false,
      "createContent": false
    }
  },
  "urls": {
    "location": "https://example.com",
    "icon": "https://example.com",
    "app": "https://example.com",
    "assets": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "permissions": {
    "admin": false
  },
  "contentSecurityPolicy": "text"
}

DELETE an integration from the GitBook Integrations Platform

Unpublish an integration

DELETEhttps://api.gitbook.com/v1/integrations/{integrationName}
Authorization
Path parameters
integrationName*string

Name of the integration.

Pattern: ^[a-zA-Z0-9-_.]+$
Response

Integration has been deleted

Request
const response = await fetch('https://api.gitbook.com/v1/integrations/{integrationName}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();
Response
{
  "error": {
    "code": 0,
    "message": "text"
  }
}

Last updated