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

mutedbooleanRequired

Whether the cluster is muted for change request creation

impactstring · enumRequired

Estimated end-user impact of a conversation issue.

• low: Minor friction or small polish issues; users can proceed with little to no guidance.
• medium: Noticeable friction or partial blocking; users can proceed with workarounds or extra guidance.
• high: Fully or near-fully blocking, severe regression, repeated failures, or risk of data loss; no viable workaround.

Possible values:

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-12-16T13:51:34.099Z",
  "updatedAt": "2025-12-16T13:51:34.099Z",
  "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"
    }
  },
  "muted": true,
  "impact": "low",
  "weeklyPulse": [
    1
  ],
  "sources": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "stats": {
    "issues": 1,
    "conversations": 1
  },
  "urls": {
    "location": "https://example.com"
  }
}

List conversations issues clusters

get

Authorizations

user

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

orderstring · enumOptional

An order for the items in the list

Default: descPossible values:

orderBystring · enumOptionalDefault: updatedAtPossible values:

Responses

200

OK

application/json

404

Not Found

application/json

get

/orgs/{organizationId}/conversations-clusters

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-12-16T13:51:34.099Z",
      "updatedAt": "2025-12-16T13:51:34.099Z",
      "icon": "gear",
      "summary": {
        "object": "document",
        "data": {
          "schemaVersion": 1,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "nodes": [
          "[Circular Reference]"
        ],
        "meta": {
          "token": "text"
        }
      },
      "muted": true,
      "impact": "low",
      "weeklyPulse": [
        1
      ],
      "sources": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "stats": {
        "issues": 1,
        "conversations": 1
      },
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

Get a conversations issues cluster by its identifier

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

clusterIdstringRequired

The unique id of the cluster

Responses

200

OK

application/json

get

/orgs/{organizationId}/conversations-clusters/{clusterId}

HTTPcURLJavaScriptPython

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

200

OK

{
  "object": "issues-cluster",
  "id": "text",
  "label": "text",
  "createdAt": "2025-12-16T13:51:34.099Z",
  "updatedAt": "2025-12-16T13:51:34.099Z",
  "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"
    }
  },
  "muted": true,
  "impact": "low",
  "weeklyPulse": [
    1
  ],
  "sources": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "stats": {
    "issues": 1,
    "conversations": 1
  },
  "urls": {
    "location": "https://example.com"
  }
}

Update a conversations issues cluster

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

clusterIdstringRequired

The unique id of the cluster

Body

application/json

mutedbooleanRequired

Whether the cluster is muted for change request creation

Responses

200

OK

application/json

patch

/orgs/{organizationId}/conversations-clusters/{clusterId}

HTTPcURLJavaScriptPython

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

{
  "muted": true
}

200

OK

{
  "object": "issues-cluster",
  "id": "text",
  "label": "text",
  "createdAt": "2025-12-16T13:51:34.099Z",
  "updatedAt": "2025-12-16T13:51:34.099Z",
  "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"
    }
  },
  "muted": true,
  "impact": "low",
  "weeklyPulse": [
    1
  ],
  "sources": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "stats": {
    "issues": 1,
    "conversations": 1
  },
  "urls": {
    "location": "https://example.com"
  }
}

List conversations

get

Authorizations

user

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

sourcestringOptional

Filter conversations by their source identifier

Responses

200

OK

application/json

get

/orgs/{organizationId}/conversations

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-12-16T13:51:34.099Z",
      "processedAt": "2025-12-16T13:51:34.099Z",
      "source": "text",
      "impact": "low",
      "urls": {
        "location": "https://example.com",
        "source": "https://example.com"
      }
    }
  ]
}

Ingest conversations

post

Authorizations

integration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Body

application/json

or

Responses

204

Conversations ingested

No content

post

/orgs/{organizationId}/conversations

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-12-16T13:51:34.099Z"
  },
  "subject": "text",
  "parts": [
    {
      "type": "message",
      "role": "user",
      "body": "text"
    }
  ]
}

204

Conversations ingested

No content

List conversation issues

get

Authorizations

user

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

clusterstringOptional

Filter conversation issues by cluster identifier.

conversationstringOptional

Filter conversation issues by conversation identifier.

Responses

200

OK

application/json

get

/orgs/{organizationId}/conversations-issues

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",
        "details": {
          "object": "document",
          "data": {
            "schemaVersion": 1,
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "nodes": "[Circular Reference]",
          "meta": {
            "token": "text"
          }
        },
        "impact": "low",
        "createdAt": "2025-12-16T13:51:34.099Z",
        "ingestedAt": "2025-12-16T13:51:34.099Z",
        "conversation": "text",
        "cluster": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "conversation": {
        "object": "conversation",
        "id": "text",
        "subject": "text",
        "createdAt": "2025-12-16T13:51:34.099Z",
        "processedAt": "2025-12-16T13:51:34.099Z",
        "source": "text",
        "impact": "low",
        "urls": {
          "location": "https://example.com",
          "source": "https://example.com"
        }
      }
    }
  ]
}

Get a conversation issue by ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/orgs/{organizationId}/conversations-issues/{issueId}

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",
    "details": {
      "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"
      }
    },
    "impact": "low",
    "createdAt": "2025-12-16T13:51:34.099Z",
    "ingestedAt": "2025-12-16T13:51:34.099Z",
    "conversation": "text",
    "cluster": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "conversation": {
    "object": "conversation",
    "id": "text",
    "subject": "text",
    "createdAt": "2025-12-16T13:51:34.099Z",
    "processedAt": "2025-12-16T13:51:34.099Z",
    "source": "text",
    "impact": "low",
    "urls": {
      "location": "https://example.com",
      "source": "https://example.com"
    }
  }
}

Get a conversation by ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/orgs/{organizationId}/conversations/{conversationId}

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-12-16T13:51:34.099Z",
    "processedAt": "2025-12-16T13:51:34.099Z",
    "source": "text",
    "impact": "low",
    "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-12-16T13:51:34.099Z"
  }
}