Integrations

List integrations enabled in a space.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Query parameters

searchstringOptional

A search string to filter integrations by name

Responses

200

Listing of integrations enabled in the space.

application/json

default

Unexpected Error

application/json

get

/spaces/{spaceId}/integrations

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/integrations HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "integration",
      "name": "text",
      "version": 1,
      "title": "text",
      "description": "text",
      "summary": "text",
      "previewImages": [
        "text"
      ],
      "target": "all",
      "verified": true,
      "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": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        },
        "space": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        },
        "site": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        }
      },
      "externalLinks": [
        {
          "url": "https://example.com",
          "label": "text"
        }
      ],
      "owner": {
        "object": "organization",
        "id": "text",
        "title": "text",
        "createdAt": "2026-01-25T23:51:25.823Z",
        "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",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "logo": "https://example.com"
        },
        "trialDecision": "downgrade",
        "customHostname": "text",
        "blocked": {
          "reason": "security"
        },
        "internal_isUsingSnippets": true,
        "internal_isOnNewTrial": true,
        "permissions": {
          "admin": true,
          "createContent": 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"
    }
  ]
}

List integrations blocks for a space

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Responses

200

list of installed integration blocks

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

get

/spaces/{spaceId}/integration-blocks

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/integration-blocks HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "name": "text",
    "blocks": [
      {
        "id": "text",
        "title": "text",
        "description": "text",
        "icon": "text",
        "urlUnfurl": [
          "text"
        ],
        "markdown": {
          "codeblock": "text",
          "body": "text"
        }
      }
    ]
  }
]

List all public integrations

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

searchstringOptional

A search string to filter integrations by name

categorystring · enumOptional

Filter the integrations by category

Possible values:

blockDomainstring · max: 100Optional

Filter the integrations by block's domains

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

blocksbooleanOptional

If true, returns only integrations with blocks. If false, returns only integrations without blocks.

Responses

200

Paginated list of integrations

application/json

default

Unexpected Error

application/json

get

/integrations

HTTPcURLJavaScriptPython

GET /v1/integrations HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "integration",
      "name": "text",
      "version": 1,
      "title": "text",
      "description": "text",
      "summary": "text",
      "previewImages": [
        "text"
      ],
      "target": "all",
      "verified": true,
      "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": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        },
        "space": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        },
        "site": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        }
      },
      "externalLinks": [
        {
          "url": "https://example.com",
          "label": "text"
        }
      ],
      "owner": {
        "object": "organization",
        "id": "text",
        "title": "text",
        "createdAt": "2026-01-25T23:51:25.823Z",
        "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",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "logo": "https://example.com"
        },
        "trialDecision": "downgrade",
        "customHostname": "text",
        "blocked": {
          "reason": "security"
        },
        "internal_isUsingSnippets": true,
        "internal_isOnNewTrial": true,
        "permissions": {
          "admin": true,
          "createContent": 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"
    }
  ]
}

Get a specific integration by its name

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

Responses

200

Integration

application/json

404

No matching integration found for given name

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}

HTTPcURLJavaScriptPython

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

{
  "object": "integration",
  "name": "text",
  "version": 1,
  "title": "text",
  "description": "text",
  "summary": "text",
  "previewImages": [
    "text"
  ],
  "target": "all",
  "verified": true,
  "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": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    },
    "space": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    },
    "site": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    }
  },
  "externalLinks": [
    {
      "url": "https://example.com",
      "label": "text"
    }
  ],
  "owner": {
    "object": "organization",
    "id": "text",
    "title": "text",
    "createdAt": "2026-01-25T23:51:25.823Z",
    "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",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "logo": "https://example.com"
    },
    "trialDecision": "downgrade",
    "customHostname": "text",
    "blocked": {
      "reason": "security"
    },
    "internal_isUsingSnippets": true,
    "internal_isOnNewTrial": true,
    "permissions": {
      "admin": true,
      "createContent": 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"
}

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

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

default

Unexpected Error

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: 1079

{
  "icon": "Ynl0ZXM=",
  "title": "text",
  "description": "text",
  "summary": "text",
  "previewImages": [
    "Ynl0ZXM="
  ],
  "visibility": "public",
  "target": "all",
  "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"
      }
    }
  ],
  "externalLinks": [
    {
      "url": "https://example.com",
      "label": "text"
    }
  ],
  "configurations": {
    "account": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    },
    "space": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    },
    "site": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "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": [
    "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": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    },
    "space": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    },
    "site": {
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {
          "title": "text",
          "description": "text",
          "type": "string",
          "default": "text"
        }
      },
      "required": [
        "text"
      ]
    }
  },
  "externalLinks": [
    {
      "url": "https://example.com",
      "label": "text"
    }
  ],
  "owner": {
    "object": "organization",
    "id": "text",
    "title": "text",
    "createdAt": "2026-01-25T23:51:25.823Z",
    "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",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "logo": "https://example.com"
    },
    "trialDecision": "downgrade",
    "customHostname": "text",
    "blocked": {
      "reason": "security"
    },
    "internal_isUsingSnippets": true,
    "internal_isOnNewTrial": true,
    "permissions": {
      "admin": true,
      "createContent": 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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

Responses

204

Integration has been deleted

default

Unexpected Error

application/json

delete

/integrations/{integrationName}

HTTPcURLJavaScriptPython

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

No content

Fetch a list of installations of an integration

get

Authorizations

integration

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

externalIdstringOptional

External Id to filter by

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/installations

HTTPcURLJavaScriptPython

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

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "status": "active",
      "space_selection": "all",
      "site_selection": "all",
      "spaces": 1,
      "configuration": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "createdAt": "2026-01-25T23:51:25.823Z",
      "updatedAt": "2026-01-25T23:51:25.823Z",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "publicEndpoint": "https://example.com"
      },
      "externalIds": [
        "text"
      ],
      "target": {
        "organization": "text"
      }
    }
  ]
}

Install integration on a target organization

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

organizationstringRequired

Responses

201

Integration installed successfully

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

post

/integrations/{integrationName}/installations

HTTPcURLJavaScriptPython

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

{
  "organization": "text"
}

{
  "id": "text",
  "status": "active",
  "space_selection": "all",
  "site_selection": "all",
  "spaces": 1,
  "configuration": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "createdAt": "2026-01-25T23:51:25.823Z",
  "updatedAt": "2026-01-25T23:51:25.823Z",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "externalIds": [
    "text"
  ],
  "target": {
    "organization": "text"
  }
}

List all integration events

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

Paginated list of integration events

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/events

HTTPcURLJavaScriptPython

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

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "integrationId": "text",
      "installationId": "text",
      "createdAt": "2026-01-25T23:51:25.823Z",
      "payload": {
        "eventId": "text",
        "type": "installation_setup",
        "installationId": "text",
        "status": "active",
        "previous": {
          "status": "active",
          "configuration": {}
        }
      },
      "status": "success"
    }
  ]
}

Get a specific integration event by its id

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

eventIdstringRequired

ID of the integration event

Responses

200

Integration event

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/events/{eventId}

HTTPcURLJavaScriptPython

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

{
  "event": {
    "id": "text",
    "integrationId": "text",
    "installationId": "text",
    "createdAt": "2026-01-25T23:51:25.823Z",
    "payload": {
      "eventId": "text",
      "type": "installation_setup",
      "installationId": "text",
      "status": "active",
      "previous": {
        "status": "active",
        "configuration": {}
      }
    },
    "status": "success"
  },
  "trace": {
    "logs": [
      {
        "message": "text",
        "timestamp": "2026-01-25T23:51:25.823Z",
        "level": "debug"
      }
    ]
  }
}

Fetch a list of space installations of an integration

get

Authorizations

integration

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

externalIdstringOptional

External Id to filter by

extendedbooleanOptional

If true, returns the space object in each items. If false, returns the space ID in each items.

Default: false

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/spaces

HTTPcURLJavaScriptPython

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

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "integration": "text",
      "installation": "text",
      "status": "active",
      "configuration": {},
      "externalIds": [
        "text"
      ],
      "urls": {
        "location": "https://example.com",
        "publicEndpoint": "https://example.com"
      },
      "space": "text"
    }
  ]
}

Update an integration to be in development mode.

put

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

tunnelUrlstring · min: 1 · max: 256Required

URL of the tunnel to dispatch integration events to

allbooleanOptional

If set to true, all requests will be forwarded to the tunnel, not just from the owning organization.

Default: false

Responses

204

Updated development mode successfully

404

Not Found

application/json

default

Unexpected Error

application/json

put

/integrations/{integrationName}/dev

HTTPcURLJavaScriptPython

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

{
  "tunnelUrl": "text",
  "all": false
}

No content

Disable the development mode on an integration.

delete

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-_.]+$

Responses

205

Disabled development mode successfully

default

Unexpected Error

application/json

delete

/integrations/{integrationName}/dev

HTTPcURLJavaScriptPython

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

No content

Queue a task for an integration to be executed later

post

Authorizations

integration

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

taskobjectRequired

Payload for the integration task

schedulenumber · max: 86400Optional

Number of seconds to wait before executing the task, defaults to 0

Responses

204

Integration task created successfully

404

Not Found

application/json

default

Unexpected Error

application/json

post

/integrations/{integrationName}/tasks

HTTPcURLJavaScriptPython

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

{
  "task": {},
  "schedule": 1
}

No content

Get a specific integration's installation by its ID

get

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-_.]+$

installationIdstringRequired

Identifier of the installation

Responses

200

Integration installation

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/installations/{installationId}

HTTPcURLJavaScriptPython

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

{
  "id": "text",
  "status": "active",
  "space_selection": "all",
  "site_selection": "all",
  "spaces": 1,
  "configuration": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "createdAt": "2026-01-25T23:51:25.823Z",
  "updatedAt": "2026-01-25T23:51:25.823Z",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "externalIds": [
    "text"
  ],
  "target": {
    "organization": "text"
  }
}

Uninstall the integration from a target organization

delete

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-_.]+$

installationIdstringRequired

Identifier of the installation

Responses

204

Integration uninstalled successfully

404

Not Found

application/json

default

Unexpected Error

application/json

delete

/integrations/{integrationName}/installations/{installationId}

HTTPcURLJavaScriptPython

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

No content

Update external IDs and configurations of an integration's installation

patch

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-_.]+$

installationIdstringRequired

Identifier of the installation

Body

application/json

externalIdsstring[] · max: 5Optional

External IDs assigned by the integration.

space_selectionstring · enumOptional

Describe whether all spaces have been selected or there's a selection involved

Possible values:

site_selectionstring · enumOptional

Describe whether all sites have been selected or there's a selection involved

Possible values:

Responses

200

The installation has been updated.

application/json

default

Unexpected Error

application/json

patch

/integrations/{integrationName}/installations/{installationId}

HTTPcURLJavaScriptPython

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

{
  "externalIds": [
    "text"
  ],
  "configuration": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "space_selection": "all",
  "site_selection": "all"
}

{
  "id": "text",
  "status": "active",
  "space_selection": "all",
  "site_selection": "all",
  "spaces": 1,
  "configuration": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "createdAt": "2026-01-25T23:51:25.823Z",
  "updatedAt": "2026-01-25T23:51:25.823Z",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "externalIds": [
    "text"
  ],
  "target": {
    "organization": "text"
  }
}

Create an integration installation API token

post

Creates a temporary API token of an integration's installation that has access to the installation and it's scopes. You must be authenticated as the integration to obtain this token.

Authorizations

integration

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

installationIdstringRequired

Identifier of the installation

Responses

200

The API token for the installation

application/json

404

Installation could not be found

application/json

default

Unexpected Error

application/json

post

/integrations/{integrationName}/installations/{installationId}/tokens

HTTPcURLJavaScriptPython

POST /v1/integrations/{integrationName}/installations/{installationId}/tokens HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "token": "text"
}

List installations on spaces for an integration in an organization

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

installationIdstringRequired

Identifier of the installation

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

extendedbooleanOptional

If true, returns the space object in each items. If false, returns the space ID in each items.

Default: false

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/installations/{installationId}/spaces

HTTPcURLJavaScriptPython

GET /v1/integrations/{integrationName}/installations/{installationId}/spaces HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "integration": "text",
      "installation": "text",
      "status": "active",
      "configuration": {},
      "externalIds": [
        "text"
      ],
      "urls": {
        "location": "https://example.com",
        "publicEndpoint": "https://example.com"
      },
      "space": "text"
    }
  ]
}

Get a specific integration's space installation

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

installationIdstringRequired

Identifier of the installation

spaceIdstringRequired

The unique id of the space

Query parameters

extendedbooleanOptional

If true, returns the space object in each items. If false, returns the space ID in each items.

Default: false

Responses

200

Integration space installation

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}

HTTPcURLJavaScriptPython

GET /v1/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "integration": "text",
  "installation": "text",
  "status": "active",
  "configuration": {},
  "externalIds": [
    "text"
  ],
  "urls": {
    "location": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "space": "text"
}

List installations on sites for an integration in an organization

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

installationIdstringRequired

Identifier of the installation

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

extendedbooleanOptional

If true, returns the site object in each items. If false, returns the site ID in each items.

Default: false

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/installations/{installationId}/sites

HTTPcURLJavaScriptPython

GET /v1/integrations/{integrationName}/installations/{installationId}/sites HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "integration": "text",
      "installation": "text",
      "status": "active",
      "configuration": {},
      "externalIds": [
        "text"
      ],
      "urls": {
        "location": "https://example.com",
        "publicEndpoint": "https://example.com"
      },
      "site": "text"
    }
  ]
}

Install integration on a site using an existing installation

post

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

installationIdstringRequired

Identifier of the installation

Query parameters

extendedbooleanOptional

If true, returns the site object in each items. If false, returns the site ID in each items.

Default: false

Body

application/json

siteIdstringRequired

ID of the site to install the integration on

Responses

201

Integration installed successfully on site

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

post

/integrations/{integrationName}/installations/{installationId}/sites

HTTPcURLJavaScriptPython

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

{
  "siteId": "text"
}

{
  "integration": "text",
  "installation": "text",
  "status": "active",
  "configuration": {},
  "externalIds": [
    "text"
  ],
  "urls": {
    "location": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "site": "text"
}

Get a specific integration's site installation

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

integrationNamestring · max: 100Required

Name of the integration.

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

installationIdstringRequired

Identifier of the installation

siteIdstringRequired

The unique id of the site

Query parameters

extendedbooleanOptional

If true, returns the site object in each items. If false, returns the site ID in each items.

Default: false

Responses

200

Integration site installation

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

get

/integrations/{integrationName}/installations/{installationId}/sites/{siteId}

HTTPcURLJavaScriptPython

GET /v1/integrations/{integrationName}/installations/{installationId}/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "integration": "text",
  "installation": "text",
  "status": "active",
  "configuration": {},
  "externalIds": [
    "text"
  ],
  "urls": {
    "location": "https://example.com",
    "publicEndpoint": "https://example.com"
  },
  "site": "text"
}

Get the status of an integration installation in an organization

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

integrationNamestring · max: 100Required

Name of the integration.

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

Responses

200

Integration installation status

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

get

/orgs/{organizationId}/integrations/{integrationName}/installation_status

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/integrations/{integrationName}/installation_status HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "active"
}

List the statuses of all integrations installed in an organization

get

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

searchstringOptional

A search string to filter integrations by name

Responses

200

List of integrations.

application/json

default

Unexpected Error

application/json

get

/orgs/{organizationId}/integrations/installations-status

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/integrations/installations-status HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "status": "active",
      "integration": {
        "object": "integration",
        "name": "text",
        "version": 1,
        "title": "text",
        "description": "text",
        "summary": "text",
        "previewImages": [
          "text"
        ],
        "target": "all",
        "verified": true,
        "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": {
            "properties": {
              "ANY_ADDITIONAL_PROPERTY": {
                "title": "text",
                "description": "text",
                "type": "string",
                "default": "text"
              }
            },
            "required": [
              "text"
            ]
          },
          "space": {
            "properties": {
              "ANY_ADDITIONAL_PROPERTY": {
                "title": "text",
                "description": "text",
                "type": "string",
                "default": "text"
              }
            },
            "required": [
              "text"
            ]
          },
          "site": {
            "properties": {
              "ANY_ADDITIONAL_PROPERTY": {
                "title": "text",
                "description": "text",
                "type": "string",
                "default": "text"
              }
            },
            "required": [
              "text"
            ]
          }
        },
        "externalLinks": [
          {
            "url": "https://example.com",
            "label": "text"
          }
        ],
        "owner": {
          "object": "organization",
          "id": "text",
          "title": "text",
          "createdAt": "2026-01-25T23:51:25.823Z",
          "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",
          "urls": {
            "location": "https://example.com",
            "app": "https://example.com",
            "logo": "https://example.com"
          },
          "trialDecision": "downgrade",
          "customHostname": "text",
          "blocked": {
            "reason": "security"
          },
          "internal_isUsingSnippets": true,
          "internal_isOnNewTrial": true,
          "permissions": {
            "admin": true,
            "createContent": 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"
      }
    }
  ]
}

List the scripts to embed in published content for a site.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

get

/orgs/{organizationId}/sites/{siteId}/integration-scripts

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/integration-scripts HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "script": "https://example.com",
    "contentSecurityPolicy": "text",
    "cookies": true
  }
]

List integrations enabled in a site.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

searchstringOptional

A search string to filter integrations by name

Responses

200

Listing of integrations enabled in the site.

application/json

default

Unexpected Error

application/json

get

/orgs/{organizationId}/sites/{siteId}/integrations

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/integrations HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "integration",
      "name": "text",
      "version": 1,
      "title": "text",
      "description": "text",
      "summary": "text",
      "previewImages": [
        "text"
      ],
      "target": "all",
      "verified": true,
      "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": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        },
        "space": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        },
        "site": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text"
            }
          },
          "required": [
            "text"
          ]
        }
      },
      "externalLinks": [
        {
          "url": "https://example.com",
          "label": "text"
        }
      ],
      "owner": {
        "object": "organization",
        "id": "text",
        "title": "text",
        "createdAt": "2026-01-25T23:51:25.823Z",
        "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",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "logo": "https://example.com"
        },
        "trialDecision": "downgrade",
        "customHostname": "text",
        "blocked": {
          "reason": "security"
        },
        "internal_isUsingSnippets": true,
        "internal_isOnNewTrial": true,
        "permissions": {
          "admin": true,
          "createContent": 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"
    }
  ]
}