Skip to Content
Baseera Docs

API reference

The Baseera runtime API: base URL, versioning, conventions and the objects you will meet.

The runtime API is what the Baseera SDK talks to. You can call it directly from a server or a custom client when you need something the SDK does not cover, such as pushing documents from your backend or running a test suite from CI.

Most apps never call the API by hand. @baseera/react and @baseera/core run the browser side, and @baseera/node wraps the server side. Use this reference when you build your own client or want to know exactly what goes over the wire.

Base URL

Every request goes to the runtime URL of your deployment. It is the same value you pass as baseUrl to the SDK. The examples in this reference use an environment variable:

Shell
export BASEERA_URL="https://your-runtime.example.com"

Versioning

Every path starts with /v0. A breaking change ships as /v1 next to it, so existing integrations keep working. You can send the header x-baseera-protocol: v0, but the path already says it, so the header is optional.

There is no dated changelog for the API yet. The version in the path is the only version.

Two kinds of caller

The API has two sides, and each uses different credentials.

CallerExamplesCredentials
BrowserSessions, turns, tool results, feedback, source linksPublishable key, an allowed Origin, and a user token
Your serverPush knowledge, verify a finish, send a signal, run an eval suite, purge a tenantAgent id and a server token signed by a secret key

See Authentication for the exact headers.

Conventions

  • JSON in, JSON out. Requests and responses use application/json, except streams, which use text/event-stream.
  • Errors share one shape. Every non-2xx response is { "error": { "code", "message", "retryAfter"? } }. See Errors.
  • Unknown fields are rejected on most write endpoints, so a typo does not silently change behavior.
  • Timestamps are ISO 8601 in UTC.
  • Ids are opaque strings. Sessions are ses_ plus 32 hex characters. Turns are trn_..., messages msg_..., tool calls call_..., finish receipts fin_..., uploads upl_..., webhook events evt_.... Do not parse them.
  • The runtime is stateless between requests. Turn state lives in the database, so any instance can continue a turn. That is why tool specs are sent again with tool results.
  • CORS. Successful browser responses allow only the agent's allowed domains. Error responses allow any origin so the SDK can read the error code. Cookies are never used.

The objects

Prop

Type

Endpoints at a glance

Method and pathCallerPage
POST /v0/sessionsBrowserSessions
GET /v0/sessions/{sessionId}BrowserSessions
POST /v0/sessions/{sessionId}/turnsBrowserMessages and streaming
GET /v0/sessions/{sessionId}/turns/{turnId}/eventsBrowserMessages and streaming
POST /v0/sessions/{sessionId}/turns/{turnId}/cancelBrowserMessages and streaming
POST /v0/sessions/{sessionId}/tool-resultsBrowserTools and approvals
GET /v0/sessions/{sessionId}/sources/{ref}BrowserMessages and streaming
POST /v0/sessions/{sessionId}/messages/{messageId}/feedbackBrowserFeedback
GET /v0/agent/theme, GET /v0/agent/logo/{logoId}BrowserOther endpoints
POST /v0/sessions/{sessionId}/finish, .../immersive/events, .../immersive/ai-checksBrowserOther endpoints
POST /v0/knowledge/{kbId}/items, GET and DELETE .../items/{externalId}, POST .../uploadsServerKnowledge
/v0/tenant-knowledge/*Browser with upload tokenKnowledge
DELETE /v0/knowledge/tenants/{tenantId}ServerKnowledge
POST /v0/finish/verify, POST /v0/signals, POST /v0/evals/runs, GET /v0/evals/runs/{id}ServerOther endpoints

Next steps

On this page