Skip to main content
POST
cURL
With the default delivery: immediate, resume the agent when the session is idle, completed, failed, or approval_required; sending to a session that is processing or queued returns 409 interaction_not_in_terminal_state.With delivery: queued, store a text message even while the agent is busy and return a 202 receipt containing message_id and status: accepted. Existing queue order, stops, approvals, and concurrency limits still apply. Queued delivery does not support streaming, attachments, approval responses, incognito sessions, or channel sessions. The message queue endpoint uses the same automatic delivery behavior.The receipt confirms storage, not processing. Capacity refusal can leave the message queued; a failed dispatch can leave it in the transcript unprocessed. Use the receipt ID with the existing queue endpoints while the message remains queued.An optional Idempotency-Key header protects retries of a queued send. Reuse the same key and content to receive the original receipt; different content under that key returns 409 session_message_idempotency_conflict. Keys are scoped to the session and sender and last while the message remains in the queue or transcript. Deleting a queued message forgets its key; stop retries when canceling it. Without a key, each request creates a new message.Files uploaded via Upload session file can be attached to the message with attachments.
A session that stopped to ask you something is approval_required, and you have two ways to move it forward:
  • Answer the ask. Send the pending asks’ responses to Resolve approvals. Use this to approve or reject a tool call, or to answer an Ask Question the agent raised. This endpoint rejects approval_responses with a 400.
  • Send a follow-up instead. Post a normal message here. It is appended to the session transcript and starts a new turn, leaving the pending ask unanswered. Use this when the answer no longer matters — for example to redirect the agent or drop the request it was asking about.
See Human in the Loop for how agents pause for approvals and questions.
api.gumloop.com only serves the non-streaming response above. To stream agent output as it’s produced, send the same request body (with stream: true) to the streaming host instead:POST https://ws.gumloop.com/api/v1/sessions/{session_id}/messagesThe response is text/event-stream (Server-Sent Events). With the Python SDK, client.sessions.stream_message(session_id, input="...") routes to ws.gumloop.com automatically and yields parsed StreamEvent objects.If you send stream: true to api.gumloop.com by mistake, the response is a 400 whose body contains the correct streaming host so you can retry against it.

Authorizations

Authorization
string
header
required

A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.

Headers

Idempotency-Key
string

Retry key for queued delivery; reuse it for the same report.

Required string length: 1 - 256
Pattern: ^[!-~]+(?![\s\S])

Path Parameters

session_id
string
required

ID of the session to continue.

Body

application/json
input
string
required

The next user message. Required. Also accepted as message for backwards compatibility.

Example:

"Now write a follow-up email."

delivery
enum<string>
default:immediate

Queued delivery stores the text message and returns an acceptance receipt.

Available options:
immediate,
queued
stream
boolean
default:false

Must be false (or omitted) when calling api.gumloop.com. Set to true only when calling ws.gumloop.com (see the streaming section above).

attachments
object[]

Files to attach to the message. Each file_name must be a stored path returned by Upload session file for this session.

Maximum array length: 10

Response

Immediate delivery returns the session response; queued delivery returns a storage receipt. queue_position applies only to immediate delivery.

session
object
required
queue_position
integer | null

Position in the per-agent queue. Populated only when the session was queued; otherwise null.

Example:

null