API reference.
Start a research Run in a new Case, then retrieve its current Case state and 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. Clerk credentials do not work with the Aculeus API; use the workspace key beginning with acu_live_. 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.
Prepare a Case Plan without starting research. Body: { subject, casePlan }. Show the returned plan to the customer and retain its Case, revision, presentation, and nonce fields for confirmation.
# 1. Prepare and show the Case Plan (this creates no Run)
curl -X POST https://aculeus.ai/api/v1/runs/prepare \
-H "Authorization: Bearer acu_live_…" \
-H "Content-Type: application/json" \
-d '{"subject":"Understand Acme Corp federal lobbying and contracts","casePlan":{"purpose":"diligence","objective":"Assess the scale and pattern of Acme Corp federal lobbying and contracts","time_window":"Use the longest comparable recent record","jurisdictions":["United States"],"entities":[{"name":"Acme Corp","role":"subject"}],"evidence":[{"family":"Federal lobbying disclosures and contract awards"}],"lines_of_inquiry":["How have lobbying and contract activity changed over time?"],"exclusions":[],"open_questions":[],"thin":false}}'Confirm the exact plan the customer saw and start its Run. Send { caseId, revisionId, presentationId, presentationNonce, intent?, researchTier? } from the prepare response plus a unique Idempotency-Key header. Client-supplied subject or Case Plan JSON is not launch authority.
# 2. Confirm the exact presentation after the customer accepts it
curl -X POST https://aculeus.ai/api/v1/runs \
-H "Authorization: Bearer acu_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: customer-launch-REPLACE_ME" \
-d '{"caseId":"REPLACE_CASE_ID","revisionId":"REPLACE_REVISION_ID","presentationId":"REPLACE_PRESENTATION_ID","presentationNonce":"REPLACE_PRESENTATION_NONCE","intent":"diligence"}'List the workspace's Runs, newest first: id, state, intent, subject, and timestamps.
Retrieve one Run plus the living Case head currently readable for its Case. The response includes `case_head` and a legacy compatibility field named `read`; either can be null while no readable Case head exists.
Export the current readable Case body and its source ledger as JSON, including source title, URL, publisher, and quality where available.
# 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_…"The export returns 409 while the Case has no readable Case head. Poll GET /runs/{id} until case_head is present.
Errors & limits¶
Errors return a JSON { error, message? } with a standard status: 401 (missing, invalid, or revoked key), 402 (the workspace plan cannot accept another Run), 404 (no such Run in your workspace), or 409 (no readable Case head exists yet). 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 move to a new version rather than silently changing the v1 contract. Need a field or integration that is not documented here? hello@aculeus.ai.