Make your first API calls

In this tutorial, you make four calls to SiteGPT API v2. You create a token, list your chatbots, send a message to one chatbot, and read the conversation that the message started. It takes about 10 minutes. You need:

A SiteGPT account on the Growth plan or above, with at least one chatbot that has content. See Plans and limits.
A terminal with curl.

The examples use placeholders such as YOUR_API_TOKEN and YOUR_CHATBOT_ID. Replace them with your own values.

Step 1: Create an API token

Sign in to SiteGPT.
In the top navigation, select Agents.
In Create API token, enter the Token name First API calls.
Keep the default Expires value and the Standard access level.
Keep All accessible chatbots.
Select Create token.
Copy the token. It starts with sgpt_. SiteGPT shows it only once.

Save the token in your terminal so that the next commands can use it:

export SITEGPT_API_TOKEN="YOUR_API_TOKEN"

Check that the token works:

curl https://sitegpt.ai/api/v2/me \
  -H "Authorization: Bearer $SITEGPT_API_TOKEN"

The response starts with "ok": true. data.user.email is the email address of your account.

Step 2: List your chatbots

curl https://sitegpt.ai/api/v2/chatbots \
  -H "Authorization: Bearer $SITEGPT_API_TOKEN"

The response has a data.chatbots list. Each chatbot has an id and a title:

{
  "ok": true,
  "data": {
    "chatbots": [
      { "id": "YOUR_CHATBOT_ID", "title": "Support Bot", "...": "..." }
    ]
  },
  "meta": { "requestId": "..." }
}

The list has up to 100 chatbots per page. If you have more, see Pagination. Copy the id of the chatbot that you want to test, and save it:

export SITEGPT_CHATBOT_ID="YOUR_CHATBOT_ID"

Step 3: Send a message

Send a question as a visitor. Use a question that your content can answer.

curl -X POST "https://sitegpt.ai/api/v2/chatbots/$SITEGPT_CHATBOT_ID/messages" \
  -H "Authorization: Bearer $SITEGPT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What are your opening hours?" }'

This call starts a new conversation. It waits for the answer, so it can take a few seconds. The response has two parts:

data.conversation.threadId is the ID of the new conversation.
data.message.answer.text is the chatbot’s answer.

{
  "ok": true,
  "data": {
    "conversation": { "threadId": "YOUR_CONVERSATION_ID", "...": "..." },
    "message": {
      "messageType": "NORMAL_MESSAGE",
      "question": { "text": "What are your opening hours?", "...": "..." },
      "answer": { "text": "...", "...": "..." },
      "sources": ["..."]
    }
  },
  "meta": { "requestId": "..." }
}

Save the conversation ID:

export SITEGPT_THREAD_ID="YOUR_CONVERSATION_ID"

Step 4: Read the conversation

curl "https://sitegpt.ai/api/v2/chatbots/$SITEGPT_CHATBOT_ID/conversations/$SITEGPT_THREAD_ID" \
  -H "Authorization: Bearer $SITEGPT_API_TOKEN"

The response has data.conversation. Its messages list has your question and the chatbot’s answer. The conversation also has fields such as mode, escalated, and resolved.

What you did

You created a token, found a chatbot, started a conversation, and read it back. Every API v2 call follows the same pattern:

The base URL is https://sitegpt.ai/api/v2.
The token goes in the Authorization: Bearer header.
The response is { "ok": true, "data": ..., "meta": ... }, or { "ok": false, "error": ... } when something fails.

Next steps

API conventions: pagination, errors, and deletes.
Authentication: access levels, scopes, and device login.
TypeScript SDK and Python SDK: the same calls from code.
The endpoint pages in this API reference list every operation, with its scopes and fields. The OpenAPI document is at https://sitegpt.ai/api/v2/openapi.json.
Moving from the legacy API? See Move from API v0 to v2.

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

Make your first API calls

Step 1: Create an API token

Step 2: List your chatbots

Step 3: Send a message

Step 4: Read the conversation

What you did

Next steps

​Step 1: Create an API token

​Step 2: List your chatbots

​Step 3: Send a message

​Step 4: Read the conversation

​What you did

​Next steps

Step 1: Create an API token

Step 2: List your chatbots

Step 3: Send a message

Step 4: Read the conversation

What you did

Next steps