Documentation Index
Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
This page groups the concrete interfaces behind conversation and agent-run flows. The REST routes use OpenAPI-backed schemas for request and response validation.
REST conversation operations
| Method | Path | Purpose |
|---|
GET | /conversations | List conversations |
POST | /conversations | Create a conversation |
GET | /conversations/{id} | Read one conversation |
PATCH | /conversations/{id} | Update title, status, summary, or project scope |
DELETE | /conversations/{id} | Soft-delete a conversation |
GET | /conversations/{id}/messages | List messages |
POST | /conversations/{id}/messages | Send a message |
GET | /conversations/{conversation_id}/messages/{message_id} | Read one message |
PATCH | /conversations/{conversation_id}/messages/{message_id} | Edit a message |
DELETE | /conversations/{conversation_id}/messages/{message_id} | Delete a message |
GET | /conversations/{conversation_id}/participants | List participants |
POST | /conversations/{conversation_id}/participants | Add a participant |
DELETE | /conversations/{conversation_id}/participants/{user_id} | Remove a participant |
GET | /conversations/{conversation_id}/read-state | Read the user’s read cursor and unread count |
PUT | /conversations/{conversation_id}/read-state | Update the user’s read cursor |
GET | /conversations/{id}/tree | Read the message tree |
GET | /conversations/{conversation_id}/branch-selection | Read active branch selection |
PUT | /conversations/{conversation_id}/branch-selection | Update active branch selection |
GET | /conversations/{conversation_id}/branches/{message_id} | List message branches |
POST | /conversations/{conversation_id}/branches | Fork at a message |
| Method | Path | Purpose |
|---|
GET | /conversations/{conversation_id}/input-requests | List input requests |
POST | /conversations/{conversation_id}/input-requests | Create an input request |
GET | /conversations/{conversation_id}/input-requests/{input_request_id} | Read one input request |
POST | /conversations/{conversation_id}/input-requests/{input_request_id}/responses | Submit an input response |
POST | /conversations/{conversation_id}/input-requests/{input_request_id}/cancel | Cancel an input request |
REST conversation run operations
| Method | Path | Purpose |
|---|
GET | /conversations/{conversation_id}/runs | List runs for a conversation |
GET | /conversations/{conversation_id}/runs/{run_id} | Read one run projection |
GET | /conversations/{conversation_id}/runs/{run_id}/events | Read persisted run events |
POST | /conversations/{conversation_id}/runs/{run_id}/events | Append durable run events |
GET | /conversations/{conversation_id}/runs/{run_id}/stream | Attach to the persisted run event log as SSE |
GET | /conversations/{conversation_id}/runs/{run_id}/snapshot | Read a replay snapshot |
GET | /conversations/{conversation_id}/runs/{run_id}/children | List child runs for a parent run |
GET | /conversations/{conversation_id}/runs/children-by-parent-conversation | List child runs by parent conversation |
SSE run streams
| Method | Path | Purpose | Auth boundary |
|---|
GET | /conversations/{conversation_id}/runs/{run_id}/stream | Replay and follow durable run events as text/event-stream | Conversation access check |
POST | /api/ag-ui | Execute a default agent request as text/event-stream | Bearer token |
POST | /api/ag-ui/messages/stream | Compatibility stream route as text/event-stream | Bearer token |
POST | /api/control-plane/agents/stream | Stream a project-agent run as text/event-stream | Control-plane JWS |
WebSocket notification routes
| Method | Path | Purpose | Auth boundary |
|---|
UPGRADE | /ws/{project_id}/events | Subscribe to project event notifications, including conversation and agent-run lifecycle events | Project access check |
UPGRADE | /ws/conversations/{conversation_id}/events | Subscribe directly to one conversation event channel | Conversation access check |
REST durable run API
/runs is the canonical durable execution API. It accepts kind: "agent", kind: "workflow", or kind: "job" and returns a shared run summary.
| Method | Path | Purpose | Side effect |
|---|
POST | /runs | Create an agent, workflow, or job run | Inserts canonical run state and run-kind detail |
GET | /runs/{run_id} | Read a canonical run | No write |
GET | /runs/{run_id}/children | List child runs | No write |
POST | /runs/{run_id}/resume | Resume a waiting run | Submits resume signal |
POST | /runs/{run_id}/cancel | Cancel a run | Writes terminal cancellation state |
POST | /runs/{run_id}/complete | Finalize a run | Writes terminal status and metadata |
Run detail endpoints
| Method | Path | Purpose | Run kind |
|---|
GET | /workflow-runs/{run_id} | Read workflow-specific run detail | workflow |
GET | /job-runs/{run_id} | Read job-specific run detail | job |
veryfront-agent routes
| Method | Path | Purpose | Stream |
|---|
POST | /api/ag-ui | Execute an AG-UI request | SSE |
POST | /api/ag-ui/messages/stream | Compatibility stream route | SSE |
POST | /api/ag-ui/runs | Start a detached durable run | Setup response plus background execution |
DELETE | /api/ag-ui/runs/:runId | Cancel an active durable run | No |
Project-agent control-plane routes
| Method | Path | Purpose | Auth boundary |
|---|
POST | /api/control-plane/agents/list | Discover runtime agents | Control-plane JWS |
POST | /api/control-plane/agents/stream | Stream a project-agent run as SSE | Control-plane JWS |
POST | /api/control-plane/agents/runs/:runId/resume | Resume a waiting project-agent run | Control-plane JWS |
DELETE | /api/control-plane/agents/runs/:runId | Cancel a project-agent run | Control-plane JWS |
/internal/agents/* paths exist as compatibility surfaces in the runtime code.
Validation contracts
| Contract | Validates | Boundary |
|---|
CreateConversationInputSchema | Project ID, type, title, metadata size | API REST body |
SendMessageInputSchema | Conversation ID, parent ID, role, message parts, idempotency key | API REST body |
MessagePartSchema | Text, image, file, tool call, tool result, reasoning, citation, source, error, data parts | API message model |
CreateAgentRunInputSchema | Run identity, lineage, user, project, source target, runtime target | API durable run body |
CreateAgentRunEventInputSchema | Run event type, payload, sequence, payload size | API event append body |
CreateRunInputSchema | Canonical run kind, owner, parent run, trigger, and run-specific request payload | API canonical run body |
AgentStreamRequestSchema | Runtime agent ID, run ID, tools, context, forwarded props, target selection | API-to-runtime stream body |
ToolResultRequestSchema | Tool call result payload and error flag | Resume body |
chatRequestSchema | Agent chat messages, context, model, runtime overrides, durable root run | veryfront-agent request body |
| Control-plane schemas | Agent discovery, stream request signing claims, runtime agent list response | Project-runtime control plane |
