TypeScript SDK

@sitegpt/sdk is the official SiteGPT client for TypeScript and JavaScript. It calls API v2.

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.

This SDK manages your account from code. To control the chat widget on your website, use the widget SDK.

Install

npm install @sitegpt/sdk

Quickstart

API access needs the Growth plan or above. See Plans and limits. Create an API token on the Agents page. See Authentication. Then:

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)

Agent onboarding without a token

The agent-first onboarding start endpoint needs no token. The response includes a temporary token for the new chatbot:

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:

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

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.

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.

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

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.

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.

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.

Get started

Concepts

Add content

Improve answers

Customize the widget

Install

Leads

Human support

Monitor

Integrations

Account and team

Reference

Developers

Help

Install

Quickstart

Agent onboarding without a token

Error handling

Convenience methods

Deletes need confirmation

Other endpoints: `request()`

OpenAPI types

Timeouts

Base URL

​Install

​Quickstart

​Agent onboarding without a token

​Error handling

​Convenience methods

​Deletes need confirmation

​Other endpoints: request()

​OpenAPI types

​Timeouts

​Base URL

​Related

Install

Quickstart

Agent onboarding without a token

Error handling

Convenience methods

Deletes need confirmation

Other endpoints: `request()`

OpenAPI types

Timeouts

Base URL

Related