> ## Documentation Index
> Fetch the complete documentation index at: https://sitegpt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> The official typed client for the SiteGPT API v2: @sitegpt/sdk on npm.

`@sitegpt/sdk` is the official SiteGPT SDK for TypeScript and JavaScript — a
typed, zero-dependency client for the [SiteGPT API v2](/docs/api-reference/v2/getting-started).

* **Typed end to end** — types are generated from the live API's OpenAPI 3.1
  document (all 119 operations), and every convenience method returns the
  operation's exact `data` payload type.
* **Zero dependencies** — built on the global `fetch` (Node 18+, Bun, Deno,
  browsers, edge runtimes).
* **Envelope-aware** — the API responds with `{ ok, data, meta }`; the SDK
  returns `data` directly and throws a `SiteGPTError` whenever `ok` is `false`.

<Note>
  This SDK drives the platform — creating chatbots, training knowledge, reading
  conversations. To embed the chat widget on your website, use the
  [JavaScript widget SDK](/docs/developers/sdk) instead.
</Note>

## Install

```sh theme={null}
npm install @sitegpt/sdk
```

## Quickstart

Create a scoped API token on the [Agents page](/docs/developers/api-tokens-and-mcp), then:

```ts theme={null}
import { SiteGPT } from '@sitegpt/sdk'

const sitegpt = new SiteGPT({ apiToken: process.env.SITEGPT_API_TOKEN! })

// List your chatbots and pick one to work with
const { chatbots } = await sitegpt.chatbots.list()
const chatbotId = chatbots[0].id

// Add knowledge to a chatbot
await sitegpt.knowledge.addLinks(chatbotId, {
  urls: ['https://example.com/docs/getting-started'],
})

// Send a chat message (starts a new conversation)
const reply = await sitegpt.messages.send(chatbotId, {
  message: 'What are your pricing plans?',
})

// Review conversations and captured leads
const conversations = await sitegpt.conversations.list(chatbotId, { limit: 20 })
const leads = await sitegpt.leads.list(chatbotId)
```

## Agent onboarding bootstrap (no token required)

The [agent-first onboarding](/docs/cli/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:

```ts theme={null}
import { SiteGPT } from '@sitegpt/sdk'

// No API token yet — the bootstrap endpoint is public:
const bootstrap = new SiteGPT()
const started = await bootstrap.onboarding.start({
  websiteUrl: 'https://example.com',
})

// The response includes a temporary workspace token:
const sitegpt = new SiteGPT({ apiToken: started.apiToken as string })
const chatbotId = started.workspace?.chatbotId as string
await sitegpt.knowledge.documentStats(chatbotId)
```

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

## Error handling

Every failed call throws a `SiteGPTError` carrying the API's error envelope:

```ts theme={null}
import { SiteGPT, SiteGPTError } from '@sitegpt/sdk'

try {
  await sitegpt.chatbots.get('nonexistent-id')
} catch (error) {
  if (error instanceof SiteGPTError) {
    console.error(error.status) // HTTP status, e.g. 404
    console.error(error.code) // machine-readable code, e.g. NOT_FOUND
    console.error(error.message) // human-readable message
    console.error(error.hint) // actionable next step, when the API provides one
    console.error(error.requestId) // for support and debugging
  }
}
```

## Convenience namespaces

The highest-value API groups have first-class methods:

| Namespace               | Methods                                                                                                                                                                                                                                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sitegpt.chatbots`      | `list`, `get`, `create`, `update`, `delete`, `dashboard`                                                                                                                                                                                                                                                             |
| `sitegpt.knowledge`     | `listDocuments`, `getDocument`, `updateDocument`, `deleteDocument`, `deleteDocuments`, `documentStats`, `resyncDocuments`, `addLinks`, `addWebsite`, `addSitemap`, `addYoutube`, `setText`, `listSources`, `getSource`, `createSource`, `updateSource`, `revokeSource`, `ingestSource`, `listSyncJobs`, `getSyncJob` |
| `sitegpt.conversations` | `list`, `get`, `create`, `update`, `delete`, `escalate`, `switchToAi`                                                                                                                                                                                                                                                |
| `sitegpt.leads`         | `list`, `get`, `update`, `delete`, `runAction`                                                                                                                                                                                                                                                                       |
| `sitegpt.messages`      | `send`, `sendToConversation`, `list`, `update`                                                                                                                                                                                                                                                                       |
| `sitegpt.onboarding`    | `start`, `getWorkspace`, `claimWorkspace`, `deleteWorkspace`                                                                                                                                                                                                                                                         |

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.deleteDocument`, `knowledge.deleteDocuments`,
`knowledge.revokeSource`, `conversations.delete`, and `leads.delete` take a
required `{ confirm: true }` argument and throw a `CONFIRMATION_REQUIRED`
`SiteGPTError` client-side (before any request) without it:

```ts theme={null}
await sitegpt.conversations.delete(chatbotId, threadId, { confirm: true })
await sitegpt.chatbots.delete(chatbotId, { confirm: true })
```

## Every other endpoint: `request()`

All 119 API v2 operations are reachable through the typed low-level
`request(path, options)` — known paths autocomplete:

```ts theme={null}
// Custom responses, personas, instructions, settings, members, tags, billing…
const personas = await sitegpt.request(`/api/v2/chatbots/${chatbotId}/personas`)

await sitegpt.request(`/api/v2/chatbots/${chatbotId}/settings`, {
  method: 'PATCH',
  body: { general: { title: 'Support Bot' } },
})
```

`requestWithMeta()` additionally returns the envelope `meta` — including
`meta.nextCursor` for pagination:

```ts theme={null}
const { data, meta } = await sitegpt.requestWithMeta(
  `/api/v2/chatbots/${chatbotId}/conversations`,
  { query: { limit: 50 } },
)
const nextPage = await sitegpt.conversations.list(chatbotId, {
  cursor: meta.nextCursor ?? undefined,
})
```

## OpenAPI types

The raw generated types are exported for advanced use, and the OpenAPI
document itself ships in the package as `openapi.generated.json`:

```ts theme={null}
import type { components, operations, paths } from '@sitegpt/sdk'

type Chatbot = components['schemas']['Chatbot']
type ListLeadsData = import('@sitegpt/sdk').OperationData<'listLeads'>
```

## Timeouts

Requests time out after 30 seconds by default. Override the default per
client with `timeoutMs`, or per request with an `AbortSignal` (a provided
`signal` replaces the timeout signal entirely):

```ts theme={null}
const sitegpt = new SiteGPT({ apiToken, timeoutMs: 60_000 })
await sitegpt.request('/api/v2/me', { signal: AbortSignal.timeout(5_000) })
```

## Custom base URL

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

```ts theme={null}
const sitegpt = new SiteGPT({
  apiToken: process.env.SITEGPT_API_TOKEN!,
  baseUrl: 'https://sitegpt.ai',
})
```

## Related

* [Python SDK](/docs/developers/sdk-python) — the same client for Python.
* [SiteGPT CLI](/docs/cli/overview) — the same API from your terminal, scripts,
  and AI agents (includes a local MCP server).
* [API v2 reference](/docs/api-reference/v2/getting-started) — every endpoint,
  generated from the live OpenAPI document.