API conventions

These rules apply to every endpoint in SiteGPT API v2.

Base URL

https://sitegpt.ai/api/v2

Send and receive JSON. Set Content-Type: application/json on requests with a body.
Send your API token in the Authorization: Bearer header. See API v2 authentication.
GET /api/v2/health needs no token. Use it to check that the API is reachable.
The OpenAPI document is at https://sitegpt.ai/api/v2/openapi.json.

Response envelope

Every response uses the same envelope. Success:

{
  "ok": true,
  "data": { },
  "meta": {
    "requestId": "YOUR_REQUEST_ID"
  }
}

Error:

{
  "ok": false,
  "error": {
    "code": "TOKEN_SCOPE_NOT_ALLOWED",
    "message": "Token does not have the required scope",
    "hint": "..."
  },
  "meta": {
    "requestId": "YOUR_REQUEST_ID"
  }
}

Field	Description
`ok`	`true` on success, `false` on error.
`data`	The result. Its shape depends on the endpoint.
`meta.requestId`	The ID of the request. Give it to support when you report a problem. If you send an `x-request-id` header with 1 to 64 letters, digits, `_`, or `-`, SiteGPT uses its value.
`meta.warnings`	Optional. Messages about the request that did not stop it, for example a deprecated credential.
`meta.nextCursor`	On list endpoints. The cursor for the next page. See Pagination.
`error.code`	A stable code in capital letters. Use it in your code.
`error.message`	A readable message. It can change. Do not match on it.
`error.hint`	Optional. A suggested next step.
`error.details`	Optional. More detail, for example the fields that failed validation, or `requiredScopes` for `TOKEN_SCOPE_NOT_ALLOWED`.

The OpenAPI error schema does not list error.hint, but the API sends it. Allow extra fields in your error parser.

Pagination

List endpoints that can return many items use cursor pagination.

Query parameter	Description
`limit`	The maximum number of items to return. At least `1`.
`cursor`	The cursor from the previous page. Leave it out for the first page.

The response has the cursor in two places:

meta.nextCursor
data.pagination, which has limit, hasNextPage, and nextCursor

nextCursor is null on the last page.

# First page
curl "https://sitegpt.ai/api/v2/chatbots/YOUR_CHATBOT_ID/conversations?limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Next page
curl "https://sitegpt.ai/api/v2/chatbots/YOUR_CHATBOT_ID/conversations?limit=50&cursor=YOUR_NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

These endpoints use cursor pagination:

Endpoint	Default `limit`	Maximum `limit`
Conversations: `GET /chatbots/{chatbotId}/conversations`	50	100
Messages in a conversation: `GET /chatbots/{chatbotId}/conversations/{threadId}/messages`	100	500
Leads: `GET /chatbots/{chatbotId}/leads`	50	100
Content documents: `GET /chatbots/{chatbotId}/documents`	50	100
Sync jobs: `GET /chatbots/{chatbotId}/ingest-jobs`	50	100
Documents of a connected source: `GET /chatbots/{chatbotId}/knowledge/sources/{connectionId}/documents`	50	100
Confluence spaces and pages: `GET /chatbots/{chatbotId}/knowledge/sources/confluence/spaces` and `.../confluence/pages`	20	100

A limit outside the allowed range returns 400 VALIDATION_FAILED.

Errors

The HTTP status tells you the kind of error. error.code tells you the exact cause.

Status	Meaning	Common codes
400	The request is not valid.	`INVALID_JSON`, `VALIDATION_FAILED`, `CONFIRMATION_REQUIRED`
401	The request has no valid credential.	`AUTHORIZATION_HEADER_REQUIRED`, `AUTHORIZATION_HEADER_NOT_VALID`, `TOKEN_NOT_VALID`
403	The credential cannot do this, or your plan does not include it.	`TOKEN_SCOPE_NOT_ALLOWED`, `PLAN_UPGRADE_REQUIRED`, `HUMAN_TAKEOVER`, `CHATBOT_LIMIT_REACHED`, `ACCOUNT_INACTIVE`, `ANALYTICS_LOCKED`, `WEBHOOKS_NOT_AVAILABLE`
404	The item does not exist, or the token cannot access it. Unknown API paths also return `404`.	`CHATBOT_NOT_FOUND`, `NOT_FOUND`
405	The endpoint does not support this HTTP method.	`METHOD_NOT_ALLOWED`
409	The conversation state does not allow the action.	`CONVERSATION_CLOSED`
429	A plan quota is used up.	`CHATBOT_PAGES_LIMIT_REACHED`
500	An error on the SiteGPT side.	`INTERNAL_SERVER_ERROR`

A 401 response includes a WWW-Authenticate header that points to the OAuth metadata at https://sitegpt.ai/.well-known/oauth-protected-resource/api/v2. Some errors come with a hint. For example, CHATBOT_LIMIT_REACHED and CHATBOT_PAGES_LIMIT_REACHED suggest how to free space or where to see plans.

Conversation state conflicts

A conversation can be resolved (closed), or a person on your team can take it over. The API checks these states at the moment it saves your change. If the state changes while your request runs, the new state wins. See Conversations and handoff.

Situation	Operation	Result
The conversation is resolved	Send a message (`POST .../conversations/{threadId}/messages`)	`409 CONVERSATION_CLOSED`
The conversation is resolved	Escalate (`POST .../conversations/{threadId}/escalate`)	`409 CONVERSATION_CLOSED`
The conversation is resolved	Release to AI (`POST .../conversations/{threadId}/switch-to-ai`)	`409 CONVERSATION_CLOSED`
The conversation is resolved	Take over (`POST .../conversations/{threadId}/take-over`)	`409 CONVERSATION_CLOSED`
A person on your team has taken over	Send a message	Success. SiteGPT saves the visitor’s message, but the AI does not answer.
A person on your team has taken over	Escalate	`403 HUMAN_TAKEOVER`. If the conversation is already escalated, the call succeeds.
A person on your team has taken over	Release to AI	Success. The AI answers the conversation again.

The OpenAPI document marks each operation that can return 409. This includes POST /chatbots/{chatbotId}/messages, which starts a new conversation.

Deletes need confirmation

Delete endpoints that remove account or chatbot data need confirm=true in the query string. The endpoint pages show a confirm parameter where it applies. Example:

curl -X DELETE "https://sitegpt.ai/api/v2/chatbots/YOUR_CHATBOT_ID/leads/YOUR_LEAD_ID?confirm=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Without it, the API returns 400 CONFIRMATION_REQUIRED and deletes nothing. Bulk deletes also need confirmation. Send "confirm": true in the request body of POST /chatbots/{chatbotId}/documents/delete, and with the delete action of POST /chatbots/{chatbotId}/conversations/bulk and POST /chatbots/{chatbotId}/leads/actions. The documents endpoint also accepts confirm=true in the query string.

Rate limits and quotas

The API sends no rate-limit headers, and there is no published per-request rate limit.
429 means that a plan quota is used up, for example the pages quota for content. Do not retry a 429 in a loop. Remove content or change your plan. See Plans and limits.

Model names

API v2 uses the public model names gpt-4.1 and gpt-4.1-mini in requests and responses.

Get started

Discovery

Onboarding

Account

Billing

Tokens

Chatbots

Knowledge

Knowledge Sync Jobs

Knowledge Sources

Custom Responses

Personas

Instructions

Settings

Conversation Starters

Conversation Followups

Members

Leads

Conversations

Messages

Tags

Base URL

Response envelope

Errors

Conversation state conflicts

Deletes need confirmation

Rate limits and quotas

Model names

​Base URL

​Response envelope

​Pagination

​Errors

​Conversation state conflicts

​Deletes need confirmation

​Rate limits and quotas

​Model names

Base URL

Response envelope

Pagination

Errors

Conversation state conflicts

Deletes need confirmation

Rate limits and quotas

Model names