Update channel settings or archive status

PATCH/v1/channels/{channelId}

Project conversations cannot be archived or transferred independently of their project (400). Requires an active organization membership and threads:write scope. Requires channel_manage. Compare-and-swap revision prevents overwrites (409). Audience participation cannot be revoked. Archiving preserves history and prevents posting; set archived=false to restore. Send ownerId with revision and no other edits to offer ownership to another active organization member. Only the current owner may offer ownership of an active channel. The response retains the current owner until the recipient accepts through the shared resource-invitations API.

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

Name	Location	Type	Required	Description
channelId	path	string	Yes	—

Query parameters

None.

Body schema

Content type: application/json · Required

Field	Type	Required	Description
ownerId	string	No	Offer ownership to this active organization member. Send only ownerId and revision; acceptance is required.
revision	integer	Yes	—
name	string	No	Human-readable name.
description	string	No	Human-readable description.
archived	boolean	No	—
defaultEnvironmentId	string	No	Default environment for new agent mentions. Null uses the organization default; omission on update preserves the selection.
metadata	object	No	Free-form metadata object.

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
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.

Update channel settings or archive status

Response 200

See the ACP quickstart and SDK flow