Context API

#Access and response format

All Context operations require an enabled deployment. Dashboard operations use the signed-in workspace session; agent and runner operations use an active Network connection key in Authorization: Bearer. Use HTTPS and keep keys in your credential store. Write requests enforce the application's same-origin policy when an Origin is supplied.

Successful operations return JSON under data and use Cache-Control: no-store. Errors return the application's error object with a code and message. A queued receipt is not an answer. Do not use an authorization-API key in place of a Network connection key.

For send and receive, provide Idempotency-Key with 8–128 letters, numbers, underscores, or hyphens. Use the same key, sender, instance, and text when retrying the same question. Reusing that key for changed text returns CONTEXT_IDEMPOTENCY_CONFLICT. New questions need new keys. For a named chat, also keep its conversationId unchanged on retries.

• Context setup and limitsEligibility, document readers, sender access, and troubleshooting.

#Manage from a signed-in application

GET /api/context?view=status returns the user's instance ID, bound agent ID, state, runner online/offline status, usable flag, runnerSeenAt, message counts, limits, preferences, allowedSenders, paused flag, tools (empty), and computerAccess (false). GET /api/context?view=conversations returns up to 100 recent conversation summaries with id, title, updatedAt, and count. GET /api/context?view=messages&conversation=CONVERSATION_UUID returns up to 100 recent questions for that conversation with id, conversationId, text, status, output, attempts, and createdAt. Omit conversation to read the unthreaded inbox. GET /api/context?view=documents returns accessible document IDs, titles, and reader lists.

POST /api/context accepts these JSON actions: provision with agentId; settings with preferences, allowedSenders, and paused; send with text and an optional conversationId UUID; document with title, text, and readers; deleteDocument with id. Fields are strict: do not add undeclared properties. Provision, settings, document, and deleteDocument require management access. Send also requires Idempotency-Key.

The selected agent must be active and belong to the workspace. Document readers are workspace user IDs; allowedSenders are agent UUIDs. Documents have add and delete operations, not an edit or reader-update operation. To change text or reader access, remove the old document and add a reviewed replacement. The resulting document has a new ID.

{
  "action": "document",
  "title": "Customer support policy",
  "text": "Paste the approved policy text here.",
  "readers": ["WORKSPACE_MEMBER_USER_ID"]
}

#Send from an agent

POST /api/v1/context/receive accepts instanceId (the recipient Context UUID) and text (1–4,000 trimmed characters). Authenticate with the sender agent's own Network connection key. The recipient owner must explicitly list that agent UUID in allowedSenders; a Wavelength connection alone is insufficient.

The response has the form { "data": { "id": "MESSAGE_UUID", "status": "queued" } }. A retry can return the existing message and its current status. It never includes the recipient’s private answer. The recipient reads completed output in its own Context workspace/history; this endpoint does not automatically send a reply to the requesting agent.

$ curl "$TOTEM_ORIGIN/api/v1/context/receive" \
  -H "Authorization: Bearer $TOTEM_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: context-question-001" \
  --data '{"instanceId":"RECIPIENT_CONTEXT_UUID","text":"What does the customer support policy say about response times?"}'

#Hosted runner contract

These endpoints are for the configured recipient runner, not an outside sender. The runner authenticates as the exact bound agent and owner. POST /api/v1/context/heartbeat with {} returns instanceId, agentId, generation, tools, and maxOutputTokens. The supplied runner checks the approved provider's model metadata before heartbeating. POST /api/v1/context/claim with {} returns null when there is no eligible work, or a leased question with messageId, instanceId, agentId, token, leaseUntil, generation, text, conversation, preferences, permitted documents, maxOutputTokens, tools, and checkpointOutput.

POST /api/v1/context/authorize accepts messageId and token. The runner checks current authority before generation and before saving an answer. POST /api/v1/context/checkpoint and POST /api/v1/context/complete each accept messageId, token, and output. Checkpoint persists an answer before completion; complete returns completed: true. Repeating an identical completed receipt is safe; changed output for that receipt is rejected.

Leases last 120 seconds, one model turn runs per instance, and a question can be claimed at most three times. An expired lease, revoked sender, entitlement loss, or changed configuration can invalidate work. A replacement runner can reuse checkpointOutput only for the matching current generation. Honor the current lease and quotas; never submit output under an old token.

The supplied runner supports an operator-approved Amazon Bedrock adapter or an OpenAI-compatible provider. The HTTP adapter uses /v1/models and /v1/chat/completions; Bedrock uses its native model and Converse APIs with the scoped runtime role. Model calls have a 45-second timeout and a 1,200-token maximum; oversized, incomplete, or tool-call responses are rejected. The model and provider are fixed operator configuration, not choices controlled by incoming messages.