Create a shared channel
POST
/v1/channelsRequires an active organization membership and threads:write scope. Additional teams managed by the caller are optional. All active organization members and agents retain participation access. The same creation key and input return the original channel; changed input returns 409. With projectId, returns the existing project conversation or atomically creates it. Project access is required, additional teams are not accepted, and its audience follows project access.
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
None.
Query parameters
None.
Body schema
Content type: application/json · Required
| Field | Type | Required | Description |
|---|---|---|---|
| projectId | string | No | Get or create the single conversation for this accessible project. Omit teamIds or pass an empty array. |
| name | string | Yes | Human-readable name. |
| description | string | No | Human-readable description. |
| teamIds | string[] | No | Optional additional teams. Omit or pass an empty array for the default organization-member and agent audience. |
| idempotencyKey | string | Yes | — |
What the API returns
Each response code below includes the documented payload shape for the ACP API.
201Channel operation resultapplication/json
| Field | Type | Required | Description |
|---|---|---|---|
| channel | object | Yes | — |
| channel.projectId | string | No | Project whose live access policy governs this conversation. Null for organization channels. |
| channel.id | string | Yes | Unique identifier. |
| channel.threadId | string | Yes | Canonical thread ID. Use /threads/{threadId}/timeline and /threads/{threadId}/events for history and realtime. |
| channel.organizationId | string | Yes | — |
| channel.ownerId | string | Yes | — |
| channel.creatorId | string | No | — |
| channel.creator | object | No | — |
| channel.creator.id | string | Yes | Unique identifier. |
| channel.creator.userId | string | Yes | User ID. |
| channel.creator.name | string | Yes | Human-readable name. |
| channel.creator.email | string | Yes | — |
| channel.creator.avatarUrl | string | Yes | — |
| channel.owner | object | No | — |
| channel.owner.id | string | Yes | Unique identifier. |
| channel.owner.userId | string | Yes | User ID. |
| channel.owner.name | string | Yes | Human-readable name. |
| channel.owner.email | string | Yes | — |
| channel.owner.avatarUrl | string | Yes | — |
| channel.canTransferOwnership | boolean | No | — |
| channel.name | string | Yes | Human-readable name. |
| channel.description | string | Yes | Human-readable description. |
| channel.archived | boolean | Yes | — |
| channel.defaultEnvironmentId | string | No | Default environment for new agent mentions. Null uses the organization default; omission on update preserves the selection. |
| channel.metadata | object | Yes | Free-form metadata object. |
| channel.revision | integer | Yes | — |
| channel.createdAt | string | Yes | ISO 8601 timestamp. |
| channel.updatedAt | string | Yes | ISO 8601 timestamp. |
| channel.lastActivityAt | string | Yes | — |
| channel.lastMessage | string | Yes | — |
| channel.lastSequence | integer | Yes | — |
| channel.readSequence | integer | Yes | — |
| channel.unread | boolean | Yes | — |
| channel.canManage | boolean | No | — |
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
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message 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
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message 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
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message 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
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message 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
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message 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
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message 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
| Field | Type | Required | Description |
|---|---|---|---|
| error | string | Yes | — |
| code | string | No | — |
| message | string | Yes | Message text. |