API Reference

Base URL

https://thalium-chain-executor.fly.dev

Authentication

X-API-Key header with scopes:

• invoke | memory:read | memory:write | memory:admin
• audit:read | config:write | admin

Endpoints

POST /v1/brain/{brainId}/invoke

Request body:

{
  "session_id": "string (required)",
  "entity_id": "string (optional)",
  "input": {
    "type": "text | image | audio",
    "content": "string"
  },
  "role_config": "object (optional)"
}

SSE Events

Event	Timing	Description
fast.triage	0.5-2s	Initial classification
fast.artifact	1-3s	First structured response
full.artifact	6-15s	Complete response
chain.partial	varies	Partial failure artifact
chain.novel	varies	Novel signal detected

GET /v1/brain/{brainId}/status

Returns operational status

GET /v1/brain/{brainId}/memory

Params:

• ring: session | entity | institutional
• address_key: ltree path filter

Partial failure handling

When any role fails, Thalium always returns a structured partial artifact. The chain.partial SSE event is emitted before full.artifact.

{
  "type": "chain.partial",
  "status": "partial",
  "failed_roles": [{ "role": "devil", "reason": "timeout" }],
  "completed_roles": ["triage", "listener", "architect", "scorer"],
  "anchor_trace": {
    "triage": { "status": "complete" },
    "devil": { "status": "failed", "reason": "timeout" },
    "scorer": { "status": "complete" }
  }
}

The Librarian always runs in the finally block. Ring writes from completed roles are committed even on partial failure.

Role failure impact:

• devil failed: output not stress-tested, treat as unchallenged
• scorer failed: no confidence score or gate decision, do not gate on confidence
• boundary_keeper failed: guardrails not applied, surface for human review
• librarian failed: ring write not committed, memory not updated

Error Responses

Code	Meaning
401	Invalid API key
403	Insufficient scope
404	Brain not found
413	Payload too large
429	Rate limited
402	Payment required