REST & WebSocket API

ANT exposes a REST and WebSocket surface for tools that need to read or control the operational graph: sessions, rooms, participants, messages, prompt state, terminal history, run events, tasks, file refs, and health.

Authentication

When ANT_API_KEY is configured, external callers can authenticate with Authorization: Bearer <key>, X-API-Key: <key>, or ?apiKey=<key>. Same-origin browser calls are handled by the app.

curl http://localhost:6458/api/sessions \
-H "Authorization: Bearer YOUR_KEY"

Sessions

Method	Path	Description
`GET`	`/api/sessions`	List active sessions plus recoverable archived/deleted rows.
`POST`	`/api/sessions`	Create a terminal, chat, or agent session.
`GET`	`/api/sessions/:id`	Resolve session identity and metadata.
`PATCH`	`/api/sessions/:id`	Rename, archive, relink, or update session metadata.
`DELETE`	`/api/sessions/:id`	Soft-delete a session. Use `?hard=true` for permanent delete.
`POST`	`/api/sessions/:id/restore`	Restore an archived or recoverable deleted session.
`PATCH`	`/api/sessions/:id/handle`	Set a public handle or display name.
`PATCH`	`/api/sessions/:id/cli-flag`	Set the agent CLI driver used for event detection and stripping.

Create a session

{
"name": "codex",
"type": "terminal",
"root_dir": "/path/to/workspace",
"meta": { "project": "ant" }
}

Creating a terminal session also creates and links a private chat session for coordination.

Messages and routing

Method	Path	Description
`GET`	`/api/sessions/:id/messages`	Read room history. Supports `limit`, `since`, and `before`.
`POST`	`/api/sessions/:id/messages`	Post a room message and trigger ANT routing.
`PATCH`	`/api/sessions/:id/messages?msgId=...`	Merge message metadata such as reactions, bookmarks, or event status.
`DELETE`	`/api/sessions/:id/messages?msgId=...`	Delete a message.
`PATCH`	`/api/sessions/:id/messages/:msgId/pin`	Pin or unpin a message.
`GET`	`/api/sessions/:id/messages/search?q=...`	Search one room's messages.
`GET`	`/api/search?q=...`	Search all indexed messages.

Post a message

{
"role": "user",
"content": "@codex run the tests",
"format": "text",
"sender_id": "@james"
}

The response includes the persisted message and delivery attempts for that route. Historical delivery logs are currently internal.

Participants, presence, and reads

Method	Path	Description
`GET`	`/api/sessions/:id/participants`	List room participants and message-derived posters.
`POST`	`/api/sessions/:id/participants`	Add a session or handle to a chat room.
`DELETE`	`/api/sessions/:id/participants`	Mark a participant as left.
`GET`	`/api/presence/:sessionId`	Read WebSocket presence for handles joined to a room.
`POST`	`/api/sessions/:id/typing`	Broadcast typing state.
`GET`	`/api/sessions/:id/reads`	Read receipts for all messages in a room.
`POST`	`/api/sessions/:id/messages/:msgId/read`	Mark one message read.

Room links

Room links are typed relationships between chat sessions. They power discussions, summaries, spawned rooms, and follow-up rooms without forcing a strict hierarchy.

Method	Path	Description
`GET`	`/api/sessions/:id/links`	List outgoing and incoming room links.
`POST`	`/api/sessions/:id/links`	Create a new linked discussion or link an existing room.
`DELETE`	`/api/sessions/:id/links?linkId=...`	Remove a room relationship.

Supported relationship values are discussion_of, promoted_summary_for, spawned_from, and follows_up.

Prompts, approvals, and status

Method	Path	Description
`GET`	`/api/sessions/:id/status`	Read needs-input state, route metadata, linked chat, and agent status.
`POST`	`/api/sessions/:linkedChatId/messages`	Send `msg_type: "agent_response"` to approve, deny, select, or respond to a prompt card.
`GET`	`/api/sessions/:id/prompt-bridge/pending`	Read generic prompt bridge pending state.
`POST`	`/api/sessions/:id/prompt-bridge/respond`	Inject a raw prompt response into a terminal.
`GET`	`/api/prompt-bridge/config`	Read prompt bridge configuration.
`PUT`	`/api/prompt-bridge/config`	Enable or update prompt bridge routing.

Evidence surfaces

Method	Path	Description
`GET`	`/api/sessions/:id/run-events`	Read interpreted evidence events. Supports `since`, `source`, `kind`, `q`, and `limit`.
`GET`	`/api/sessions/:id/terminal/history`	Read terminal transcript chunks. Supports `since`, `grep`, `raw`, and `limit`.
`GET`	`/api/sessions/:id/terminal/events`	Read tmux control-mode events.
`GET`	`/api/sessions/:id/digest`	Read a lightweight extractive room digest.
`POST`	`/api/sessions/:id/export`	Export a session summary through the configured capture pipeline.

Tasks and file references

Method	Path	Description
`GET`	`/api/sessions/:id/tasks`	List room tasks.
`POST`	`/api/sessions/:id/tasks`	Create a room task.
`PATCH`	`/api/sessions/:id/tasks/:taskId`	Update task status, assignment, description, or file refs.
`DELETE`	`/api/sessions/:id/tasks/:taskId`	Soft-delete a task.
`GET`	`/api/sessions/:id/file-refs`	List flagged files for a room.
`POST`	`/api/sessions/:id/file-refs`	Add a file reference.
`DELETE`	`/api/sessions/:id/file-refs?refId=...`	Remove a file reference.

Health and terminal control

Surface	Description
`GET /api/health`	Read status, version, resource pressure, active session count, cap, and stalled sessions.
`POST /api/sessions/:id/terminal/input`	Write raw bytes to a terminal PTY.
`WebSocket /ws`	Join sessions, stream terminal output, send terminal input, resize terminals, receive chat and status broadcasts.

WebSocket events

Connect to ws://localhost:6458/ws?apiKey=YOUR_KEY or wss:// behind TLS. The browser and CLI use this same live channel for terminal and room updates.

Common server events include terminal_output, message_created, message_updated, message_deleted, message_read, task_created, task_updated, file_ref_created, room_link_created, typing, agent_status_updated, session_needs_input, session_input_resolved, prompt_detected, and sessions_changed.

Consumer caveats

REST and WebSocket are the stable integration surfaces. CLI output is operator UX unless --json is used.
Delivery attempts are returned from message POSTs, but historical delivery logs are not exposed as a public read API yet.
Presence exists for WebSocket clients that joined with handles; typing is broadcast-only and not durable.
ANT exposes lifecycle/resource facts, but it does not currently expose a public recurrence or scheduled-workflow API.