TypeScript SDK

@sitegpt/sdk is the official SiteGPT SDK for TypeScript and JavaScript — a typed, zero-dependency client for the SiteGPT API v2.

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.

This SDK drives the platform — creating chatbots, training knowledge, reading conversations. To embed the chat widget on your website, use the JavaScript widget SDK instead.

Install

npm install @sitegpt/sdk

Quickstart

Create a scoped API token on the Agents page, then:

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

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:

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:

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:

// 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:

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:

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

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:

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

Python SDK — the same client for Python.
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()`

OpenAPI types

Timeouts

Custom base URL

​Install

​Quickstart

​Agent onboarding bootstrap (no token required)

​Error handling

​Convenience namespaces

​Destructive operations require confirmation

​Every other endpoint: request()

​OpenAPI types

​Timeouts

​Custom base URL

​Related

Install

Quickstart

Agent onboarding bootstrap (no token required)

Error handling

Convenience namespaces

Destructive operations require confirmation

Every other endpoint: `request()`

OpenAPI types

Timeouts

Custom base URL

Related