Integrations

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

Publish an integration

post

Authorizations

user

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

Body

application/json

runtimestring · enumOptional

The runtime version to use for the integration. If not specified, the integration will use the default runtime.

Default: v1Possible values:

iconstring · byteOptional

Base64 content of the icon

titlestring · min: 2 · max: 30Required

Title of the integration

descriptionstring · max: 100Required

Description of the integration

summarystring · max: 2048Optional

Long form markdown summary of the integration

previewImagesstring · byte[] · max: 3Optional

Base64 content of the image

visibilitystring · enumOptionalPossible values:

targetstring · enumOptional

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

Possible values:

scriptstringRequired

Content of the script to use

organizationstringRequired

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

contentSecurityPolicyone ofOptional

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.

stringOptional

or

Responses

200

OK

application/json

404

Organization could not be found for the given hostname

application/json

post

/integrations/{integrationName}

HTTPcURLJavaScriptPython

POST /v1/integrations/{integrationName} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1219

{
  "runtime": "v1",
  "icon": "Ynl0ZXM=",
  "title": "text",
  "description": "text",
  "summary": "text",
  "previewImages": [
    "Ynl0ZXM="
  ],
  "visibility": "public",
  "target": "all",
  "scopes": [
    "space:content: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"
      }
    }
  ],
  "externalLinks": [
    {
      "url": "https://example.com",
      "label": "text"
    }
  ],
  "configurations": {
    "account": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text",
          "completion_url": "text",
          "enum": [
            "text"
          ]
        }
      },
      "required": [
        "text"
      ]
    },
    "space": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text",
          "completion_url": "text",
          "enum": [
            "text"
          ]
        }
      },
      "required": [
        "text"
      ]
    },
    "site": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text",
          "completion_url": "text",
          "enum": [
            "text"
          ]
        }
      },
      "required": [
        "text"
      ]
    }
  },
  "script": "text",
  "organization": "text",
  "secrets": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "contentSecurityPolicy": "text"
}

{
  "object": "integration",
  "name": "text",
  "version": 1,
  "title": "text",
  "description": "text",
  "summary": "text",
  "previewImages": [
    "text"
  ],
  "target": "all",
  "verified": true,
  "visibility": "public",
  "scopes": [
    "space:content: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": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text",
          "completion_url": "text",
          "enum": [
            "text"
          ]
        }
      },
      "required": [
        "text"
      ]
    },
    "space": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text",
          "completion_url": "text",
          "enum": [
            "text"
          ]
        }
      },
      "required": [
        "text"
      ]
    },
    "site": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text",
          "completion_url": "text",
          "enum": [
            "text"
          ]
        }
      },
      "required": [
        "text"
      ]
    }
  },
  "externalLinks": [
    {
      "url": "https://example.com",
      "label": "text"
    }
  ],
  "owner": {
    "object": "organization",
    "id": "text",
    "title": "text",
    "createdAt": "2025-11-06T14:44:50.241Z",
    "emailDomains": [
      "text"
    ],
    "hostname": "text",
    "type": "business",
    "useCase": "internalDocs",
    "communityType": "nonProfit",
    "defaultRole": "admin",
    "defaultContent": {
      "type": "site",
      "site": "text"
    },
    "sso": true,
    "ai": true,
    "inviteLinks": true,
    "plan": "free_2024",
    "billing": {
      "interval": "monthly",
      "endDate": "2025-11-06T14:44:50.241Z",
      "hasPaymentFailed": true,
      "isScheduledToCancel": true,
      "pricing": {
        "members": {
          "plus_2024": {
            "monthly": 1,
            "yearly": 1
          },
          "pro_2024": {
            "monthly": 1,
            "yearly": 1
          }
        },
        "sites": {
          "premium": {
            "monthly": 1,
            "yearly": 1
          },
          "ultimate": {
            "monthly": 1,
            "yearly": 1
          }
        }
      },
      "usageAddons": {
        "ANY_ADDITIONAL_PROPERTY": {
          "enabled": true
        }
      }
    },
    "mergeRules": {
      "type": "rules",
      "rules": [
        {
          "rule": "require_specific_reviewers",
          "users": [
            "text"
          ]
        }
      ]
    },
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "logo": "https://example.com"
    },
    "trial": {
      "status": "notapplicable",
      "count": 1,
      "endDate": "2025-11-06T14:44:50.241Z",
      "decision": "downgrade"
    },
    "customHostname": "text",
    "blocked": {
      "source": "backoffice",
      "reason": "text"
    },
    "internal_billingMigration": {
      "deadline": "2025-11-06T14:44:50.241Z",
      "discountPercent": 1,
      "discountEndDate": "2025-11-06T14:44:50.241Z"
    },
    "permissions": {
      "view": true,
      "admin": true,
      "ownTeam": true,
      "createContent": true,
      "createOpenAPISpec": true,
      "ingestConversations": true,
      "viewBilling": true,
      "listMembers": true,
      "listTeams": true,
      "listIntegrations": true,
      "listInstallations": true,
      "installIntegration": true
    }
  },
  "urls": {
    "location": "https://example.com",
    "icon": "https://example.com",
    "app": "https://example.com",
    "assets": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "permissions": {
    "admin": true
  },
  "contentSecurityPolicy": "text"
}

Unpublish an integration

delete

Authorizations

user

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

Responses

204

Integration did not exist

No content

205

Integration has been deleted

delete

/integrations/{integrationName}

HTTPcURLJavaScriptPython

DELETE /v1/integrations/{integrationName} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content