Eli customer read API¶

Read your organisation’s active agents, descriptions, stored assessments, and obligations using your own API key.

Authentication¶

Open Eli → Settings → API access. Reveal or copy Your API key, then send it in the X-API-Key header. The key is the signed-in user’s existing credential. The account must be approved, enabled, and active, and must have active membership in its active primary organisation.

Base URL: https://app.carveragents.ai/api/v1/eli

These endpoints require X-API-Key; a bearer token alone is not sufficient. They return data only for the caller’s primary organisation, including for users with platform admin roles. They do not require a super-admin credential.

Endpoints¶

Method	Path	Response
GET	`/agents?limit=100&offset=0`	`organization_id`, `total`, `limit`, `offset`, and `items` containing agent summaries and assessment states
GET	`/agents/{agent_id}`	Agent details, `customer_tier`, `facts`, submitted `twin`, and the stored `assessment` JSON
GET	`/agents/{agent_id}/obligations`	One JSON document containing `agent_id`, `twin_version`, `mapping_status`, `assessment_is_previous`, `total`, and an `obligations` array

Agent IDs are UUIDs. Agent listing accepts a limit of 1–200 (default 100) and a nonnegative offset. Continue paging until all total agents have been read. Disabled and deleted agents are excluded. Locked agents appear in the list; detail and obligation reads return 402 until the plan opens them.

Each obligation contains its act_id, obligation_id, assessment content, and the organisation’s recorded decision fields. Organisation scope limits apply to assessment acts and obligations. The total on the obligations response is the number returned, not a claim of exhaustive legal coverage.

Examples¶

Set ELI_API_KEY in your server environment or secret store before running these examples.

curl --fail-with-body \
  -H "X-API-Key: $ELI_API_KEY" \
  'https://app.carveragents.ai/api/v1/eli/agents'

Replace YOUR_AGENT_UUID with an ID returned by the list endpoint:

curl --fail-with-body \
  -H "X-API-Key: $ELI_API_KEY" \
  'https://app.carveragents.ai/api/v1/eli/agents/YOUR_AGENT_UUID'

curl --fail-with-body \
  -H "X-API-Key: $ELI_API_KEY" \
  'https://app.carveragents.ai/api/v1/eli/agents/YOUR_AGENT_UUID/obligations'

Assessment progress¶

These routes read existing assessments; they do not create or update an agent. Poll detail or obligations to observe mapping_status. A pending or in_progress assessment may retain the preceding result while the new one runs. assessment_is_previous: true explicitly identifies that retained result. An agent without stored results returns assessment: null and an empty obligations array.

Errors¶

401: missing, invalid, disabled, or otherwise unusable key; bearer-only requests are also rejected.
403: account approval or active organisation membership is missing.
404: agent is unavailable in the caller’s organisation. IDs belonging to other organisations receive the same response.
402: the agent is locked by the organisation’s plan.
422: invalid UUID or pagination values.

Retrieve your key in Eli¶

The Settings control uses bearer-authenticated GET /api/v2/core/auth/api-key, proxied by Eli at /api/session/api-key. It returns only the caller’s existing api_key with Cache-Control: no-store. The key is not generated or rotated when Settings is opened and is not stored separately in the browser by this control.

Submit or revise a standalone agent¶

POST /agents accepts name, description, optional client_ref, optional context, and optional base_version: 0. Send X-API-Key and a unique Idempotency-Key. It returns 202 with the registered agent and queued description version. Preparation and mapping run asynchronously; poll the existing agent detail route.

POST /agents/{agent_id}/assessments accepts the same fields with the current base_version. It returns 202 for a new immutable description version, or 409 if another update has superseded that base. Client references cannot change. Identical idempotency-key replays return the existing accepted version; different input with the same key returns 409. There is a default daily allowance of 24 standalone API submissions per organisation.

Standalone-agent quotas, locks, organisation scoping, and enabled review-role requirements apply. These routes cannot edit Workflow components. Workflow submissions are independent; see the Workflow API.