Site context

Manage context records, connections, and topics for a docs site.

Manage the contextual records and topics used by your site to power AI experiences and insights.

List all context records

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

typestring · enumOptional

Filter context records by type.

Possible values:

connectorone ofOptional

Filter context records by connector type.

stringOptional

Integration source

Pattern: ^integration:[^:]+$

or

string · enumOptional

Builtin sources

Possible values:

connectionstringOptional

Filter context records by connection id.

topicstringOptional

Filter context records by associated site topic ID.

Responses

200

OK

application/json

get

/orgs/{organizationId}/sites/{siteId}/context-records

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "context-record",
      "id": "text",
      "title": "text",
      "description": "text",
      "type": "ticket",
      "createdAt": "2026-03-18T12:39:39.497Z",
      "processedAt": "2026-03-18T12:39:39.497Z",
      "connection": "text",
      "connector": "text",
      "topics": [
        "text"
      ],
      "urls": {
        "location": "https://example.com",
        "source": "https://example.com"
      }
    }
  ]
}

Create or update context records

put

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Bodyobject[]

application/json

Input to ingest a new context record

idstringRequired

Unique local identifier for the record

typestring · enumRequiredPossible values:

titlestring · min: 1 · max: 256Required

Title for the context record

descriptionstring · max: 512Optional

Optional short description of the context record

bodystringRequired

Body content of the record as markdown

urlstring · uriOptional

URL of the record

createdAtstring · date-timeOptional

Date of the record creation in the original source

Responses

204

The context records have been created or updated

put

/orgs/{organizationId}/sites/{siteId}/context-records

HTTPcURLJavaScriptPython

PUT /v1/orgs/{organizationId}/sites/{siteId}/context-records HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 194

[
  {
    "id": "text",
    "type": "ticket",
    "title": "text",
    "description": "text",
    "body": "text",
    "url": "https://example.com",
    "createdAt": "2026-03-18T12:39:39.497Z",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }
]

204

The context records have been created or updated

No content

Get a context record

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteContextRecordIdstringRequired

The unique id of the context record

Responses

200

OK

application/json

objectstring · enumRequiredPossible values:

idstringRequired

The ID of the record

titlestring · min: 1 · max: 256Required

Title for the context record

descriptionstring · max: 512Optional

Optional short description of the context record

typestring · enumRequiredPossible values:

createdAtstring · date-timeRequired

processedAtstring · date-timeOptional

connectionstringRequired

The connection ID associated with the record

connectorone ofRequired

The connector type associated with the record

stringOptional

Integration source

Pattern: ^integration:[^:]+$

or

string · enumOptional

Builtin sources

Possible values:

topicsstring[]Optional

The associated topics of the record

get

/orgs/{organizationId}/sites/{siteId}/context-records/{siteContextRecordId}

HTTPcURLJavaScriptPython

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

200

OK

{
  "object": "context-record",
  "id": "text",
  "title": "text",
  "description": "text",
  "type": "ticket",
  "createdAt": "2026-03-18T12:39:39.497Z",
  "processedAt": "2026-03-18T12:39:39.497Z",
  "connection": "text",
  "connector": "text",
  "topics": [
    "text"
  ],
  "urls": {
    "location": "https://example.com",
    "source": "https://example.com"
  }
}

List all site scans

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

topicstringOptional

Filter scans by associated site topic ID.

statusstring · enumOptional

Status of a persisted site scan.

Possible values:

Responses

200

OK

application/json

get

/orgs/{organizationId}/sites/{siteId}/scans

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-scan",
      "id": "text",
      "status": "pending",
      "topic": "text",
      "createdAt": "2026-03-18T12:39:39.497Z",
      "startedAt": "2026-03-18T12:39:39.497Z",
      "finishedAt": "2026-03-18T12:39:39.497Z",
      "findings": {
        "low": 1,
        "medium": 1,
        "high": 1
      },
      "failureMessage": "text",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

Enqueue a new site scan

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Body

application/json

topicstringRequired

The site topic ID to scan.

Responses

202

Site scan has been enqueued

application/json

post

/orgs/{organizationId}/sites/{siteId}/scans

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/scans HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "topic": "text"
}

202

Site scan has been enqueued

{
  "object": "site-scan",
  "id": "text",
  "status": "pending",
  "topic": "text",
  "createdAt": "2026-03-18T12:39:39.497Z",
  "startedAt": "2026-03-18T12:39:39.497Z",
  "finishedAt": "2026-03-18T12:39:39.497Z",
  "findings": {
    "low": 1,
    "medium": 1,
    "high": 1
  },
  "failureMessage": "text",
  "urls": {
    "location": "https://example.com"
  }
}

Get a site scan by ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteScanIdstringRequired

The unique id of the site scan

Responses

200

OK

application/json

objectstring · enumRequiredPossible values:

idstringRequired

The ID of the scan

statusstring · enumRequired

Status of a persisted site scan.

Possible values:

topicstringRequired

The site topic ID associated with the scan

createdAtstring · date-timeRequired

startedAtstring · date-timeOptional

finishedAtstring · date-timeOptional

failureMessagestringOptional

Failure message for failed scans

get

/orgs/{organizationId}/sites/{siteId}/scans/{siteScanId}

HTTPcURLJavaScriptPython

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

200

OK

{
  "object": "site-scan",
  "id": "text",
  "status": "pending",
  "topic": "text",
  "createdAt": "2026-03-18T12:39:39.497Z",
  "startedAt": "2026-03-18T12:39:39.497Z",
  "finishedAt": "2026-03-18T12:39:39.497Z",
  "findings": {
    "low": 1,
    "medium": 1,
    "high": 1
  },
  "failureMessage": "text",
  "urls": {
    "location": "https://example.com"
  }
}

List all site context findings

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

topicstringOptional

Filter findings by associated site topic ID.

statusstring · enumOptional

Status of a site finding.

Possible values:

typestring · enumOptional

Classification of a site finding:

• Outdated content: The content is no longer up to date with external context and may be misleading or incorrect.
• Incoherent content: The content contains information that is inconsistent or contradictory.
• Content gap: The content is missing important information that should be present to answer user questions effectively.
• Other: Any other type of finding not covered by the above categories.

Possible values:

severitystring · enumOptional

Estimated end-user severity of a site finding.

Possible values:

Responses

200

OK

application/json

get

/orgs/{organizationId}/sites/{siteId}/findings

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-finding",
      "id": "text",
      "scan": "text",
      "topic": "text",
      "title": "text",
      "changeRequests": 1,
      "pages": 1,
      "records": 1,
      "questions": 1,
      "status": "open",
      "type": "content-outdated",
      "severity": "low",
      "description": {
        "object": "document",
        "data": {
          "schemaVersion": 1,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "nodes": [
          "[Circular Reference]"
        ],
        "meta": {
          "token": "text"
        }
      },
      "autoFixable": true,
      "createdAt": "2026-03-18T12:39:39.497Z",
      "updatedAt": "2026-03-18T12:39:39.497Z",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

Get a site finding by ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteFindingIdstringRequired

The unique id of the site finding

Responses

200

OK

application/json

objectstring · enumRequiredPossible values:

idstringRequired

The ID of the finding

scanstringRequired

The site scan ID associated with the finding

topicstringRequired

The site topic ID associated with the finding

titlestring · max: 256Required

Short finding title

changeRequestsnumberRequired

Number of change requests linked to the finding

pagesnumberRequired

Number of pages linked to the finding

recordsnumberRequired

Number of records linked to the finding

questionsnumberRequired

Number of questions linked to the finding

statusstring · enumRequired

Status of a site finding.

Possible values:

typestring · enumRequired

Classification of a site finding:

• Outdated content: The content is no longer up to date with external context and may be misleading or incorrect.
• Incoherent content: The content contains information that is inconsistent or contradictory.
• Content gap: The content is missing important information that should be present to answer user questions effectively.
• Other: Any other type of finding not covered by the above categories.

Possible values:

severitystring · enumRequired

Estimated end-user severity of a site finding.

Possible values:

autoFixablebooleanRequired

Whether an AI agent should be able to fix this finding directly

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

get

/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}

HTTPcURLJavaScriptPython

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

200

OK

{
  "object": "site-finding",
  "id": "text",
  "scan": "text",
  "topic": "text",
  "title": "text",
  "changeRequests": 1,
  "pages": 1,
  "records": 1,
  "questions": 1,
  "status": "open",
  "type": "content-outdated",
  "severity": "low",
  "description": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  },
  "autoFixable": true,
  "createdAt": "2026-03-18T12:39:39.497Z",
  "updatedAt": "2026-03-18T12:39:39.497Z",
  "urls": {
    "location": "https://example.com"
  }
}

Update a site finding

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteFindingIdstringRequired

The unique id of the site finding

Body

application/json

statusstring · enumRequiredPossible values:

Responses

200

OK

application/json

objectstring · enumRequiredPossible values:

idstringRequired

The ID of the finding

scanstringRequired

The site scan ID associated with the finding

topicstringRequired

The site topic ID associated with the finding

titlestring · max: 256Required

Short finding title

changeRequestsnumberRequired

Number of change requests linked to the finding

pagesnumberRequired

Number of pages linked to the finding

recordsnumberRequired

Number of records linked to the finding

questionsnumberRequired

Number of questions linked to the finding

statusstring · enumRequired

Status of a site finding.

Possible values:

typestring · enumRequired

Classification of a site finding:

• Outdated content: The content is no longer up to date with external context and may be misleading or incorrect.
• Incoherent content: The content contains information that is inconsistent or contradictory.
• Content gap: The content is missing important information that should be present to answer user questions effectively.
• Other: Any other type of finding not covered by the above categories.

Possible values:

severitystring · enumRequired

Estimated end-user severity of a site finding.

Possible values:

autoFixablebooleanRequired

Whether an AI agent should be able to fix this finding directly

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

patch

/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "status": "open"
}

200

OK

{
  "object": "site-finding",
  "id": "text",
  "scan": "text",
  "topic": "text",
  "title": "text",
  "changeRequests": 1,
  "pages": 1,
  "records": 1,
  "questions": 1,
  "status": "open",
  "type": "content-outdated",
  "severity": "low",
  "description": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  },
  "autoFixable": true,
  "createdAt": "2026-03-18T12:39:39.497Z",
  "updatedAt": "2026-03-18T12:39:39.497Z",
  "urls": {
    "location": "https://example.com"
  }
}

List change requests linked to a site finding

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteFindingIdstringRequired

The unique id of the site finding

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

List of change requests linked to the site finding

application/json

get

/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/change-requests

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/change-requests HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of change requests linked to the site finding

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "change-request",
      "id": "text",
      "number": 1,
      "status": "draft",
      "subject": "text",
      "description": {
        "object": "document",
        "data": {
          "schemaVersion": 1,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "nodes": [
          "[Circular Reference]"
        ],
        "meta": {
          "token": "text"
        }
      },
      "createdBy": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2026-03-18T12:39:39.497Z",
      "updatedAt": "2026-03-18T12:39:39.497Z",
      "space": "text",
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 1,
      "outdated": true,
      "urls": {
        "app": "https://example.com",
        "location": "https://example.com"
      }
    }
  ]
}

Process a site finding into change requests

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteFindingIdstringRequired

The unique id of the site finding

Responses

202

Site finding processing has been started

post

/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/change-requests

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/change-requests HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

202

Site finding processing has been started

No content

List pages linked to a site finding

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteFindingIdstringRequired

The unique id of the site finding

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

List of pages linked to the site finding

application/json

get

/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/pages

HTTPcURLJavaScriptPython

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

200

List of pages linked to the site finding

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-finding-page",
      "spaceId": "text",
      "page": {
        "id": "text",
        "type": "document",
        "title": "text",
        "path": "text"
      }
    }
  ]
}

List questions linked to a site finding

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteFindingIdstringRequired

The unique id of the site finding

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

List of questions linked to the site finding

application/json

get

/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/questions

HTTPcURLJavaScriptPython

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

200

List of questions linked to the site finding

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-question",
      "id": "text",
      "question": "text",
      "type": "exploring",
      "createdAt": "2026-03-18T12:39:39.497Z",
      "stats": {
        "total": 1,
        "answers": 1,
        "feedback": {
          "positive": 1,
          "negative": 1,
          "unrated": 1
        },
        "answered": {
          "yes": 1,
          "partially": 1,
          "no": 1
        },
        "relevance": {
          "relevant": 1,
          "spam": 1,
          "off-topic": 1,
          "unclear": 1
        },
        "types": {
          "exploring": 1,
          "how-to": 1,
          "troubleshooting": 1,
          "reference": 1,
          "unknown": 1
        },
        "channelTypes": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "channels": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "weeklyPulse": [
          1
        ]
      },
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

List records linked to a site finding

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteFindingIdstringRequired

The unique id of the site finding

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

List of records linked to the site finding

application/json

get

/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/records

HTTPcURLJavaScriptPython

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

200

List of records linked to the site finding

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "context-record",
      "id": "text",
      "title": "text",
      "description": "text",
      "type": "ticket",
      "createdAt": "2026-03-18T12:39:39.497Z",
      "processedAt": "2026-03-18T12:39:39.497Z",
      "connection": "text",
      "connector": "text",
      "topics": [
        "text"
      ],
      "urls": {
        "location": "https://example.com",
        "source": "https://example.com"
      }
    }
  ]
}

List all context connections

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

get

/orgs/{organizationId}/sites/{siteId}/context-connections

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "context-connection",
      "id": "text",
      "createdAt": "2026-03-18T12:39:39.497Z",
      "syncedAt": "2026-03-18T12:39:39.497Z",
      "label": "text",
      "status": "pending",
      "records": 1,
      "failureMessage": "text",
      "email": {
        "ingestionAddress": "[e-mail]"
      },
      "usageSettings": {
        "changeRequests": true,
        "search": true,
        "searchBoost": "x0.8"
      },
      "urls": {
        "location": "https://example.com"
      },
      "connector": "builtin:email"
    }
  ]
}

Create a context connection

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Body

application/json

anyOptional

or

or

or

or

or

or

or

and

Responses

201

Created connection

application/json

post

/orgs/{organizationId}/sites/{siteId}/context-connections

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/context-connections HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "connector": "builtin:email",
  "usageSettings": {
    "changeRequests": true,
    "search": true,
    "searchBoost": "x0.8"
  }
}

201

Created connection

{
  "object": "context-connection",
  "id": "text",
  "createdAt": "2026-03-18T12:39:39.497Z",
  "syncedAt": "2026-03-18T12:39:39.497Z",
  "label": "text",
  "status": "pending",
  "records": 1,
  "failureMessage": "text",
  "email": {
    "ingestionAddress": "[e-mail]"
  },
  "usageSettings": {
    "changeRequests": true,
    "search": true,
    "searchBoost": "x0.8"
  },
  "urls": {
    "location": "https://example.com"
  },
  "connector": "builtin:email"
}

Get a context connection

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteContextConnectionIdstringRequired

The unique id of the context connection

Responses

200

OK

application/json

and

anyOptional

or

or

or

or

or

or

or

get

/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}

HTTPcURLJavaScriptPython

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

200

OK

{
  "object": "context-connection",
  "id": "text",
  "createdAt": "2026-03-18T12:39:39.497Z",
  "syncedAt": "2026-03-18T12:39:39.497Z",
  "label": "text",
  "status": "pending",
  "records": 1,
  "failureMessage": "text",
  "email": {
    "ingestionAddress": "[e-mail]"
  },
  "usageSettings": {
    "changeRequests": true,
    "search": true,
    "searchBoost": "x0.8"
  },
  "urls": {
    "location": "https://example.com"
  },
  "connector": "builtin:email"
}

Delete a context connection

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteContextConnectionIdstringRequired

The unique id of the context connection

Responses

204

Context connection did not exist

205

Context connection deleted

delete

/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a context connection

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteContextConnectionIdstringRequired

The unique id of the context connection

Body

application/json

anyOptional

or

or

or

or

or

or

or

or

Responses

200

OK

application/json

and

anyOptional

or

or

or

or

or

or

or

patch

/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "connector": "builtin:email"
}

200

OK

{
  "object": "context-connection",
  "id": "text",
  "createdAt": "2026-03-18T12:39:39.497Z",
  "syncedAt": "2026-03-18T12:39:39.497Z",
  "label": "text",
  "status": "pending",
  "records": 1,
  "failureMessage": "text",
  "email": {
    "ingestionAddress": "[e-mail]"
  },
  "usageSettings": {
    "changeRequests": true,
    "search": true,
    "searchBoost": "x0.8"
  },
  "urls": {
    "location": "https://example.com"
  },
  "connector": "builtin:email"
}

Trigger a sync for a context connection

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteContextConnectionIdstringRequired

The unique id of the context connection

Responses

204

Sync started

400

Connection was synced less than an hour ago or invalid connector

application/json

post

/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}/sync

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}/sync HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List all topics

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Query parameters

fromstring · date-timeOptional

Filter stats to answers created at or after this timestamp.

tostring · date-timeOptional

Filter stats to answers created at or before this timestamp.

Responses

200

OK

application/json

get

/orgs/{organizationId}/sites/{siteId}/topics

HTTPcURLJavaScriptPython

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

200

OK

{
  "items": [
    {
      "object": "context-topic",
      "id": "text",
      "label": "text",
      "parent": {
        "id": "text",
        "label": "text"
      },
      "createdAt": "2026-03-18T12:39:39.497Z",
      "updatedAt": "2026-03-18T12:39:39.497Z",
      "icon": "gear",
      "summary": {
        "object": "document",
        "data": {
          "schemaVersion": 1,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "nodes": [
          "[Circular Reference]"
        ],
        "meta": {
          "token": "text"
        }
      },
      "usageSettings": {
        "changeRequests": true
      },
      "pages": 1,
      "records": 1,
      "questions": {
        "total": 1,
        "answers": 1,
        "feedback": {
          "positive": 1,
          "negative": 1,
          "unrated": 1
        },
        "answered": {
          "yes": 1,
          "partially": 1,
          "no": 1
        },
        "relevance": {
          "relevant": 1,
          "spam": 1,
          "off-topic": 1,
          "unclear": 1
        },
        "types": {
          "exploring": 1,
          "how-to": 1,
          "troubleshooting": 1,
          "reference": 1,
          "unknown": 1
        },
        "channelTypes": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "channels": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "weeklyPulse": [
          1
        ]
      },
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

Get a topic

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteTopicIdstringRequired

The unique id of the topic

Responses

200

OK

application/json

objectstring · enumRequiredPossible values:

idstringRequired

The ID of the topic

labelstringRequired

The label of the topic

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

iconstring · icon · max: 50Required

Name of the icon

Example: gear

pagesnumberRequired

The number of pages associated with the topic

recordsnumberRequired

The number of records in the topic

get

/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}

HTTPcURLJavaScriptPython

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

200

OK

{
  "object": "context-topic",
  "id": "text",
  "label": "text",
  "parent": {
    "id": "text",
    "label": "text"
  },
  "createdAt": "2026-03-18T12:39:39.497Z",
  "updatedAt": "2026-03-18T12:39:39.497Z",
  "icon": "gear",
  "summary": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  },
  "usageSettings": {
    "changeRequests": true
  },
  "pages": 1,
  "records": 1,
  "questions": {
    "total": 1,
    "answers": 1,
    "feedback": {
      "positive": 1,
      "negative": 1,
      "unrated": 1
    },
    "answered": {
      "yes": 1,
      "partially": 1,
      "no": 1
    },
    "relevance": {
      "relevant": 1,
      "spam": 1,
      "off-topic": 1,
      "unclear": 1
    },
    "types": {
      "exploring": 1,
      "how-to": 1,
      "troubleshooting": 1,
      "reference": 1,
      "unknown": 1
    },
    "channelTypes": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "channels": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "weeklyPulse": [
      1
    ]
  },
  "urls": {
    "location": "https://example.com"
  }
}

Update a topic

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteTopicIdstringRequired

The unique id of the topic

Body

application/json

Responses

200

OK

application/json

objectstring · enumRequiredPossible values:

idstringRequired

The ID of the topic

labelstringRequired

The label of the topic

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

iconstring · icon · max: 50Required

Name of the icon

Example: gear

pagesnumberRequired

The number of pages associated with the topic

recordsnumberRequired

The number of records in the topic

patch

/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "usageSettings": {
    "changeRequests": true
  }
}

200

OK

{
  "object": "context-topic",
  "id": "text",
  "label": "text",
  "parent": {
    "id": "text",
    "label": "text"
  },
  "createdAt": "2026-03-18T12:39:39.497Z",
  "updatedAt": "2026-03-18T12:39:39.497Z",
  "icon": "gear",
  "summary": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  },
  "usageSettings": {
    "changeRequests": true
  },
  "pages": 1,
  "records": 1,
  "questions": {
    "total": 1,
    "answers": 1,
    "feedback": {
      "positive": 1,
      "negative": 1,
      "unrated": 1
    },
    "answered": {
      "yes": 1,
      "partially": 1,
      "no": 1
    },
    "relevance": {
      "relevant": 1,
      "spam": 1,
      "off-topic": 1,
      "unclear": 1
    },
    "types": {
      "exploring": 1,
      "how-to": 1,
      "troubleshooting": 1,
      "reference": 1,
      "unknown": 1
    },
    "channelTypes": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "channels": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "weeklyPulse": [
      1
    ]
  },
  "urls": {
    "location": "https://example.com"
  }
}

Delete all findings for a topic

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

siteTopicIdstringRequired

The unique id of the topic

Responses

204

Topic had no findings or did not exist

205

Topic findings deleted

delete

/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}/findings

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}/findings HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content