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