> ## Documentation Index
> Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent REST API

> The /v1/agent event model: turns, ordered event pages, opaque cursors, terminal states, sessions, and action results.

The Agent resource lives at `/v1/agent` and owns conversation state. For TypeScript, the [Agent API](/docs/integrate/agent) SDK surface drives this same resource for you. See the [Overview](/docs/api-reference/overview) for authentication and request conventions.

## The event loop

Start a turn with `POST /v1/agent/chat`, then poll `GET /v1/agent/chat/{sessionId}` until the turn reaches a terminal state. Every response is an event page:

```json theme={null}
{
  "session_id": "demo-session-8b5f",
  "cursor": "opaque-cursor",
  "events": [],
  "has_more": true
}
```

Messages, tool activity, actions, errors, and lifecycle changes are entries in `events`; they are not separate top-level response fields.

* Apply events in sequence order, and repeat while `has_more` is true or the latest turn state is `processing`.
* Stop at `complete`, `failed`, `interrupted`, or `awaiting_action`.
* `wait` is an integer long-poll duration in milliseconds, bounded to `30000`. A typical client request uses `wait=25000`.
* Keep the cursor opaque. An expired cursor returns `410`, and a malformed or cross-session cursor returns `400 invalid_cursor`; in either case, request the session without a cursor and reconcile the returned event page.

## Sessions

Session ownership comes from the authenticated caller. Do not use a wallet address as an ownership key.

## Action results

Action resolution requires its own permission (`agent:actions:resolve`) and an idempotency key. Submit only the result produced by the reviewed request — never replace the action payload with caller-authored transaction fields. The request body is `{ "revision": number, "result": ActionResult }`; the response contains the resulting action revision.

## Live stream

`GET /v1/agent/chat/{sessionId}/stream` is an SSE projection over the same event log. It emits three SSE event names:

| Event     | Meaning                                                               |
| --------- | --------------------------------------------------------------------- |
| `page`    | A durable `EventPage`; persist its opaque cursor for reconnects.      |
| `message` | A transient in-progress message snapshot.                             |
| `resync`  | The stream could not project a safe delta; fetch an event page again. |

Reconnect with the last cursor from a `page` event. A `message` event is useful for rendering live text, but it is not a durable cursor.