Integrations

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

Last updated 8 days ago

Was this helpful?

Publish an integration

post

/integrations/{integrationName}

Authorizations

Path parameters

integrationNamestringrequired

Name of the integration.

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

Body

titlestringrequired

Title of the integration

descriptionstringrequired

Description of the integration

summarystring

Long form markdown summary of the integration

visibilityenum

Options: public, private, unlisted

scopesenum[]required

Permissions that should be granted to the integration

categoriesenum[]

Categories for which the integration is listed in the marketplace

blocksobject[]

Custom blocks defined by this integration.

externalLinksobject[]

External urls configured by the developer of the integration

configurationsobject

secretsobject

Secrets stored on the integration and passed at runtime.

contentSecurityPolicyone 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.

iconstring byte

Base64 content of the icon

targetenum

Allowed installation target for the integration. If not specified, the integration can be installed at all targets (org, spaces etc)

Options: all, site, space, organization

scriptstringrequired

Content of the script to use

organizationstringrequired

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

contentSourcesobject[]

previewImagesstring byte[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/integrations/{integrationName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"title":"text","description":"text","visibility":"public","scopes":["space:views:read"],"categories":["analytics"],"blocks":[{"markdown":{"codeblock":"text","body":"text"},"id":"text","title":"text","urlUnfurl":[null]}],"externalLinks":[{"url":"https://example.com","label":"text"}],"configurations":{"account":{"required":[null],"properties":{"ANY_ADDITIONAL_PROPERTY":{"type":"string"}}},"space":{"required":[null],"properties":{"ANY_ADDITIONAL_PROPERTY":{"type":"string"}}},"site":{"required":[null],"properties":{"ANY_ADDITIONAL_PROPERTY":{"type":"string"}}}},"secrets":{},"target":"all","script":"text","organization":"text","contentSources":[{"configuration":{"componentId":"text"},"id":"text","title":"text"}],"previewImages":[null]}'

200

404

default

{
  "title": "text",
  "description": "text",
  "summary": "text",
  "target": "all",
  "visibility": "public",
  "scopes": [
    "space:views:read"
  ],
  "categories": [
    "analytics"
  ],
  "blocks": [
    {
      "markdown": {
        "codeblock": "text",
        "body": "text"
      },
      "id": "text",
      "title": "text",
      "urlUnfurl": [
        null
      ]
    }
  ],
  "configurations": {
    "account": {
      "required": [
        null
      ],
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "string"
        }
      }
    },
    "space": {
      "required": [
        null
      ],
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "string"
        }
      }
    },
    "site": {
      "required": [
        null
      ],
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "string"
        }
      }
    }
  },
  "externalLinks": [
    {
      "url": "https://example.com",
      "label": "text"
    }
  ],
  "owner": {
    "title": "text",
    "createdAt": "2025-02-15T16:25:47.429Z",
    "emailDomains": [
      "text"
    ],
    "hostname": "text",
    "type": "business",
    "useCase": "internalDocs",
    "communityType": "nonProfit",
    "defaultRole": "admin",
    "defaultContent": {
      "type": "site",
      "site": "text"
    },
    "plan": "free_2024",
    "id": "text",
    "sso": true,
    "ai": true,
    "inviteLinks": true,
    "customHostname": "text",
    "internal_isOnNewTrial": true,
    "object": "organization",
    "trialDecision": "downgrade",
    "blocked": {
      "reason": "security"
    },
    "internal_billingMigration": {
      "deadline": "2025-02-15T16:25:47.429Z",
      "discountPercent": 1,
      "discountEndDate": "2025-02-15T16:25:47.429Z"
    },
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "logo": "https://example.com"
    },
    "permissions": {
      "admin": true,
      "createContent": true
    }
  },
  "contentSecurityPolicy": "text",
  "object": "integration",
  "name": "text",
  "version": 1,
  "verified": true,
  "contentSources": [
    {
      "configuration": {
        "componentId": "text"
      },
      "id": "text",
      "title": "text",
      "description": "text",
      "icon": "text"
    }
  ],
  "previewImages": [
    "text"
  ],
  "permissions": {
    "admin": true
  },
  "urls": {
    "location": "https://example.com",
    "icon": "https://example.com",
    "app": "https://example.com",
    "assets": "https://example.com",
    "publicEndpoint": "https://example.com"
  }
}

Unpublish an integration

delete