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:
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.
| Caller | Examples | Credentials |
|---|---|---|
| Browser | Sessions, turns, tool results, feedback, source links | Publishable key, an allowed Origin, and a user token |
| Your server | Push knowledge, verify a finish, send a signal, run an eval suite, purge a tenant | Agent 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 usetext/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 aretrn_..., messagesmsg_..., tool callscall_..., finish receiptsfin_..., uploadsupl_..., webhook eventsevt_.... 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 path | Caller | Page |
|---|---|---|
POST /v0/sessions | Browser | Sessions |
GET /v0/sessions/{sessionId} | Browser | Sessions |
POST /v0/sessions/{sessionId}/turns | Browser | Messages and streaming |
GET /v0/sessions/{sessionId}/turns/{turnId}/events | Browser | Messages and streaming |
POST /v0/sessions/{sessionId}/turns/{turnId}/cancel | Browser | Messages and streaming |
POST /v0/sessions/{sessionId}/tool-results | Browser | Tools and approvals |
GET /v0/sessions/{sessionId}/sources/{ref} | Browser | Messages and streaming |
POST /v0/sessions/{sessionId}/messages/{messageId}/feedback | Browser | Feedback |
GET /v0/agent/theme, GET /v0/agent/logo/{logoId} | Browser | Other endpoints |
POST /v0/sessions/{sessionId}/finish, .../immersive/events, .../immersive/ai-checks | Browser | Other endpoints |
POST /v0/knowledge/{kbId}/items, GET and DELETE .../items/{externalId}, POST .../uploads | Server | Knowledge |
/v0/tenant-knowledge/* | Browser with upload token | Knowledge |
DELETE /v0/knowledge/tenants/{tenantId} | Server | Knowledge |
POST /v0/finish/verify, POST /v0/signals, POST /v0/evals/runs, GET /v0/evals/runs/{id} | Server | Other endpoints |