Publish an integration

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

objectstring · enumRequiredPossible values:

namestringRequired

Unique named identifier for the integration

versionnumberRequired

Version of the integration

titlestring · min: 2 · max: 30Required

Title of the integration

descriptionstring · max: 100Optional

Description of the integration

summarystring · max: 2048Optional

Long form markdown summary of the integration

previewImagesstring[] · max: 3Required

URLs of images to showcase the integration

targetstring · enumRequired

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

Possible values:

verifiedbooleanRequired

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

visibilitystring · enumRequiredPossible values:

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

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": "2026-07-22T23:08:54.662Z",
    "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": "2026-07-22T23:08:54.662Z",
      "hasPaymentFailed": true,
      "canCheckout": 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
        }
      },
      "minUsers": 1,
      "maxUsers": 1,
      "minPremiumSites": 1,
      "maxPremiumSites": 1,
      "minUltimateSites": 1,
      "maxUltimateSites": 1,
      "paidMembers": 1,
      "paidPremiumSites": 1,
      "paidUltimateSites": 1,
      "canChangeInterval": true,
      "canUseSAML": 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": "2026-07-22T23:08:54.662Z",
      "decision": "downgrade"
    },
    "customHostname": "text",
    "blocked": {
      "source": "backoffice",
      "reason": "text"
    },
    "internal_billingMigration": {
      "deadline": "2026-07-22T23:08:54.662Z",
      "discountPercent": 1,
      "discountEndDate": "2026-07-22T23:08:54.662Z"
    },
    "permissions": {
      "view": true,
      "access": true,
      "admin": true,
      "ownTeam": true,
      "createContent": true,
      "createOpenAPISpec": 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",
    "publicContentEndpoint": "https://example.com"
  },
  "permissions": {
    "admin": true
  },
  "contentSecurityPolicy": "text"
}