Post to the canonical conversation

POST/v1/channels/{channelId}/messages

Requires an active organization membership and threads:write scope. Persists the authenticated sender, validates mention targets and notifies human mentions through Inbox. Each distinct mentioned agent gets a durable queued thread in the channel's default environment, falling back to the organization default. Missing environments return channel_environment_required (409); unavailable environments or agents return 404. Custom agents require a published version (channel_agent_not_published, 409); its version is pinned at admission. Message, thread associations and jobs commit atomically. Retain idempotencyKey for retries; changed content returns 409 without starting another run. Archived channels reject posting. Execution rechecks membership, resource access, capacity, budget and runtime permissions; final replies are posted back to the channel. Optional threadIds share up to 20 owned, nondeleted threads from this organization. Sending atomically grants current channel members read access to the original threads and includes them in the channel Threads list. It does not grant write or reshare rights, move originals, or enqueue work without agent mentions. Unavailable or unowned threads return channel_thread_unavailable (404). Content may be empty for a thread share. Message metadata.threadAttachments contains server-resolved id and title pairs. Retries reuse the original event.

How to call this endpoint

Every ACP API request uses bearer authentication. The examples here show the actual request path, auth header, and body shape that the platform expects.

Path, query, and header parameters

These parameters control which ACP object the endpoint acts on and how the request is processed.

Path parameters
NameLocationTypeRequiredDescription
channelIdpathstringYes—
Query parameters
None.

Body schema

Content type: application/json · Required

FieldTypeRequiredDescription
contentstringYesMessage text; may be empty only when threadIds is nonempty.
threadIdsstring[]NoOwned threads in this organization to share with channel readers. Duplicates are deduplicated.
mentionsobject[]No—
mentions[].kindhuman | agentYes—
mentions[].idstringYesUnique identifier.
mentions[].labelstringNo—
idempotencyKeystringYes—

What the API returns

Each response code below includes the documented payload shape for the ACP API.

201Channel operation resultapplication/json
FieldTypeRequiredDescription
agentThreadsobject[]Yes—
agentThreads[].idstringYesUnique identifier.
agentThreads[].channelIdstringYes—
agentThreads[].sourceEventIdstringYes—
agentThreads[].titlestringYesDisplay title.
agentThreads[].agentIdstringYesAgent ID.
agentThreads[].agentNamestringYes—
agentThreads[].environmentIdstringYesComputer ID.
agentThreads[].environmentNamestringYes—
agentThreads[].statusstringYesQueue/execution status, including queued, running, completed, failed, cancelled and permission_asked.
agentThreads[].threadStatusstringYesCanonical thread status, independent of the initial mention job.
agentThreads[].batchJobIdstringYes—
agentThreads[].createdAtstringYesISO 8601 timestamp.
agentThreads[].updatedAtstringYesISO 8601 timestamp.
eventobjectYes—
event.idstringYesUnique identifier.
event.threadIdstringYesThread ID.
event.sequenceintegerYes—
event.typestringYes—
event.producerTypestringYes—
event.producerIdstringYes—
event.visibilitystringYes—
event.payloadobjectYes—
event.occurredAtstringYes—
event.createdAtstringYesISO 8601 timestamp.
400Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json
FieldTypeRequiredDescription
errorstringYes—
codestringNo—
messagestringYesMessage text.
401Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json
FieldTypeRequiredDescription
errorstringYes—
codestringNo—
messagestringYesMessage text.
403Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json
FieldTypeRequiredDescription
errorstringYes—
codestringNo—
messagestringYesMessage text.
404Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json
FieldTypeRequiredDescription
errorstringYes—
codestringNo—
messagestringYesMessage text.
409Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json
FieldTypeRequiredDescription
errorstringYes—
codestringNo—
messagestringYesMessage text.
500Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json
FieldTypeRequiredDescription
errorstringYes—
codestringNo—
messagestringYesMessage text.
503Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json
FieldTypeRequiredDescription
errorstringYes—
codestringNo—
messagestringYesMessage text.
Post to the canonical conversation
Loading...
Response 201
Loading...
See the ACP quickstart and SDK flow