Python SDK

sitegpt is the official SiteGPT client for Python. It calls API v2. It uses only the Python standard library and needs Python 3.9 or later.

Handles the envelope. The API answers with { ok, data, meta }. The SDK returns data as plain dicts and lists. It raises a SiteGPTError when ok is false.
Reaches every endpoint. Convenience methods cover chatbots, content, conversations, leads, messages, and onboarding. Every other API v2 operation works through request().

Install

pip install sitegpt

Quickstart

API access needs the Growth plan or above. See Plans and limits. Create an API token on the Agents page. See Authentication. Then:

import os

from sitegpt import SiteGPT

sitegpt = SiteGPT(api_token=os.environ["SITEGPT_API_TOKEN"])

# List your chatbots
chatbots = sitegpt.chatbots.list()["chatbots"]
chatbot_id = chatbots[0]["id"]

# Add a page as content
sitegpt.knowledge.add_links(
    chatbot_id, urls=["https://example.com/docs/getting-started"]
)

# Send a message (starts a new conversation)
reply = sitegpt.messages.send(chatbot_id, message="What are your opening hours?")

# Read conversations and leads
conversations = sitegpt.conversations.list(chatbot_id, limit=20)
leads = sitegpt.leads.list(chatbot_id)

Agent onboarding without a token

The agent-first onboarding start endpoint needs no token. The response includes a temporary token for the new chatbot:

from sitegpt import SiteGPT

# No API token yet. The start endpoint is public.
bootstrap = SiteGPT()
started = bootstrap.onboarding.start(websiteUrl="https://example.com")

# Use the temporary token from the response
sitegpt = SiteGPT(api_token=started["apiToken"])
sitegpt.knowledge.document_stats(started["workspace"]["chatbotId"])

health() also works without a token. Every other call returns 401 until you set api_token.

Error handling

Every failed call raises a SiteGPTError with the fields of the API error:

from sitegpt import SiteGPT, SiteGPTError

try:
    sitegpt.chatbots.get("YOUR_CHATBOT_ID")
except SiteGPTError as error:
    print(error.status)      # HTTP status, for example 404
    print(error.code)        # error code, for example CHATBOT_NOT_FOUND
    print(error.message)     # readable message
    print(error.hint)        # next step, when the API sends one
    print(error.request_id)  # give this to support

See API conventions for error codes.

Convenience methods

Namespace	Methods
`sitegpt.chatbots`	`list`, `get`, `create`, `update`, `delete`, `dashboard`, `analytics`
`sitegpt.knowledge`	`list_documents`, `get_document`, `update_document`, `delete_document`, `delete_documents`, `document_stats`, `resync_documents`, `add_links`, `add_website`, `add_sitemap`, `add_youtube`, `set_text`, `list_sources`, `get_source`, `create_source`, `update_source`, `revoke_source`, `ingest_source`, `list_sync_jobs`, `get_sync_job`
`sitegpt.conversations`	`list`, `get`, `create`, `update`, `delete`, `escalate`, `switch_to_ai`, `take_over`
`sitegpt.leads`	`list`, `get`, `update`, `delete`, `run_action`
`sitegpt.messages`	`send`, `send_to_conversation`, `list`, `update`
`sitegpt.onboarding`	`start`, `get_workspace`, `claim_workspace`, `delete_workspace`

conversations.take_over needs version 0.3.0 or later. It takes over a conversation the same way as the dashboard. See Conversation state conflicts. The client also has sitegpt.me() and sitegpt.health(). Pass body fields and query filters as keyword arguments. Use the API’s own field names, in camelCase, as in the OpenAPI document:

sitegpt.knowledge.list_documents(chatbot_id, limit=10, source=["WEBSITE"])
sitegpt.knowledge.get_document(chatbot_id, document_id, includeContent=True)

One method is different. chatbots.analytics takes start_day and end_day, as YYYY-MM-DD dates:

sitegpt.chatbots.analytics(chatbot_id, start_day="2026-09-01", end_day="2026-09-21")

Deletes need confirmation

The API needs confirm=true on delete operations. The SDK sends it only when you pass confirm=True. These methods need it: chatbots.delete, knowledge.delete_document, knowledge.delete_documents, knowledge.revoke_source, conversations.delete, and leads.delete. Without it, the SDK raises a CONFIRMATION_REQUIRED error and sends no request.

sitegpt.conversations.delete(chatbot_id, thread_id, confirm=True)
sitegpt.chatbots.delete(chatbot_id, confirm=True)

Other endpoints: `request()`

# Custom responses, personas, instructions, settings, members, tags, billing, and more
personas = sitegpt.request(f"/api/v2/chatbots/{chatbot_id}/personas")

sitegpt.request(
    f"/api/v2/chatbots/{chatbot_id}/settings",
    method="PATCH",
    body={"appearance": {"title": "Support Bot"}},
)

request_with_meta() also returns the envelope meta, including meta["nextCursor"] for the next page:

data, meta = sitegpt.request_with_meta(
    f"/api/v2/chatbots/{chatbot_id}/conversations", query={"limit": 50}
)
if meta.get("nextCursor"):
    more = sitegpt.conversations.list(chatbot_id, cursor=meta["nextCursor"])

Timeouts and base URL

timeout is the time limit for each request, in seconds. The default is 30.
base_url is https://sitegpt.ai by default. Change it only if SiteGPT gives you a different API address.

sitegpt = SiteGPT(api_token=os.environ["SITEGPT_API_TOKEN"], timeout=60)

Get started

Concepts

Add content

Improve answers

Customize the widget

Install

Leads

Human support

Monitor

Integrations

Account and team

Reference

Developers

Help

Install

Quickstart

Agent onboarding without a token

Error handling

Convenience methods

Deletes need confirmation

Other endpoints: `request()`

Timeouts and base URL

​Install

​Quickstart

​Agent onboarding without a token

​Error handling

​Convenience methods

​Deletes need confirmation

​Other endpoints: request()

​Timeouts and base URL

​Related

Install

Quickstart

Agent onboarding without a token

Error handling

Convenience methods

Deletes need confirmation

Other endpoints: `request()`

Timeouts and base URL

Related