List organization channels
GET
/v1/channelsRequires an active organization membership and threads:read scope. Cursor pagination is ordered by channel ID; follow nextCursor until null. unreadOnly applies before pagination and uses the authenticated member’s read position. Defaults to active organization channels and omits project conversations unless projectId is supplied. Project conversations inherit project access, checked before pagination.
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
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
| projectId | query | string | No | Restrict to the accessible conversation for this project. |
| cursor | query | string | No | — |
| limit | query | integer | No | — |
| query | query | string | No | — |
| status | query | active | archived | all | No | — |
| unreadOnly | query | boolean | No | — |
Body schema
This endpoint does not require a request body.
None.
What the API returns
Each response code below includes the documented payload shape for the ACP API.
200Channel operation resultapplication/json
| Field | Type | Required | Description |
|---|---|---|---|
| data | object[] | Yes | — |
| data[].projectId | string | No | Project whose live access policy governs this conversation. Null for organization channels. |
| data[].id | string | Yes | Unique identifier. |
| data[].threadId | string | Yes | Canonical thread ID. Use /threads/{threadId}/timeline and /threads/{threadId}/events for history and realtime. |
| data[].organizationId | string | Yes | — |
| data[].ownerId | string | Yes | — |
| data[].creatorId | string | No | — |
| data[].creator | object | No | — |
| data[].creator.id | string | Yes | Unique identifier. |
| data[].creator.userId | string | Yes | User ID. |
| data[].creator.name | string | Yes | Human-readable name. |
| data[].creator.email | string | Yes | — |
| data[].creator.avatarUrl | string | Yes | — |
| data[].owner | object | No | — |
| data[].owner.id | string | Yes | Unique identifier. |
| data[].owner.userId | string | Yes | User ID. |
| data[].owner.name | string | Yes | Human-readable name. |
| data[].owner.email | string | Yes | — |
| data[].owner.avatarUrl | string | Yes | — |
| data[].canTransferOwnership | boolean | No | — |
| data[].name | string | Yes | Human-readable name. |
| data[].description | string | Yes | Human-readable description. |
| data[].archived | boolean | Yes | — |
| data[].defaultEnvironmentId | string | No | Default environment for new agent mentions. Null uses the organization default; omission on update preserves the selection. |
| data[].metadata | object | Yes | Free-form metadata object. |
| data[].revision | integer | Yes | — |
| data[].createdAt | string | Yes | ISO 8601 timestamp. |
| data[].updatedAt | string | Yes | ISO 8601 timestamp. |
| data[].lastActivityAt | string | Yes | — |
| data[].lastMessage | string | Yes | — |
| data[].lastSequence | integer | Yes | — |
| data[].readSequence | integer | Yes | — |
| data[].unread | boolean | Yes | — |
| data[].canManage | boolean | No | — |
| nextCursor | string | Yes | — |
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. |