Add a message
POST/v1/projects/:project_id/agents/:agent_id/sessions/:session_id/messages
Appends a user message to the session — plain message text or a document_id, exactly one of the two. idempotency_key makes the append safe to retry: a repeat with the same key returns the original message (HTTP 200) and triggers no new work. When the session has auto_generate on, the response is the agent's reply (a Generation shape) instead of the saved message.
Request
Responses
- 200
- 201
- 400
- 401
- 404
- 502
A duplicate append (idempotency key matched); the saved message.
The message was appended. The saved message, or (when auto_generate is on) the agent's generated reply.
The request was malformed or failed validation.
Missing or invalid credentials.
The resource does not exist (existence is not leaked).
The upstream runtime could not complete the operation.