BUILD ON IT / ELPIS

API reference

Authentication, jobs, proof evaluation, replay and financial operations. All responses should be treated as structured data, not text to guess from.

Request conventions

All API calls use HTTPS. Scoped keys are sent as Bearer tokens and must stay on your server.

Headers

Authorization: Bearer $ELPIS_API_KEY
Content-Type: application/json
Idempotency-Key: one-key-per-intended-write

Responses generally contain a data object or structured error details. A rate limit returns HTTP 429 with a Retry-After header and says which limit was reached: wait that long before retrying. The defaults and how to ask for more are in the API limits guide. See the complete OpenAPI 3.1 document for parameters and bodies.

Many writes have real effects. Evaluating a policy is not the same as proposing or authorizing a payment. Never retry a non-idempotent financial operation blindly.

Jobs and evidence

Method and path	Purpose
`POST /api/v1/jobs`	Commit acceptance conditions. Requires propose scope.
`GET /api/v1/jobs`	List this organization's jobs. Requires read scope.
`POST /api/v1/jobs/{id}/verify`	Dry-run submitted evidence against the committed condition; read scope.
`POST /api/v1/jobs/{id}/settle`	Record a deterministic decision; propose scope; no guaranteed chain transfer.
`POST /api/v1/attestations/{id}/replay`	Recompute a stored decision; read scope.
`POST /api/v1/settle/preview`	Public deterministic playground evaluation without signing or fund movement.

Untrusted witness names, signer lists or arbitrary oracle strings do not become authenticated evidence merely because they appear in JSON. The standalone Jobs API refuses unsupported external-evidence releases.

Treasury operations

Read the generated OpenAPI specification for action initiation, approvals, accounts, limits, ledger, recoverability, and incidents. These functions can cross different trust boundaries and are not interchangeable with a job-preview request.

The authenticated Developer workspace shows scoped keys and usage. Treasury operations describes the workflow before real-money execution.

MCP and SDKs

The MCP endpoint is POST /api/mcp, with scoped permissions. TypeScript and Python SDK surfaces are available in the repository. Treat an agent as an untrusted caller subject to the same policy limits as any other API client.

Continue with Integrations, Agents and MCP, and Webhooks.

Failures are outcomes

Status	Typical interpretation
400	Malformed or unsupported input.
401	Missing or invalid credential.
403	Insufficient scope.
409	Conflicting job state, unacceptable evidence or incompatible retry.
422	Trusted evidence is required by a condition.
429	Rate limit; respect the server's retry guidance.