Python SDK

sitegpt is the official SiteGPT SDK for Python — a small, dependable, zero-dependency client for the SiteGPT API v2 (standard library only, Python 3.9+).

Envelope-aware — the API responds with { ok, data, meta }; the SDK returns data directly (plain dicts and lists) and raises a SiteGPTError whenever ok is false.
Full API reach — convenience methods cover the highest-value groups (chatbots, knowledge, conversations, leads, messages, onboarding); every one of the 119 API v2 operations is reachable through request().

Install

pip install sitegpt

Quickstart

Create a scoped API token on the Agents page, 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 knowledge to a chatbot
sitegpt.knowledge.add_links(
    chatbot_id, urls=["https://example.com/docs/getting-started"]
)

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

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

Agent onboarding bootstrap (no token required)

The agent-first onboarding bootstrap is a public endpoint — an AI agent can provision a SiteGPT workspace with no credentials at all, and the response carries the temporary workspace token to use for everything that follows:

from sitegpt import SiteGPT

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

# The response includes a temporary workspace token:
sitegpt = SiteGPT(api_token=started["apiToken"])
sitegpt.knowledge.document_stats(started["workspace"]["chatbotId"])

health() is public too; every other endpoint responds 401 until an api_token is set.

Error handling

Every failed call raises a SiteGPTError carrying the API’s error envelope:

from sitegpt import SiteGPT, SiteGPTError

try:
    sitegpt.chatbots.get("nonexistent-id")
except SiteGPTError as error:
    print(error.status)      # HTTP status, e.g. 404
    print(error.code)        # machine-readable code, e.g. NOT_FOUND
    print(error.message)     # human-readable message
    print(error.hint)        # actionable next step, when the API provides one
    print(error.request_id)  # for support and debugging

Convenience namespaces

Namespace	Methods
`sitegpt.chatbots`	`list`, `get`, `create`, `update`, `delete`, `dashboard`
`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`
`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`

Plus sitegpt.me() and sitegpt.health().

Destructive operations require confirmation

The API requires confirm=true on delete-family endpoints, and the SDK keeps that intent explicit instead of confirming on your behalf: chatbots.delete, knowledge.delete_document, knowledge.delete_documents, knowledge.revoke_source, conversations.delete, and leads.delete take a confirm=True keyword argument and raise a CONFIRMATION_REQUIRED SiteGPTError client-side (before any request) without it:

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

Body fields and query filters are passed as keyword arguments using the API’s own field names (camelCase, exactly as documented in the OpenAPI document):

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

Every other endpoint: `request()`

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

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

request_with_meta() additionally returns the envelope meta — including meta["nextCursor"] for pagination:

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"])

Custom base URL

base_url defaults to https://sitegpt.ai and only needs to change if SiteGPT gives you a different API origin.

TypeScript SDK — the same client for TypeScript and JavaScript.
SiteGPT CLI — the same API from your terminal, scripts, and AI agents (includes a local MCP server).
API v2 reference — every endpoint, generated from the live OpenAPI document.

Getting started

Add your content

Customize your chatbot

Install on your website

Run your chatbot

Connect your tools

Developers

Account & team

Install

Quickstart

Agent onboarding bootstrap (no token required)

Error handling

Convenience namespaces

Destructive operations require confirmation

Every other endpoint: `request()`

Custom base URL

​Install

​Quickstart

​Agent onboarding bootstrap (no token required)

​Error handling

​Convenience namespaces

​Destructive operations require confirmation

​Every other endpoint: request()

​Custom base URL

​Related

Install

Quickstart

Agent onboarding bootstrap (no token required)

Error handling

Convenience namespaces

Destructive operations require confirmation

Every other endpoint: `request()`

Custom base URL

Related