Authentication
All API requests require a bearer token. Pass it in the Authorization header.
Tokens are scoped to a single user. They cannot read another user's beliefs, runs, or verdicts — the isolation guarantee is enforced at the token layer, not just the application layer.
Live keys begin el_live_. Test keys begin el_test_. Test runs do not write to your ground truth store and do not consume your monthly run quota.
Base URL
All endpoints below are relative to this base. The API is versioned at the path level. Breaking changes increment the major version; additive changes do not.
Rate Limits
| Tier | Ingest | Runs / month | Verdicts / day |
|---|---|---|---|
| Research | 500 beliefs / day | 20 runs | Unlimited |
| Builder | 5,000 beliefs / day | 200 runs | Unlimited |
| Enterprise | Negotiated | Negotiated | Unlimited |
Rate limit headers are returned on every response: X-RateLimit-Remaining, X-RateLimit-Reset.
POST /ingest
Submit one or more beliefs for inclusion in your Archive. Beliefs are tagged by Mise before being held for a run.
{ "beliefs": [ { "text": "Deliberate practice outperforms raw hours for skill acquisition.", "source": "obsidian://vault/notes/learning-models.md", "kind": "FACT" } ] }
| Field | Type | Description | |
|---|---|---|---|
| text | string | Required | The belief as a declarative statement. One claim per belief. Avoid hedges; the engine introduces them. |
| source | string | URI or reference to the note this came from. Stored but not transmitted to the Brigade. | |
| kind | enum | Override Mise's tagging. One of: FACT, PREDICTION, VALUE, PREFERENCE. Omit to let Mise classify. | |
| tags | string[] | Your own labels, passed through unmodified. Useful for filtering beliefs into a run. |
POST /run
Start a Colosseum run against a selection of your beliefs. The Brigade prosecutes asynchronously; poll GET /verdict or subscribe to the webhook for completion.
{ "belief_ids": ["bel_a1b2", "bel_c3d4"], "webhook_url": "https://your-app.example/elenchi-webhook" }
Returns a run_id immediately. Runs typically complete in 90 to 240 seconds depending on belief count and Brigade depth.
With a test key, runs return synthetic Brigade output in under two seconds. The synthesizer and Socrates both run; verdicts are not written to your ground truth store.
GET /verdict/{run_id}
Retrieve the output of a completed run: Brigade findings, Clarity Index scores, Socrates' audit, and the synthesizer's presentation for each belief.
Note: the verdict object surfaces prosecution findings. It does not include a decision. The engine never rules. Your call to POST /verdict/{run_id}/pass with action keep, kill, or revise writes the decision.
GET /beliefs
List beliefs in your Archive. Supports filtering by kind, tag, and ratification status.
The Belief Object
| Field | Type | Notes |
|---|---|---|
| id | string | Prefixed bel_ |
| text | string | The declarative statement as submitted |
| kind | enum | Mise-assigned or user-overridden |
| clarity_index | number | 0.0 – 1.0. The VS Clarity Index score from the last run. Null if never run. |
| ratified | boolean | True if you have issued a keep action against this belief |
| last_run_at | ISO 8601 | |
| created_at | ISO 8601 |
Request API Access
The API is in private beta. Access is granted to researchers, tool authors, and teams building on top of the refutation engine. Describe your use case below.