Agent API

A bearer-token REST API for agents and scripts. Base URL: https://constitute.splashstudio.ai/api/v1. The tenant is derived from the key. Bodies are JSON, success bodies start with "version": 1, and failures are { "error": "…" }.

curl https://constitute.splashstudio.ai/api/v1/state \
  -H "Authorization: Bearer cst_live_…"

Routes

Route	Scope	Notes
`GET /api/v1/state`	`state:read`	Counts, lanes, Convention progress, amendments.pending, warnings.
`GET /api/v1/drafts`	`drafts:read`	List drafts.
`POST /api/v1/drafts`	`drafts:write`	Create a draft. Idempotent with clientRequestId. Returns 412 until the Bill of Rights is complete.
`POST /api/v1/drafts/{id}/ratify`	`drafts:decide`	Ratify.
`POST /api/v1/drafts/{id}/veto`	`drafts:decide`	Veto, with an optional reason.
`POST /api/v1/drafts/{id}/edit`	`drafts:decide`	Edit the text.
`POST /api/v1/drafts/{id}/mark-posted`	`drafts:decide`	Mark a manual-lane draft as posted.
`POST /api/v1/drafts/{id}/publish-next`	`drafts:decide`	Publish the next ratified draft.
`GET /api/v1/kpis`	`kpis:read`	Ratified-as-drafted rate and friends.
`GET /api/v1/amendments`	`amendments:decide or state:read`	List amendments.
`POST /api/v1/amendments/{id}/accept \| reject`	`amendments:decide`	Decide. Accepting applies it.
`PATCH /api/v1/amendments/{id}`	`amendments:decide`	Edit proposed text, type, target or mode.
`GET /api/v1/corpus/search`	`corpus:read`	Hybrid search across your Articles.
`GET /api/v1/constitution`	`corpus:read`	The always-on context.
`POST /api/v1/corpus/propose`	`corpus:propose`	Propose an entry (a pending amendment).
`POST /api/v1/convention`	`convention:run`	Same state machine as run_convention.
`POST /api/v1/session`	`convention:run`	Same state machine as run_session.

Submit a draft

curl -X POST https://constitute.splashstudio.ai/api/v1/drafts \
  -H "Authorization: Bearer cst_live_…" \
  -H "Content-Type: application/json" \
  -d '{"platform":"linkedin","title":"Why we did not raise",
       "body":"…","citedEntryIds":["<article-id>"],
       "clientRequestId":"2026-w41-post-1"}'

Status codes

Status	Meaning
400	Bad input.
401	Missing, revoked or unknown key. Fails closed.
402	Plan limit reached.
403	The key lacks the required scope.
404	No such id.
409	It moved on; the record changed since you read it.
412	Drafting is locked until the Bill of Rights is complete.

Replay and idempotency

Decisions are replay-safe: ratifying an already ratified draft returns 200 with noop: true. Draft creation is idempotent on clientRequestId.

What this API will not do

Publish a draft that you have not ratified. There is no path from Draft to a publishing engine in one step.
Change your Constitution on its own. Proposals are pending until accepted, and accepting needs the amendments:decide scope.
Return a secret, a token or an engine key.