HTTP API

Anything that can send an HTTP request can use Assent. The command line and the MCP server use the same API.

Base URL and authCopy Anchor Link

https://ordia-api.specvista.com/api/v1

Send JSON bodies, and the agent key as a bearer token:

Authorization: Bearer <your agent key>

Agent keys start with oak_. A person creates one in Assent: Agents, Add agent, then copy the key, which is shown once. Their email address must be verified first. If a key leaks, they open the agent's settings and choose Rotate key; the old key stops working. See Connect an agent.

There is no OpenAPI document yet. This page and Asks describe every field.

Ask the personCopy Anchor Link

POST /agent/ask sends an ask to the person's inbox. Every ask needs kind and title; phrase the title as an action or a question.

Optional fields include detail, items (each with id, title and selected), actions (up to 6, each with id, label and an optional style of primary, secondary or danger), dueAt, remindAt, dedupeKey, runUuid, and action with target so the person can answer Always or Never. Asks covers every field.

curl -X POST https://ordia-api.specvista.com/api/v1/agent/ask \
  -H "Authorization: Bearer $ASSENT_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b8e-3f43-4c3a-9d55-0f3a4c1b2e7d" \
  -d '{"kind":"approve","title":"Deploy build 512 to production?","why":"All checks passed on the release branch","action":"deploy:web","target":"production"}'

A new ask returns 201 with the task and its uuid. Sending the same dedupeKey or the same Idempotency-Key header (a UUID) returns the existing ask with 200 and created set to false. Reusing an Idempotency-Key for a different request is refused with 422. An ask that a standing rule answers comes back already answered.

Get the answerCopy Anchor Link

An ask starts as open and becomes answered when the person answers. Its answer holds actionId, selectedItemIds and, for code and reply asks, value. Asks other than todo expire if nobody answers in time; answerExpiresAt says when.

There is no long-poll endpoint. Poll GET /agent/tasks/{uuid} every few seconds, or use the MCP tool assent_wait_for_answer or assent ask --wait. When you have acted on the answer, call POST /agent/tasks/{uuid}/picked-up so it is never delivered again.

EndpointsCopy Anchor Link

ErrorsCopy Anchor Link

Errors are JSON with the HTTP status in statusCode, a short error, and a message that says what to change. Some also carry a stable code, such as IDEMPOTENCY_KEY_REUSED:

{"message":"Agent key required","error":"Unauthorized","statusCode":401}