Go SDK

sitegpt-go is the official SiteGPT client for Go. It calls API v2. It works like the TypeScript and Python SDKs, with one difference: it returns the whole response envelope. See Responses.

No dependencies. It uses only the Go standard library. It needs Go 1.22 or later.
Structured errors. Every non-2xx response returns a *sitegpt.Error with the API’s code, message, and hint.
Safe defaults. Delete helpers do not run unless confirm is true. The client removes the token from a redirect that changes the scheme, host, or port.

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

Install

go get github.com/sitegpt/sitegpt-go

The module path is github.com/sitegpt/sitegpt-go. The package name is sitegpt.

Quickstart

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

package main

import (
	"context"
	"fmt"
	"net/url"
	"os"

	sitegpt "github.com/sitegpt/sitegpt-go"
)

func main() {
	client := sitegpt.NewClient(os.Getenv("SITEGPT_API_TOKEN"))
	ctx := context.Background()

	// List your chatbots and pick one
	listed, err := client.Chatbots.List(ctx)
	if err != nil {
		panic(err)
	}
	data, _ := listed["data"].(map[string]any)
	chatbots, _ := data["chatbots"].([]any)
	if len(chatbots) == 0 {
		panic("no chatbots found")
	}
	first, _ := chatbots[0].(map[string]any)
	chatbotID, _ := first["id"].(string)

	// Add a page as content
	if _, err := client.Knowledge.AddLinks(ctx, chatbotID, sitegpt.JSON{
		"urls": []string{"https://example.com/docs/getting-started"},
	}); err != nil {
		panic(err)
	}

	// Send a message (starts a new conversation)
	reply, err := client.Messages.Send(ctx, chatbotID, sitegpt.JSON{
		"message": "What are your opening hours?",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(reply["data"])

	// Read conversations and leads
	conversations, err := client.Conversations.List(ctx, chatbotID, url.Values{"limit": {"20"}})
	if err != nil {
		panic(err)
	}
	leads, err := client.Leads.List(ctx, chatbotID, nil)
	if err != nil {
		panic(err)
	}
	fmt.Println(conversations["data"], leads["data"])
}

Responses

Every method returns sitegpt.JSON, which is a map[string]any. It holds the whole API envelope: ok, data, and meta. Read the payload from data. Nested objects are map[string]any and lists are []any, so use type assertions to read them. The TypeScript and Python SDKs return data directly.

Agent onboarding without a token

The agent-first onboarding start endpoint needs no token. Pass an empty token. The client then sends no Authorization header. The response includes a temporary token for the new chatbot:

// No API token yet. The start endpoint is public.
bootstrap := sitegpt.NewClient("")
started, err := bootstrap.Onboarding.Start(ctx, sitegpt.JSON{
	"websiteUrl": "https://example.com",
})
if err != nil {
	panic(err)
}

// Use the temporary token from the envelope's data
data, _ := started["data"].(map[string]any)
apiToken, _ := data["apiToken"].(string)
workspace, _ := data["workspace"].(map[string]any)
chatbotID, _ := workspace["chatbotId"].(string)

client := sitegpt.NewClient(apiToken)
stats, err := client.Knowledge.DocumentStats(ctx, chatbotID, nil)

Onboarding.GetWorkspace(ctx, workspaceID) reads the state of the temporary workspace. Onboarding.ClaimWorkspace claims it for an account, and Onboarding.DeleteWorkspace deletes it. These two methods need v0.4.0 or later. Health also works without a token. Every other call returns 401 until you set a token.

Error handling

Every non-2xx response returns a *sitegpt.Error. Use errors.As to read it:

_, err := client.Chatbots.Get(ctx, "YOUR_CHATBOT_ID")

var apiErr *sitegpt.Error
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.Status)  // HTTP status, for example 404
	fmt.Println(apiErr.Code)    // error code, for example CHATBOT_NOT_FOUND
	fmt.Println(apiErr.Message) // readable message
	fmt.Println(apiErr.Hint)    // next step, when the API sends one
	fmt.Println(apiErr.Details) // extra error data, when the API sends it
}

Some errors come from the SDK before it sends a request: CONFIRMATION_REQUIRED, INVALID_PATH, and INVALID_PATH_PARAM. For these errors, Status is 0.
Network errors and a 2xx response that is not JSON return a plain error, not a *sitegpt.Error.
The SDK does not retry failed requests.

See API conventions for error codes.

Convenience methods

Namespace	Methods
`client.Chatbots`	`List`, `Get`, `Create`, `Update`, `Delete`, `Dashboard`, `Analytics`
`client.Knowledge`	Documents: `ListDocuments`, `DocumentStats`, `GetDocument`, `UpdateDocument`, `DeleteDocument`, `DeleteDocuments`, `ResyncDocuments`. Adding content: `AddLinks`, `AddWebsite`, `AddSitemap`, `AddYouTube`, `SetText`. Sources: `ListSources`, `GetSource`, `CreateSource`, `UpdateSource`, `RevokeSource`, `IngestSource`. Sync jobs: `ListSyncJobs`, `GetSyncJob`
`client.Conversations`	`List`, `Get`, `Create`, `Update`, `Delete`, `Escalate`, `TakeOver`, `SwitchToAI`
`client.Leads`	`List`, `Get`, `Update`, `Delete`, `RunAction`
`client.Messages`	`Send`, `SendToConversation`, `List`, `Update`
`client.Onboarding`	`Start`, `GetWorkspace`, `ClaimWorkspace`, `DeleteWorkspace`

The client also has client.Me(ctx) and client.Health(ctx). The Go SDK has helpers for the same operations as the TypeScript and Python SDKs. Use Request for every other operation. Version notes:

v0.4.0 adds 20 methods: the document, source, and sync job methods other than ListDocuments, DocumentStats, and ListSources, and Conversations.Create, Conversations.Update, Leads.Update, Leads.RunAction, Messages.List, Messages.Update, Onboarding.ClaimWorkspace, and Onboarding.DeleteWorkspace.
v0.4.0 changes DocumentStats. It now takes a url.Values filter as the third argument. Code written for v0.3.0 must add nil.
v0.3.0 adds TakeOver and SwitchToAI. In older versions, Escalate with nil fails with 400.

All methods take a context.Context first, then the IDs as string values. The other arguments have these types:

Body fields are a sitegpt.JSON map. This applies to every method that sends a body, for example Create, Update, the Knowledge.Add... methods, ResyncDocuments, IngestSource, Escalate, and Send. Use the API’s own field names, in camelCase, as in the OpenAPI document.
If you pass nil as the body, the SDK sends an empty JSON object. In v0.3.0, this applies only to Escalate, TakeOver, and SwitchToAI. Their only field is an optional message.
Query filters are a url.Values. This applies to Chatbots.Analytics, Knowledge.ListDocuments, Knowledge.DocumentStats, Knowledge.GetDocument, Knowledge.ListSources, Knowledge.ListSyncJobs, Conversations.List, Leads.List, and Messages.List. Pass nil for no filters. DocumentStats takes the same filters as ListDocuments. For GetDocument, pass includeContent=true to get the full text.

docs, err := client.Knowledge.ListDocuments(ctx, chatbotID, url.Values{"limit": {"10"}})

Analytics

Chatbots.Analytics returns the daily engagement series for a chatbot, with totals and a comparison to the previous period. Set the range with startDay and endDay, as YYYY-MM-DD dates in UTC. If you do not set a range, the API uses the last 30 days:

analytics, err := client.Chatbots.Analytics(ctx, chatbotID, url.Values{
	"startDay": {"2026-09-01"},
	"endDay":   {"2026-09-21"},
})

If analytics is not on your plan, the call returns a 403 *sitegpt.Error with the code ANALYTICS_LOCKED. Chatbots.Dashboard works on every plan that includes API access.

Deletes need confirmation

The API needs confirm=true on delete operations. Chatbots.Delete, Conversations.Delete, Leads.Delete, Knowledge.DeleteDocument, Knowledge.DeleteDocuments, and Knowledge.RevokeSource take a confirm bool argument. The SDK sends confirm=true only when you pass true. If you pass false, the SDK returns a CONFIRMATION_REQUIRED error and sends no request. Onboarding.DeleteWorkspace needs no confirmation, because it deletes only a temporary onboarding workspace.

_, err := client.Conversations.Delete(ctx, chatbotID, threadID, true)
_, err = client.Chatbots.Delete(ctx, chatbotID, true)

Other endpoints: `Request`

Every API v2 operation works through Request(ctx, method, path, query, body). query is a url.Values and body is any value that encoding/json can encode. Both can be nil:

// Custom responses, personas, instructions, settings, members, tags, billing, and more
personas, err := client.Request(ctx, http.MethodGet,
	"/api/v2/chatbots/"+chatbotID+"/personas", nil, nil)

_, err = client.Request(ctx, http.MethodPatch,
	"/api/v2/chatbots/"+chatbotID+"/settings", nil, sitegpt.JSON{
		"appearance": sitegpt.JSON{"title": "Support Bot"},
	})

The path must start with /.
The client rejects empty path segments and . or .. segments before it sends the request. A wrong ID cannot change the request to a different route.
Request does not escape the path. The convenience methods escape each ID for you.
The full contract is the OpenAPI document at sitegpt.ai/api/v2/openapi.json.

Pagination

The SDK has no pagination helper. Because every method returns the whole envelope, you can read meta.nextCursor from the response. Pass it as cursor to get the next page:

query := url.Values{"limit": {"50"}}
for {
	page, err := client.Conversations.List(ctx, chatbotID, query)
	if err != nil {
		panic(err)
	}
	fmt.Println(page["data"])

	meta, _ := page["meta"].(map[string]any)
	next, _ := meta["nextCursor"].(string)
	if next == "" {
		break
	}
	query.Set("cursor", next)
}

Timeouts and custom HTTP clients

Requests time out after 10 seconds by default. To change this, pass your own *http.Client. The SDK keeps its redirect rule, so it still removes the token on a redirect to a different origin:

client := sitegpt.NewClient("YOUR_API_TOKEN", sitegpt.WithHTTPClient(&http.Client{
	Timeout: 60 * time.Second,
}))

The client follows up to 10 redirects. If your *http.Client has its own CheckRedirect, the SDK runs that function after it removes the token. For a time limit on one call, use a context:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
me, err := client.Me(ctx)

Base URL

The base URL is https://sitegpt.ai by default. It is also in the constant sitegpt.DefaultBaseURL. Change it only if SiteGPT gives you a different API address:

client := sitegpt.NewClient("YOUR_API_TOKEN", sitegpt.WithBaseURL("https://sitegpt.ai"))

Get started

Concepts

Add content

Improve answers

Customize the widget

Install

Leads

Human support

Monitor

Integrations

Account and team

Reference

Developers

Help

Install

Quickstart

Responses

Agent onboarding without a token

Error handling

Convenience methods

Analytics

Deletes need confirmation

Other endpoints: `Request`

Timeouts and custom HTTP clients

Base URL

​Install

​Quickstart

​Responses

​Agent onboarding without a token

​Error handling

​Convenience methods

​Analytics

​Deletes need confirmation

​Other endpoints: Request

​Pagination

​Timeouts and custom HTTP clients

​Base URL

​Related

Install

Quickstart

Responses

Agent onboarding without a token

Error handling

Convenience methods

Analytics

Deletes need confirmation

Other endpoints: `Request`

Pagination

Timeouts and custom HTTP clients

Base URL

Related