Aex Brain
HTTP APIAPI

API

Sessions, messages, events and integration endpoints.

List sessions

Lists sessions belonging to the caller's tenant in ascending ID order. Pass the last session ID as after to fetch the next page.

Create a session

Creates a session for the caller's tenant with the given harness, model, instructions, reasoning effort, and tools. Requires a management token. Creating a session records its metadata locally; the harness process starts when the first message is sent.

Delete a session

Settles execution, revokes executors, and removes local private state, events, native files and online checkpoints. A retained tombstone prevents restoration. Repeat after a failed cleanup; success means online cleanup completed. Independently retained backups follow their retention policy.

Get a session

Returns metadata and current status for a session. If the session is not on local disk and external storage is configured, Brain loads the latest published checkpoint.

Close a session

Permanently closes a session and stops any active or queued work. Requires a management token. Event history remains readable.

Read or stream events

Returns a page of retained events as JSON, or streams history and live updates when called with Accept: text/event-stream. Pass after (or Last-Event-ID) with the last retained event's cursor to resume from a known position. Returns 409 cursor_unavailable if the cursor points to an unsynced tail lost during restore.

Send input

Queues a user.message (with text and an optional idempotency key) or requests an interruption with user.interrupt. Returns 202 Accepted once the input is recorded locally.

Flush external state

Uploads local event history and the latest completed checkpoint to external storage and returns the resulting checkpoint reference. Requires a management token and configured persistence.

Restore a checkpoint

Replaces local session state with a specific checkpoint from external storage. Requires a management token and settled local execution.

Resume a session

Moves an interrupted or failed session back to idle from its last completed checkpoint. Requires a management token. Send a new user.message after resuming to continue the conversation.

Read synchronization status

Returns the latest published checkpoint, pending upload state, and any sync error for the session. Requires configured persistence.

Register runtime tools

Requires management authority. Connect the returned executor before creating the session. Rebinding supplies the saved session and matching descriptors; functions remain in the client.

Close a runtime executor

Requires its executor credential. Pending dispatched calls receive unknown outcomes; future calls are unavailable.

Connect a runtime executor

Requires the executor credential. Returns non-replayable SSE commands and a ready connection identity. A dropped connection never replays calls.

Submit runtime progress or result

Requires the executor credential and current connection/call identity. Stale, duplicate and unsolicited results fail.

Connect bidirectional runtime RPC

WebSocket upgrade using brain-rpc and brain-auth.TOKEN subprotocols. Commands and replies use the same contract as SSE/HTTP. Browser origins are rejected.