API ReferenceCollab Agents

Send Message to Collab Agent

Beta
Submit a message to a collab agent through its Programmatic channel. The agent must have the channel explicitly enabled (programmaticEnabled) and must be shared with the caller. With wait=false (default) the submission is queued and the endpoint returns 202 immediately; the resulting session appears in Athena under the caller's account. With wait=true the request long-polls: the connection stays open while the agent runs and the final agent message is returned verbatim in the reply field — size client timeouts for multi-minute runs. Submissions from the same caller with the same clientThreadKey continue one conversation until 24 hours of inactivity.

Authentication

X-API-KEYstring
API Key authentication via header
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

asset_idstringRequired

Request

This endpoint expects an object.
messagestringRequired1-32000 characters
The message text to submit to the agent. Delivered verbatim as the user turn of the agent session.
clientThreadKeystring or nullOptional<=128 characters

Optional caller-chosen conversation key. Submissions from the same caller with the same key continue one agent session (until 24 hours of inactivity); different keys hold independent conversations. Omitted, all of a caller’s submissions to this agent share one ‘default’ thread.

waitbooleanOptionalDefaults to false

When false (default), the submission is queued and the endpoint returns 202 immediately. When true, the request long-polls: the connection is held open while the agent runs (typically seconds to a few minutes) and the final reply is returned in the response.

Response

Agent run completed inline (wait=true) and the final reply is included

statusstring

‘accepted’ when the submission was queued (wait=false, HTTP 202); ‘completed’ when the agent run finished inline (wait=true, HTTP 200).

threadKeystring

The conversation key this submission was routed under — the clientThreadKey from the request, or ‘default’.

replystring or null

The agent’s final message, verbatim. Null on 202 responses, and null on completed runs where the agent declined to reply (it invoked its dont_respond tool).

sessionIdstring or null

Asset id of the Athena session that handled the submission. Null on 202 responses (the session is resolved asynchronously).

Errors

403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error