> ## 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

> Reference for @sitegpt/sdk, the official TypeScript and JavaScript client for SiteGPT API v2.

`@sitegpt/sdk` is the official SiteGPT client for TypeScript and JavaScript. It calls [API v2](/docs/api-reference/v2/getting-started).

* **Typed.** Types are generated from the API v2 OpenAPI document. Each convenience method returns the `data` type of its operation.
* **No dependencies.** It uses the global `fetch`. It runs on Node.js 18 or later and in other runtimes that have `fetch`.
* **Handles the envelope.** The API answers with `{ ok, data, meta }`. The SDK returns `data`. It throws a `SiteGPTError` when `ok` is `false`.

<Note>
  This SDK manages your account from code. To control the chat widget on your website, use the [widget SDK](/docs/developers/widget-sdk).
</Note>

## Install

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

## Quickstart

API access needs the Growth plan or above. See [Plans and limits](/docs/reference/plans-and-limits). Create an API token on the **Agents** page. See [Authentication](/docs/developers/authentication). 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
const { chatbots = [] } = await sitegpt.chatbots.list()
const chatbotId = chatbots[0]?.id
if (!chatbotId) throw new Error('No chatbots found')

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

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

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

`chatbots.list()` returns the first 100 chatbots.

## Agent onboarding without a token

The [agent-first onboarding](/docs/cli/onboarding) start endpoint needs no token. The response includes a temporary token for the new chatbot:

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

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

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

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

## Error handling

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

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

try {
  await sitegpt.chatbots.get('YOUR_CHATBOT_ID')
} catch (error) {
  if (error instanceof SiteGPTError) {
    console.error(error.status) // HTTP status, for example 404
    console.error(error.code) // error code, for example CHATBOT_NOT_FOUND
    console.error(error.message) // readable message
    console.error(error.hint) // next step, when the API sends one
    console.error(error.requestId) // give this to support
  }
}
```

See [API conventions](/docs/api-reference/v2/conventions#errors) for error codes.

## Convenience methods

| Namespace | Methods |
| - | - |
| `sitegpt.chatbots` | `list`, `get`, `create`, `update`, `delete`, `dashboard`, `analytics` |
| `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`, `takeOver` |
| `sitegpt.leads` | `list`, `get`, `update`, `delete`, `runAction` |
| `sitegpt.messages` | `send`, `sendToConversation`, `list`, `update` |
| `sitegpt.onboarding` | `start`, `getWorkspace`, `claimWorkspace`, `deleteWorkspace` |

The client also has `sitegpt.me()` and `sitegpt.health()`.

`conversations.takeOver` needs version 0.3.0 or later. It takes over a conversation the same way as the dashboard. See [Conversation state conflicts](/docs/api-reference/v2/conventions#conversation-state-conflicts).

### Deletes need confirmation

The API needs `confirm=true` on delete operations. The SDK sends it only when you pass `{ confirm: true }` as the last argument. These methods need it: `chatbots.delete`, `knowledge.deleteDocument`, `knowledge.deleteDocuments`, `knowledge.revokeSource`, `conversations.delete`, and `leads.delete`. Without it, the SDK throws a `CONFIRMATION_REQUIRED` error and sends no request.

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

## Other endpoints: `request()`

Every API v2 operation works through `request(path, options)`. Known paths autocomplete.

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

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

`requestWithMeta()` also returns the envelope `meta`, including `meta.nextCursor` for the next page:

```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 package exports the generated types `components`, `operations`, and `paths`, and helper types such as `OperationData`. It also ships the OpenAPI document as `@sitegpt/sdk/openapi.generated.json`.

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

type Chatbot = components['schemas']['Chatbot']
type ListLeadsData = OperationData<'listLeads'>
```

## Timeouts

Requests time out after 30 seconds. Change this for the client with `timeoutMs`. For one request, pass an `AbortSignal`. A `signal` replaces the timeout.

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

## Base URL

`baseUrl` is `https://sitegpt.ai` by default. Change it only if SiteGPT gives you a different API address.

## Related

* [Python SDK](/docs/developers/sdk-python)
* [Go SDK](/docs/developers/sdk-go)
* [SiteGPT CLI](/docs/cli/overview)
* [API v2 reference](/docs/api-reference/v2/getting-started)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.