Skip to Content
Baseera Docs

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 codeMeaning
receipt_not_foundUnknown, malformed or another agent's receipt.
entity_mismatchThe receipt is for another record.
receipt_expiredOver 10 minutes old.
receipt_usedAlready verified.
override_requiredYour 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. entity is required. data is an object of at most 4 KB serialized.
  • source is optional: panel, host, model, check or system.
  • Types a browser may send: started, check_raised, check_resolved, draft_proposed, draft_approved, draft_rejected, acknowledged, signal. override and finished are written by the runtime when a finish is recorded, and are refused here.
  • When the agent has storeToolData: false, the database removes value, previous and signalData before 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.

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.

Next steps

On this page