@sitegpt/sdk

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 120 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 (with the API's error code, message, and actionable hint) whenever ok is false.

Install

npm install @sitegpt/sdk

Quickstart

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

import { SiteGPT } from '@sitegpt/sdk'

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

// List your chatbots
const { chatbots } = await sitegpt.chatbots.list()

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

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 120 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',
})

Related

• 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