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

user

Path parameters

integrationName*string

Name of the integration.

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

Body

application/json

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.

stringobject

Response

200404default

OK

Body

application/json

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.

stringobject

Request

JavaScriptCurlPython

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

200404default

{
  "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": "2024-11-21T07:27:38.683Z",
    "emailDomains": [
      "text"
    ],
    "hostname": "text",
    "type": "business",
    "useCase": "internalDocs",
    "communityType": "nonProfit",
    "defaultRole": "admin",
    "defaultContent": {
      "type": "space",
      "space": "text"
    },
    "sso": false,
    "ai": false,
    "inviteLinks": false,
    "plan": "free_2024",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "logo": "https://example.com"
    }
  },
  "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

user

Path parameters

integrationName*string

Name of the integration.

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

Response

204default

Integration has been deleted

Request

JavaScriptCurlPython

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

Response

default

{
  "error": {
    "message": "text"
  }
}