The native HTTP endpoints for creating, finding, reading, and deleting messages.
Messages are persisted separately from run state, so a client can read conversation history outside of an active run and add messages to a session directly.
Find messages for a session with optional filtering and pagination.
/v1/sessions/{session_id}/messagesFind messages for a session with optional filtering and pagination.
The session ID.
Maximum page size.
Opaque cursor for the next page.
Message IDs to filter on.
Run IDs to filter on.
Checkpoint IDs to filter on.
Message roles to filter on.
Filter by creation time.
Filter by creation time.
Create a new message in a session outside of a run.
/v1/sessions/{session_id}/messagesCreate a new message in a session outside of a run.
The session ID.
The message role.
systemusertoolOptional message ID. If omitted, one is generated automatically.
The system message text.
Optional message ID. If omitted, one is generated automatically.
Ordered content blocks. A user message may include text and media.
Optional message ID. If omitted, one is generated automatically.
The tool call this message completes.
The assistant message that started the tool call.
Tool output text.
Error text if the tool failed.
Get a message by its ID.
/v1/messages/{message_id}Get a message by its ID.
The message ID.
Delete a message by its ID.
/v1/messages/{message_id}Delete a message by its ID.
The message ID.
A single content block in a user message. A user message carries an ordered array of these blocks, so
one message may mix text and media. The block is discriminated by type.
Identifies plain text content.
textThe text content.
Identifies image content.
imageThe image source.
The MIME type.
Identifies audio content.
audioThe audio source.
The MIME type.
Identifies video content.
videoThe video source.
The MIME type.
Identifies document content.
documentThe document source.
The MIME type.
The source of an image, audio, video, or document content block. It is either a URL to fetch or an
inline base64 payload, discriminated by type.
Identifies a URL source.
urlThe URL to fetch.
Identifies inline base64 data.
base64The base64-encoded payload.
A tool invocation emitted by the assistant.
The tool call ID.
The name of the tool to invoke.
The tool arguments, as a JSON object matching the tool's parameter schema.
© 2026 pogue.dev. All rights reserved.
CC BY 4.0Search the agentc documentation