Conversations

Ingest knowledge for Conversations.

The Conversations endpoints let you ingest, manage, and monitor Conversations in GitBook to be processed by Docs Agents.

The ConversationsIssuesCluster object

Attributes

objectstring · enumRequiredPossible values:

idstringRequired

The ID of the conversations issues cluster

labelstringRequired

The label of the conversations issues cluster

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

iconstring · icon · max: 50Required

Name of the icon

Example: gear

summarystringRequired

The summary of the conversations issues cluster

weeklyPulsenumber[] · min: 13 · max: 13Required

The weekly pulse of the conversations issues cluster for the past 3 months

The ConversationsIssuesCluster object

{
  "object": "issues-cluster",
  "id": "text",
  "label": "text",
  "createdAt": "2025-10-24T19:46:05.903Z",
  "updatedAt": "2025-10-24T19:46:05.903Z",
  "icon": "gear",
  "summary": "text",
  "weeklyPulse": [
    1
  ],
  "sources": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "stats": {
    "issues": 1,
    "conversations": 1,
    "tasksTotal": 1,
    "tasksBacklog": 1,
    "tasksStarted": 1,
    "tasksCompleted": 1,
    "tasksCancelled": 1
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

List conversations issues clusters

get

Authorizations

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

orderstring · enumOptional

An order for the items in the list

Default: descPossible values:

orderBystring · enumOptionalDefault: updatedAtPossible values:

statusstring · enumOptional

Filter by status

Possible values:

Responses

200

OK

application/json

Responseall of

404

Not Found

application/json

get

HTTPcURLJavaScriptPython

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

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "issues-cluster",
      "id": "text",
      "label": "text",
      "createdAt": "2025-10-24T19:46:05.903Z",
      "updatedAt": "2025-10-24T19:46:05.903Z",
      "icon": "gear",
      "summary": "text",
      "weeklyPulse": [
        1
      ],
      "sources": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "stats": {
        "issues": 1,
        "conversations": 1,
        "tasksTotal": 1,
        "tasksBacklog": 1,
        "tasksStarted": 1,
        "tasksCompleted": 1,
        "tasksCancelled": 1
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

List conversations

get

Authorizations

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

sourcestringOptional

Filter conversations by their source identifier

Responses

200

OK

application/json

Responseall of

get

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "conversation",
      "id": "text",
      "subject": "text",
      "createdAt": "2025-10-24T19:46:05.903Z",
      "processedAt": "2025-10-24T19:46:05.903Z",
      "source": "text",
      "urls": {
        "location": "https://example.com",
        "source": "https://example.com"
      }
    }
  ]
}

Ingest conversations

post

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

Body

one ofOptional

or

Responses

204

Conversations ingested

post

HTTPcURLJavaScriptPython

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

{
  "id": "text",
  "metadata": {
    "url": "text",
    "attributes": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "createdAt": "2025-10-24T19:46:05.903Z"
  },
  "subject": "text",
  "parts": [
    {
      "type": "message",
      "role": "user",
      "body": "text"
    }
  ]
}

204

Conversations ingested

No content

List conversation issues

get

Authorizations

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

clusterstringOptional

Filter conversation issues by cluster identifier.

conversationstringOptional

Filter conversation issues by conversation identifier.

Responses

200

OK

application/json

Responseall of

get

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "issue": {
        "object": "conversation-issue",
        "id": "text",
        "title": "text",
        "summary": "text",
        "createdAt": "2025-10-24T19:46:05.903Z",
        "ingestedAt": "2025-10-24T19:46:05.903Z",
        "conversation": "text",
        "cluster": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "conversation": {
        "object": "conversation",
        "id": "text",
        "subject": "text",
        "createdAt": "2025-10-24T19:46:05.903Z",
        "processedAt": "2025-10-24T19:46:05.903Z",
        "source": "text",
        "urls": {
          "location": "https://example.com",
          "source": "https://example.com"
        }
      }
    }
  ]
}

Get a conversation issue by ID

get

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

issueIdstringRequired

Identifier of the conversation issue

Responses

200

OK

application/json

404

Conversation issue not found

application/json

get

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/conversations-issues/{issueId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "issue": {
    "object": "conversation-issue",
    "id": "text",
    "title": "text",
    "summary": "text",
    "createdAt": "2025-10-24T19:46:05.903Z",
    "ingestedAt": "2025-10-24T19:46:05.903Z",
    "conversation": "text",
    "cluster": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "conversation": {
    "object": "conversation",
    "id": "text",
    "subject": "text",
    "createdAt": "2025-10-24T19:46:05.903Z",
    "processedAt": "2025-10-24T19:46:05.903Z",
    "source": "text",
    "urls": {
      "location": "https://example.com",
      "source": "https://example.com"
    }
  }
}

Get a conversation by ID

get

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

conversationIdstringRequired

Identifier of the conversation

Responses

200

OK

application/json

404

Conversation not found

application/json

get

HTTPcURLJavaScriptPython

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

{
  "conversation": {
    "object": "conversation",
    "id": "text",
    "subject": "text",
    "createdAt": "2025-10-24T19:46:05.903Z",
    "processedAt": "2025-10-24T19:46:05.903Z",
    "source": "text",
    "urls": {
      "location": "https://example.com",
      "source": "https://example.com"
    }
  },
  "parts": [
    {
      "type": "message",
      "role": "user",
      "body": "text"
    }
  ],
  "metadata": {
    "url": "text",
    "attributes": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "createdAt": "2025-10-24T19:46:05.903Z"
  }
}