API reference.
Start a Case, then pull it and its full source ledger programmatically. Authentication is a per-workspace API key.
Authentication¶
Every request authenticates with a workspace API key. A workspace owner or admin issues keys from Account → API keys. The full key is shown once at creation and never again — store it like a password; only its hash is kept on our side. Pass it as a bearer token (or the x-api-key header):
curl https://aculeus.ai/api/v1/me \
-H "Authorization: Bearer acu_live_…"Keys are scoped to the workspace that issued them; a request can only read that workspace's Cases. Revoke a key any time from the same screen — revocation takes effect immediately. Base URL: https://aculeus.ai/api/v1.
Endpoints¶
Your key's workspace, plan, seat count, and scopes. The quickest way to confirm a key works.
Start a Case. Body: { subject, intent?, researchTier? } — subject is what to investigate. Returns { runId, state }. The Case runs the full pipeline asynchronously; poll GET /runs/{id} until its `read` is present.
# Start a Case
curl -X POST https://aculeus.ai/api/v1/runs \
-H "Authorization: Bearer acu_live_…" \
-H "Content-Type: application/json" \
-d '{"subject":"Acme Corp 2026 federal lobbying and contracts","intent":"diligence"}'List the workspace's Cases, newest first: id, state, intent, subject, and timestamps.
A single Case's status. Once it has drafted and cleared the ship gate, the response includes the Answer Brief body, its source_index, and the confidence.
The full source-ledger export: the Case body plus every source with its title, URL, publisher, and quality. This is the programmatic 'distribution' path — pull the finished, sourced piece into your own pipeline.
# Fetch a Case and its source ledger
curl https://aculeus.ai/api/v1/runs/REPLACE_RUN_ID/export?format=json \
-H "Authorization: Bearer acu_live_…"A Case that is still running, or that the ship gate parked for review, returns 409 rather than a half-finished export — poll GET /runs/{id} until read is present.
Errors & limits¶
Errors return a JSON { error, message? } with a standard status: 401 (missing, invalid, or revoked key), 404 (no such run in your workspace), 409 (the Case isn't ready or is held for review). Keys are rate-limited per key; sustained overuse returns 429 with a retry-after header.
Versioning & what's next¶
The surface is versioned in the path (/api/v1); breaking changes ship under a new version, never in place. Next on the roadmap: additional export formats and Dispatch-render access. Need something specific? hello@aculeus.ai.