Move from API v0 to v2

This page maps the legacy API v0 (and the one v1 endpoint) to API v2. Use it to move an existing integration. Paths in the v2 column are relative to https://sitegpt.ai/api/v2. Paths in the v0 column are relative to https://sitegpt.ai/api.

What changes

Topic	API v0	API v2
Base URL	`https://sitegpt.ai/api/v0`	`https://sitegpt.ai/api/v2`
Credential	Legacy API key from the Billing page	API token (`sgpt_...`) from the Agents page. See Authentication.
Permissions	The key acts as your user, with your dashboard role. It has no scopes.	Scopes, chatbot access, and your dashboard role
Success response	`{ "success": true, "message", "data" }`	`{ "ok": true, "data", "meta" }`
Error response	`{ "success": false, "message", "data": null, "error": { "code", "message", "details" } }`	`{ "ok": false, "error": { "code", "message", "hint", "details" }, "meta" }`
Pagination	None. Lists return all items.	Cursor pagination with `limit`, `cursor`, and `meta.nextCursor`
Deletes	No confirmation	Deletes of chatbot or account data need `confirm=true`
Spec	`https://sitegpt.ai/openapi.yaml`	`https://sitegpt.ai/api/v2/openapi.json`

See API conventions for the v2 rules.

Names

API v0	API v2	Dashboard
threads	conversations (the ID is still called `threadId`)	Conversations
prompts	instructions	Instructions
personas (under `settings/`)	personas	Personas
quick prompts, conversation starters	starters	Conversation starters
follow-up prompts	followups	Follow-up suggestions
custom content	knowledge text	Text snippets
links	knowledge links, website, sitemap, and YouTube	Content sources

To make a persona or instruction active, v0 uses .../assign and v2 uses .../use.

Endpoint mapping

Chatbots

API v0	API v2
`GET /v0/chatbots`	`GET /chatbots`
`POST /v0/chatbots`	`POST /chatbots`
`GET /v0/chatbots/{chatbotId}`	`GET /chatbots/{chatbotId}`
`DELETE /v0/chatbots/{chatbotId}`	`DELETE /chatbots/{chatbotId}?confirm=true`
`PATCH /v0/chatbots/{chatbotId}/appearance`	`PATCH /chatbots/{chatbotId}/settings/appearance`
`POST /v0/chatbots/{chatbotId}/icons`	`POST /chatbots/{chatbotId}/icons`
`DELETE /v0/chatbots/{chatbotId}/icons`	`DELETE /chatbots/{chatbotId}/icons/{iconType}?confirm=true`

Content

API v0	API v2
`POST /v0/chatbots/{chatbotId}/links`	`POST /chatbots/{chatbotId}/knowledge/links`
`POST /v1/chatbots/{chatbotId}/links` with `sourceType` `URLS_LIST`	`POST /chatbots/{chatbotId}/knowledge/links`
`POST /v1/chatbots/{chatbotId}/links` with `sourceType` `WEBSITE`	`POST /chatbots/{chatbotId}/knowledge/website`
`POST /v1/chatbots/{chatbotId}/links` with `sourceType` `SITEMAP`	`POST /chatbots/{chatbotId}/knowledge/sitemap`
`POST /v1/chatbots/{chatbotId}/links` with `sourceType` `YOUTUBE`	`POST /chatbots/{chatbotId}/knowledge/youtube`
`POST /v0/chatbots/{chatbotId}/custom-content`	`POST /chatbots/{chatbotId}/knowledge/text`

Messages and conversations

API v0	API v2
`POST /v0/chatbots/{chatbotId}/message`	`POST /chatbots/{chatbotId}/messages` for a new conversation, or `POST /chatbots/{chatbotId}/conversations/{threadId}/messages` for an existing one
`PATCH /v0/chatbots/{chatbotId}/messages/{messageId}`	`PATCH /chatbots/{chatbotId}/conversations/{threadId}/messages/{messageId}`
`GET /v0/chatbots/{chatbotId}/threads`	`GET /chatbots/{chatbotId}/conversations` (paginated)
`POST /v0/chatbots/{chatbotId}/threads`	`POST /chatbots/{chatbotId}/conversations`
`GET /v0/chatbots/{chatbotId}/threads/{threadId}`	`GET /chatbots/{chatbotId}/conversations/{threadId}`
`PATCH /v0/chatbots/{chatbotId}/threads/{threadId}`	`PATCH /chatbots/{chatbotId}/conversations/{threadId}`
`POST /v0/chatbots/{chatbotId}/threads/{threadId}/escalate`	`POST /chatbots/{chatbotId}/conversations/{threadId}/escalate`

Conversation starters and follow-up suggestions

API v0	API v2
`GET /v0/chatbots/{chatbotId}/quick-prompts`	`GET /chatbots/{chatbotId}/starters`
`POST /v0/chatbots/{chatbotId}/quick-prompts`	`POST /chatbots/{chatbotId}/starters`
`GET /v0/chatbots/{chatbotId}/quick-prompts/{promptId}`	`GET /chatbots/{chatbotId}/starters/{starterId}`
`PATCH /v0/chatbots/{chatbotId}/quick-prompts/{promptId}`	`PATCH /chatbots/{chatbotId}/starters/{starterId}`
`DELETE /v0/chatbots/{chatbotId}/quick-prompts/{promptId}`	`DELETE /chatbots/{chatbotId}/starters/{starterId}?confirm=true`
`GET /v0/chatbots/{chatbotId}/follow-up-prompts`	`GET /chatbots/{chatbotId}/followups`
`POST /v0/chatbots/{chatbotId}/follow-up-prompts`	`POST /chatbots/{chatbotId}/followups`
`GET /v0/chatbots/{chatbotId}/follow-up-prompts/{followUpPromptId}`	`GET /chatbots/{chatbotId}/followups/{followupId}`
`PATCH /v0/chatbots/{chatbotId}/follow-up-prompts/{followUpPromptId}`	`PATCH /chatbots/{chatbotId}/followups/{followupId}`
`DELETE /v0/chatbots/{chatbotId}/follow-up-prompts/{followUpPromptId}`	`DELETE /chatbots/{chatbotId}/followups/{followupId}?confirm=true`

The v0 endpoint reference pages show conversation starters under /v0/chatbots/{chatbotId}/conversation-starters. The API serves them only at /v0/chatbots/{chatbotId}/quick-prompts. The conversation-starters path returns 404.

Instructions and personas

API v0	API v2
`GET /v0/chatbots/{chatbotId}/settings/prompts`	`GET /chatbots/{chatbotId}/instructions`
`POST /v0/chatbots/{chatbotId}/settings/prompts`	`POST /chatbots/{chatbotId}/instructions`
`GET /v0/chatbots/{chatbotId}/settings/prompts/{promptId}`	`GET /chatbots/{chatbotId}/instructions/{instructionId}`
`PATCH /v0/chatbots/{chatbotId}/settings/prompts/{promptId}`	`PATCH /chatbots/{chatbotId}/instructions/{instructionId}`
`DELETE /v0/chatbots/{chatbotId}/settings/prompts/{promptId}`	`DELETE /chatbots/{chatbotId}/instructions/{instructionId}?confirm=true`
`POST /v0/chatbots/{chatbotId}/settings/prompts/{promptId}/assign`	`POST /chatbots/{chatbotId}/instructions/{instructionId}/use`
`GET /v0/chatbots/{chatbotId}/settings/personas`	`GET /chatbots/{chatbotId}/personas`
`POST /v0/chatbots/{chatbotId}/settings/personas`	`POST /chatbots/{chatbotId}/personas`
`GET /v0/chatbots/{chatbotId}/settings/personas/{personaId}`	`GET /chatbots/{chatbotId}/personas/{personaId}`
`PATCH /v0/chatbots/{chatbotId}/settings/personas/{personaId}`	`PATCH /chatbots/{chatbotId}/personas/{personaId}`
`DELETE /v0/chatbots/{chatbotId}/settings/personas/{personaId}`	`DELETE /chatbots/{chatbotId}/personas/{personaId}?confirm=true`
`POST /v0/chatbots/{chatbotId}/settings/personas/{personaId}/assign`	`POST /chatbots/{chatbotId}/personas/{personaId}/use`

Settings

In API v2, each settings group is a section of PATCH /chatbots/{chatbotId}/settings/{section}. You can also change several sections at once with PATCH /chatbots/{chatbotId}/settings.

API v0	API v2
`PATCH /v0/chatbots/{chatbotId}/settings/general`	`PATCH /chatbots/{chatbotId}/settings/general`
`PATCH /v0/chatbots/{chatbotId}/settings/chat-mode`	`PATCH /chatbots/{chatbotId}/settings/chat-mode`
`PATCH /v0/chatbots/{chatbotId}/settings/localization`	`PATCH /chatbots/{chatbotId}/settings/localization`
`PATCH /v0/chatbots/{chatbotId}/settings/user-data`	`PATCH /chatbots/{chatbotId}/settings/user-data`
`PATCH /v0/chatbots/{chatbotId}/settings/advanced`, webhook fields	`PATCH /chatbots/{chatbotId}/settings/webhooks`
`PATCH /v0/chatbots/{chatbotId}/settings/advanced`, `creativity` and `temperature`	No direct equivalent. Set `temperature` on the instruction that the chatbot uses: `PATCH /chatbots/{chatbotId}/instructions/{instructionId}`. The dashboard shows this value as Creativity Level.

The v2 webhooks section needs webhook access on your plan. See Webhooks.

Removed in v2

The v0 endpoint reference lists Whitelabel endpoints (/v0/w/brands/...). The API does not serve them, and they have no v2 equivalent.

Only in API v2

API v2 has many endpoints that API v0 does not have. Some examples:

Custom responses: /chatbots/{chatbotId}/custom-responses
Content documents and connected sources: /chatbots/{chatbotId}/documents, /chatbots/{chatbotId}/knowledge/sources
File upload: POST /chatbots/{chatbotId}/knowledge/files
Leads: /chatbots/{chatbotId}/leads
Members: /chatbots/{chatbotId}/members
Tags: /chatbots/{chatbotId}/tags
Analytics: GET /chatbots/{chatbotId}/analytics
Release a conversation to the AI: POST /chatbots/{chatbotId}/conversations/{threadId}/switch-to-ai
Take over a conversation: POST /chatbots/{chatbotId}/conversations/{threadId}/take-over
Account, usage, billing, and tokens: /account, /usage, /billing/..., /tokens

See the endpoint pages in this API reference for the full list.

Legacy API v0

Chatbots

Appearance

Custom Content

Follow-up Prompts

Icons

Content & Training

Messages

Personas

Instructions

Conversation Starters

Settings

Threads

Whitelabel (Deprecated)

What changes

Names

Endpoint mapping

Chatbots

Content

Messages and conversations

Conversation starters and follow-up suggestions

Instructions and personas

Settings

Removed in v2

Only in API v2

​What changes

​Names

​Endpoint mapping

​Chatbots

​Content

​Messages and conversations

​Conversation starters and follow-up suggestions

​Instructions and personas

​Settings

​Removed in v2

​Only in API v2

What changes

Names

Endpoint mapping

Chatbots

Content

Messages and conversations

Conversation starters and follow-up suggestions

Instructions and personas

Settings

Removed in v2

Only in API v2