sitegpt

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/lists) and raises a SiteGPTError (with the API's error code, message, and actionable hint) whenever ok is false.
• Full API reach — convenience methods cover the highest-value groups (chatbots, knowledge, conversations, leads, messages, onboarding); every one of the 120 API v2 operations is reachable through request().

Install

pip install sitegpt

Quickstart

Create an API token in the SiteGPT dashboard (Settings → API tokens), 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 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

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

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.

Related

• @sitegpt/sdk — the official TypeScript/JavaScript SDK.
• @sitegpt/cli — the same API from your terminal, scripts, and AI agents (includes a local MCP server).
• API reference: https://sitegpt.ai/api/v2/openapi.json

License

MIT © SiteGPT