Other endpoints
Finish receipts, immersive trail and AI checks, server signals, eval runs from CI, and the agent theme.
These endpoints support immersive mode (a user working on one record), server-originated events and CI. Authentication is the same as everywhere else. See Authentication.
Record a finish
POST /v0/sessions/{sessionId}/finish is a browser call. The SDK makes it when the person finishes a record in immersive mode, before your own finish action.
Prop
Type
{
"entity": { "type": "invoice", "ref": "inv_1042" },
"openBlocking": ["tax-id-missing"],
"override": { "reason": "Customer confirmed the tax ID by phone", "checks": ["tax-id-missing"] }
}Response 200:
{ "receipt": "fin_...", "expiresAt": "2026-11-09T10:10:00.000Z" }A receipt is valid for 10 minutes and for one verification. It stores who finished (user id, tenant id), when, the open blocking ids and the override. Errors: session_not_found, invalid_request, plus authentication errors.
Verify a finish
POST /v0/finish/verify is a server call with a server token of purpose verify_finish. Your finish route sends the receipt its browser got and, if it can, the blocking check ids your own server found open.
{ "receipt": "fin_...", "entity": { "type": "invoice", "ref": "inv_1042" }, "openBlocking": ["tax-id-missing"] }Everything answers 200, except bad authentication (401 invalid_server_token) and a bad body (400 invalid_request):
{ "ok": true, "finish": { "userId": "user_42", "tenantId": "t1", "openBlocking": ["tax-id-missing"], "override": { "reason": "...", "checks": ["tax-id-missing"] }, "createdAt": "2026-11-09T10:00:00.000Z" } }{ "ok": false, "code": "receipt_used" }| Refusal code | Meaning |
|---|---|
receipt_not_found | Unknown, malformed or another agent's receipt. |
entity_mismatch | The receipt is for another record. |
receipt_expired | Over 10 minutes old. |
receipt_used | Already verified. |
override_required | Your openBlocking is not covered by the receipt's override, or there is no reason. |
A successful verification marks the receipt used in the same transaction. A refusal never does. verifyFinish in @baseera/node wraps this call and fails closed: any error is a refusal.
Check results come from the browser, so Baseera cannot vouch that they are true. The guarantee is narrower: the finish is recorded first as a single-use receipt, and your server verifies it before it changes anything.
Append trail events
POST /v0/sessions/{sessionId}/immersive/events is a browser call. The SDK sends what happens to the record, in batches. The response is 204 No Content.
{
"events": [
{ "type": "started", "entity": { "type": "invoice", "ref": "inv_1042" }, "source": "system", "data": { "title": "Invoice 1042" }, "at": "2026-11-09T10:00:00.000Z" }
]
}- At most 100 events per request.
entityis required.datais an object of at most 4 KB serialized. sourceis optional:panel,host,model,checkorsystem.- Types a browser may send:
started,check_raised,check_resolved,draft_proposed,draft_approved,draft_rejected,acknowledged,signal.overrideandfinishedare written by the runtime when a finish is recorded, and are refused here. - When the agent has
storeToolData: false, the database removesvalue,previousandsignalDatabefore storing.
The trail is the browser's account of what happened. It records, and it does not prove.
Run AI checks
POST /v0/sessions/{sessionId}/immersive/ai-checks is a browser call. Send the record as in a turn, with aiChecks listing the check ids you opted into.
{ "immersive": { "entity": { "type": "invoice", "ref": "inv_1042" }, "fields": [{ "name": "lines", "label": "Lines", "kind": "text", "value": "Late fee 25%" }], "checks": [], "aiChecks": ["policy-conflict"] } }{ "results": [{ "id": "policy-conflict", "ok": false, "message": "A 25% late fee is above the 5% limit in the fee policy.", "fields": ["lines"], "sources": [{ "ref": "S1", "title": "Finance policies", "section": "Late fees" }], "severity": "warning", "blocksFinish": false }] }Only checks defined on the agent's latest version and listed in aiChecks run. Severity, instruction and canBlockFinish come from the agent, never from the request. Results are cached per session, record, check, agent version and a hash of the field values. At most 20 model runs per record per session and one every 5 seconds. Past the cap the answer carries cached results and "capped": true, or "retryAfterMs" inside the interval. Rate limit: 30 a minute per user.
Errors: session_not_found, invalid_request, agent_not_configured, provider_key_missing, the provider errors a turn can return, plus authentication errors.
Send a server signal
POST /v0/signals lets your backend tell Baseera that something happened to a record while nobody had it open. Server token with purpose signal.
Prop
Type
{ "entity": { "type": "invoice", "ref": "INV-7" }, "name": "payment.received", "data": { "amount": 120.5, "currency": "SAR" }, "tenantId": "acme" }The optional Idempotency-Key header (8 to 128 of A-Za-z0-9_.:-) makes a retry safe. The same key with the same content answers 200 { "ok": true, "id": 41, "duplicate": true }. Different content gives 409 idempotency_conflict. A new signal answers 200 { "ok": true, "id": 41, "duplicate": false }.
Unknown fields are refused and the body is at most 8 KB. Signals are kept 30 days, the newest 50 per record and 10,000 per agent. A signal makes the record's cached AI checks stale and the newest five reach the checks' model as untrusted data. It cannot change a check result by itself.
import { createBaseera } from "@baseera/node";
const baseera = createBaseera({ agentId, secretKey, baseUrl });
await baseera.signal({ type: "invoice", ref: "INV-7" }, "payment.received", { amount: 120.5, currency: "SAR" });Run an eval suite from CI
POST /v0/evals/runs starts one of the agent's test suites and GET /v0/evals/runs/{id} reads the result. Server token with purpose eval_run. A run calls the model with your organization's own provider key, so it costs money, and nothing starts unless confirmCost is the boolean true.
Prop
Type
{ "suiteName": "core", "target": "production", "repeats": 1, "confirmCost": true }Unknown fields are refused. The body is at most 4 KB. The answer is 202:
{
"run": { "id": "...", "status": "queued", "total": 24, "completed": 0, "passed": 0, "failed": 0, "errored": 0, "passRate": 0, "minPassRate": 100, "failingCases": [], "attempts": [] },
"estimate": { "attempts": 24, "inputTokens": 91000, "outputTokens": 14400, "costUsd": 0.31, "provider": "anthropic", "model": "claude-sonnet-5-5" }
}Poll GET /v0/evals/runs/{id} until status is done, failed or stopped. A run passes when passed * 100 >= minPassRate * total. The result holds counts, up to 500 attempts and up to 100 failing cases with their failed checks. It never holds transcripts, case inputs, tool data or model output.
Limits: 500 attempts per run, one queued or running run per agent (409 eval_run_in_progress), 30 runs per agent per hour (429 eval_limit_reached), 120 calls a minute per secret key. A run starts when the eval worker picks it up, which can take up to a minute. Another agent's suite or run answers 404 eval_not_found.
Read the agent's theme and logo
GET /v0/agent/theme needs the publishable key and an allowed origin, and no user token. It is the agent's look, the same for every user.
{
"theme": {
"critical": { "light": "#8a0f2c", "dark": "#ff8aa5" },
"accent": { "light": "#3a86a4" },
"radius": "12px",
"font": "serif",
"logo": "0b3f2f4e-9c1a-4c0e-8a7e-1d2f3a4b5c6d"
}
}theme is null when the owner set none. It holds only plain colours, a radius from 0px to 32px, a font word (system, serif, rounded or mono) and a logo id.
GET /v0/agent/logo/{logoId} answers the logo's bytes as PNG or WebP (at most 256 KB and 512 by 512). A host with a CSP needs img-src blob:, because the SDK shows it from a blob: URL.
Both are rate limited (theme: 1,200 a minute per key and 60 per network address; logo: 600 and 30) and cached with an ETag. They support If-None-Match and answer 304 Not Modified.