Metadata-Version: 2.5
Name: sitegpt
Version: 0.2.0
Summary: Official SiteGPT SDK for Python — a zero-dependency client for the SiteGPT API v2 (chatbots, knowledge, conversations, leads, messages, onboarding).
Project-URL: Homepage, https://sitegpt.ai
Project-URL: API Reference, https://sitegpt.ai/api/v2/openapi.json
Author-email: SiteGPT <support@sitegpt.ai>
License: MIT
License-File: LICENSE
Keywords: ai,ai-agent,api-client,chatbot,customer-support,knowledge-base,sdk,sitegpt,support-automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# sitegpt

Official [SiteGPT](https://sitegpt.ai) 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

```sh
pip install sitegpt
```

## Quickstart

Create an API token in the SiteGPT dashboard (Settings → API tokens), then:

```python
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:

```python
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

```python
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:

```python
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):

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

## Every other endpoint: `request()`

```python
# 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:

```python
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`](https://www.npmjs.com/package/@sitegpt/sdk) — the official TypeScript/JavaScript SDK.
- [`@sitegpt/cli`](https://www.npmjs.com/package/@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](https://sitegpt.ai)
