HTTP API

Everything MCP exposes is plain HTTP underneath. If you are building your own agent loop, call your cell directly.

Your cell URL is on your dashboard. The examples below use the shared managed cell.

Authentication#

Every call carries an agent-scoped key as a bearer token:

curl https://aws-us1.cells.sioma.ai/v1/focus \
  -H "Authorization: Bearer $SIOMA_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "intent": "list this customer unpaid invoices" }'

POST /v1/focus#

The minimal grounded context for one intent.

Request: intent (required), plus optional userId, sessionId, and trace to include the resolver trace, which is off by default.

Response:

{
  "recordId": "…",
  "status": "serve",
  "verified": false,
  "systemText": "…give this to your model…",
  "tools": [{ "name": "…", "description": "…" }]
}

status is serve, ask, or none. Treat ask as a question to put to your user, and none as a red flag: there is nothing in the map that answers this.

POST /v1/outcome#

Report what happened, using the recordId from a prior focus.

{
  "recordId": "…",
  "success": true,
  "inputTokens": 812,
  "outputTokens": 96
}

correct is optional and is recorded as a self-report, never as verified truth. Sending token counts is what makes savings visible in Insights.

GET /v1/insights, /v1/savings, /v1/usage#

Read your own numbers: what was served, what it cost, and what it saved. All three take an optional time window.

TypeScript client#

@sioma/client is a zero-dependency wrapper over the same endpoints:

import { SiomaClient } from "@sioma/client";

const sioma = new SiomaClient({
  baseUrl: "https://aws-us1.cells.sioma.ai",
  apiKey: process.env.SIOMA_API_KEY!,
});

const f = await sioma.focus({ intent: "list this customer unpaid invoices" });
// f.status: "serve" | "ask" | "none"; f.systemText goes to your model.

await sioma.outcome(f.recordId, {
  success: true,
  inputTokens: 812,
  outputTokens: 96,
});

A non-2xx response throws a SiomaClientError carrying the HTTP status and the server's own reason, so a failure tells you what went wrong rather than just that something did.

Vercel AI SDK#

@sioma/vercel wires the same thing into an AI SDK app, so focus and outcome become tools your model can call directly.

Rails endpoints#

A workspace with rails enabled also gets /v1/rail/*, matching the four passenger tools in Agent tools. Rails are off by default.