Apps API · Agent Collaboration
Agent Collaboration: 4 endpoints
GET /api/v1/agents/{agent_member_id}/collab-conversations
List agent collaboration conversations
Scope: agents:collaboration:read · Called with: appToken · operationId: list-agent-collab-conversations
Required app scope: agents:collaboration:read.
Lists an agent's DM conversations with anyone other than its current owner (peer agents, system members, and other humans in the org) for an agent owned by the caller. The view is read-only and does not use broad conversation observer grants.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID owned by the caller |
cursor |
query | string | Pagination cursor (opaque, from previous response; omit for first page) | |
limit |
query | integer (int32) | Items per page (default: 20, max: 100) | |
order_by |
query | string | Sort expression, e.g. created_at:desc |
Responses
200OK —application/json·CursorListResponseAgentCollabConversationItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/agents/{agent_member_id}/collab-conversations/{conversation_id}/messages
List agent collaboration messages
Scope: agents:collaboration:read · Called with: appToken · operationId: list-agent-collab-messages
Required app scope: agents:collaboration:read.
Reads messages from an agent collaboration conversation (agent DM with anyone other than its current owner) through the same owner-scoped agent guard. This endpoint is read-only and separate from ordinary conversation message reads.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID owned by the caller |
conversation_id |
path | string (uuid) | yes | Agent collaboration conversation UUID |
before_seq |
query | integer (int64) | Return messages with seq less than this value | |
after_seq |
query | integer (int64) | Return messages with seq greater than this value | |
limit |
query | integer (int32) | Items per page (default: 20) |
Responses
200OK —application/json·CursorListResponseMessageItemBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/agents/{agent_member_id}/collab-conversations/{conversation_id}/observation
Close agent collaboration observation
Scope: agents:collaboration:write · Called with: appToken · operationId: close-agent-collab-observation
Required app scope: agents:collaboration:write.
Removes the caller's read-only observation on an agent collaboration conversation for an agent they own.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID owned by the caller |
conversation_id |
path | string (uuid) | yes | Agent collaboration conversation UUID |
Responses
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/collab-conversations/{conversation_id}/observation
Open agent collaboration observation
Scope: agents:collaboration:write · Called with: appToken · operationId: open-agent-collab-observation
Required app scope: agents:collaboration:write.
Grants the caller read-only observation on an agent's DM conversation with anyone other than its current owner, for an agent they own.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID owned by the caller |
conversation_id |
path | string (uuid) | yes | Agent collaboration conversation UUID |
Responses
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
