Network

Get the network runtime status snapshot

GET/api/network/status

`application/json`

curl -X GET "https://example.com/api/network/status"

{  "network": {    "channels": 0,    "conversation_messages": 0,    "declared_channels": [      {        "activation_id": "string",        "bundle_name": "string",        "description": "string",        "extension_name": "string",        "name": "string",        "primary": true,        "profile_name": "string",        "workspace_id": "string"      }    ],    "direct_resolves": 0,    "enabled": true,    "handoff_tagged_events": 0,    "kind_metrics": [      {        "delivered": 0,        "kind": "string",        "received": 0,        "rejected": 0,        "sent": 0      }    ],    "local_peers": 0,    "messages_delivered": 0,    "messages_received": 0,    "messages_rejected": 0,    "messages_sent": 0,    "open_direct_rooms": 0,    "open_threads": 0,    "open_work_items": 0,    "status": "string",    "work_transitions": 0,    "workflow_tagged_events": 0  }}

Stream one task run coordination conversation

GET/api/task-runs/{id}/conversation/stream

Query Parameters

after?string

Replay messages after this message id

`text/event-stream`

`application/json`

curl -X GET "https://example.com/api/task-runs/string/conversation/stream"

{  "message": {    "body": null,    "causation_id": "string",    "channel": "string",    "direct_id": "string",    "direction": "string",    "display_name": "string",    "intent": "string",    "kind": "string",    "local": true,    "mentions": [      "string"    ],    "message_id": "string",    "peer_from": "string",    "peer_to": "string",    "preview_text": "string",    "reply_to": "string",    "session_id": "string",    "size_bytes": 0,    "surface": "string",    "text": "string",    "thread_id": "string",    "timestamp": "2019-08-24T14:15:22Z",    "trace_id": "string",    "work_id": "string",    "workspace_id": "string"  },  "usage": {    "budget": {      "exhausted_reason": "string",      "input_tokens_used": 0,      "output_tokens_used": 0,      "participation_status": {        "available": true,        "owner": {          "id": "string",          "kind": "session",          "workspace_id": "string"        },        "participating": true,        "reason": "string"      },      "updated_at": "2019-08-24T14:15:22Z",      "wakes_used": 0,      "wall_time_used": "string"    },    "details": [      {        "channel": "string",        "charged_wall_time": "string",        "depth": 0,        "input_tokens": 0,        "output_tokens": 0,        "participation_status": {          "available": true,          "owner": {            "id": "string",            "kind": "session",            "workspace_id": "string"          },          "participating": true,          "reason": "string"        },        "reason": "string",        "reserved_at": "2019-08-24T14:15:22Z",        "root_id": "string",        "settled_at": "2019-08-24T14:15:22Z",        "state": "string",        "task_run_id": "string",        "usage_state": "string",        "wake_id": "string",        "workspace_id": "string"      }    ],    "next_cursor": "string",    "total": {      "actual_wake_count": 0,      "charged_wall_time": "string",      "input_tokens": 0,      "output_tokens": 0,      "reserved_wake_count": 0,      "unavailable_wake_count": 0,      "wake_count": 0    },    "workspace_id": "string"  }}

Enqueue designated sibling runs for one task

POST/api/tasks/{id}/runs/fan-out

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

designations*array<>

idempotency_key?string

network_participation?|||

`application/json`

curl -X POST "https://example.com/api/tasks/string/runs/fan-out" \  -H "Content-Type: application/json" \  -d '{    "designations": [      {        "brief": "string"      }    ]  }'

{  "designation_group_id": "string",  "runs": [    {      "attempt": 0,      "claim_token_hash": "string",      "claimed_at": "2019-08-24T14:15:22Z",      "claimed_by": {        "kind": "human",        "ref": "string"      },      "coordination_channel": {        "allowed_message_kinds": [          "status"        ],        "display_name": "string",        "id": "string",        "last_activity_at": "2019-08-24T14:15:22Z",        "purpose": "string",        "run_id": "string",        "task_id": "string",        "workflow_id": "string",        "workspace_id": "string"      },      "designation": {        "brief": "string",        "index": 0      },      "designation_group_id": "string",      "ended_at": "2019-08-24T14:15:22Z",      "error": "string",      "failure_kind": "string",      "heartbeat_at": "2019-08-24T14:15:22Z",      "id": "string",      "idempotency_key": "string",      "lease_until": "2019-08-24T14:15:22Z",      "metadata": null,      "origin": {        "kind": "cli",        "ref": "string"      },      "previous_run_id": "string",      "queued_at": "2019-08-24T14:15:22Z",      "recovery_count": 0,      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "result": null,      "session_id": "string",      "started_at": "2019-08-24T14:15:22Z",      "status": "queued",      "task_id": "string"    }  ]}

Get scoped network coordination settings, invitation state, and eligibility

GET/api/workspaces/{workspace_id}/network-coordination

Query Parameters

scope*string

Coordination scope

Value in

"workspace"
"task"

task_id?string

Task id required for task scope

run_id?string

Run id used for daemon-owned invitation eligibility

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network-coordination?scope=workspace"

{  "coordination": {    "eligibility": {      "coordinator": true,      "eligible": true,      "reason": "string",      "run_id": "string",      "worker_count": 0    },    "enabled": true,    "invitation": {      "dismissed": true,      "dismissed_at": "2019-08-24T14:15:22Z",      "dismissed_by": "string",      "scope": "string",      "task_id": "string"    },    "revision": 0,    "scope": "string",    "task_id": "string",    "updated_at": "2019-08-24T14:15:22Z",    "updated_by": "string",    "workspace_id": "string"  }}

Compare-and-set future-run network coordination for one scope

PUT/api/workspaces/{workspace_id}/network-coordination

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

enabled*boolean

expected_revision*integer

Formatint64

Range0 <= value

run_id?string

Length1 <= length

scope*"workspace"

Value in

"workspace"

`application/json`

curl -X PUT "https://example.com/api/workspaces/string/network-coordination" \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "expected_revision": 0,    "scope": "workspace"  }'

{  "coordination": {    "eligibility": {      "coordinator": true,      "eligible": true,      "reason": "string",      "run_id": "string",      "worker_count": 0    },    "enabled": true,    "invitation": {      "dismissed": true,      "dismissed_at": "2019-08-24T14:15:22Z",      "dismissed_by": "string",      "scope": "string",      "task_id": "string"    },    "revision": 0,    "scope": "string",    "task_id": "string",    "updated_at": "2019-08-24T14:15:22Z",    "updated_by": "string",    "workspace_id": "string"  }}

Dismiss or reset the coordination invitation for a scope

PUT/api/workspaces/{workspace_id}/network-coordination/invitation

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

dismissed*boolean

expected_revision*integer

Formatint64

Range0 <= value

run_id?string

Length1 <= length

scope*"workspace"

Value in

"workspace"

`application/json`

curl -X PUT "https://example.com/api/workspaces/string/network-coordination/invitation" \  -H "Content-Type: application/json" \  -d '{    "dismissed": true,    "expected_revision": 0,    "scope": "workspace"  }'

{  "coordination": {    "eligibility": {      "coordinator": true,      "eligible": true,      "reason": "string",      "run_id": "string",      "worker_count": 0    },    "enabled": true,    "invitation": {      "dismissed": true,      "dismissed_at": "2019-08-24T14:15:22Z",      "dismissed_by": "string",      "scope": "string",      "task_id": "string"    },    "revision": 0,    "scope": "string",    "task_id": "string",    "updated_at": "2019-08-24T14:15:22Z",    "updated_by": "string",    "workspace_id": "string"  }}

List materialized network channels

GET/api/workspaces/{workspace_id}/network/channels

Query Parameters

recent_limit?integer

Maximum cross-channel recent conversations to include

Formatint32

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels"

{  "channels": [    {      "channel": "string",      "coordinator_peer_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "fanout_policy": "string",      "historical_participant_count": 0,      "last_activity_at": "2019-08-24T14:15:22Z",      "last_message_preview": "string",      "last_presence_at": "2019-08-24T14:15:22Z",      "local_peer_count": 0,      "message_count": 0,      "peer_count": 0,      "presence_count": 0,      "purpose": "string",      "session_count": 0,      "workspace_id": "string"    }  ],  "recents": [    {      "channel": "string",      "container_id": "string",      "last_activity_at": "2019-08-24T14:15:22Z",      "last_message_preview": "string",      "participant_count": 0,      "session_a": "string",      "session_b": "string",      "surface": "string",      "title": "string"    }  ]}

Create a network channel by spawning agent sessions

POST/api/workspaces/{workspace_id}/network/channels

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

agent_names*array<string>

channel*string

coordinator_peer_id?string

fanout_policy?string

purpose*string

workspace_id*string

`application/json`

curl -X POST "https://example.com/api/workspaces/string/network/channels" \  -H "Content-Type: application/json" \  -d '{    "agent_names": [      "string"    ],    "channel": "string",    "purpose": "string",    "workspace_id": "string"  }'

{  "channel": {    "channel": "string",    "coordinator_peer_id": "string",    "created_at": "2019-08-24T14:15:22Z",    "created_by": "string",    "fanout_policy": "string",    "historical_participant_count": 0,    "kind_counts": [      {        "count": 0,        "kind": "string"      }    ],    "last_activity_at": "2019-08-24T14:15:22Z",    "last_message_preview": "string",    "last_presence_at": "2019-08-24T14:15:22Z",    "local_peer_count": 0,    "message_count": 0,    "peer_count": 0,    "peers": [      {        "channel": "string",        "display_name": "string",        "joined_at": "2019-08-24T14:15:22Z",        "local": true,        "peer_card": {          "artifacts_supported": [            "string"          ],          "capabilities": [            {              "id": "string",              "summary": "string"            }          ],          "display_name": "string",          "ext": {            "property1": null,            "property2": null          },          "peer_id": "string",          "profiles_supported": [            "string"          ],          "trust_modes_supported": [            "string"          ]        },        "peer_id": "string",        "presence_state": "string",        "session_id": "string",        "workspace_id": "string"      }    ],    "presence_count": 0,    "purpose": "string",    "session_count": 0,    "sessions": [      {        "acp_caps": {          "config_options": [            {              "current": "string",              "description": "string",              "id": "string",              "kind": "string",              "label": "string",              "values": [                {                  "description": "string",                  "label": "string",                  "value": "string"                }              ]            }          ],          "supported_modes": [            "string"          ],          "supports_load_session": true        },        "acp_session_id": "string",        "activity": {          "current_tool": "string",          "deadline_at": "2019-08-24T14:15:22Z",          "elapsed_ms": 0,          "elapsed_seconds": 0,          "idle_seconds": 0,          "iteration_current": 0,          "iteration_max": 0,          "last_activity_at": "2019-08-24T14:15:22Z",          "last_activity_detail": "string",          "last_activity_kind": "string",          "last_progress_at": "2019-08-24T14:15:22Z",          "tool_call_id": "string",          "turn_id": "string",          "turn_source": "string",          "turn_started_at": "2019-08-24T14:15:22Z"        },        "agent_name": "string",        "attach_expires_at": "2019-08-24T14:15:22Z",        "attachable": true,        "attached_to": "string",        "available_commands": [          {            "description": "string",            "input": {              "hint": "string"            },            "name": "string"          }        ],        "badge": "string",        "created_at": "2019-08-24T14:15:22Z",        "failure": {          "crash_bundle_path": "string",          "kind": "string",          "summary": "string"        },        "health": {          "active_prompt": true,          "agent_name": "string",          "attachable": true,          "eligible_for_wake": true,          "health": "healthy",          "ineligibility_reason": "session_prompt_active",          "last_activity_at": "2019-08-24T14:15:22Z",          "last_error": "string",          "last_presence_at": "2019-08-24T14:15:22Z",          "session_id": "string",          "state": "idle",          "updated_at": "2019-08-24T14:15:22Z",          "workspace_id": "string"        },        "id": "string",        "lineage": {          "auto_stop_on_parent": true,          "parent_session_id": "string",          "permission_policy": {            "mcp_servers": [              "string"            ],            "network_channels": [              "string"            ],            "sandbox_profiles": [              "string"            ],            "skills": [              "string"            ],            "tools": [              "string"            ],            "workspace_paths": [              "string"            ]          },          "root_session_id": "string",          "spawn_budget": {            "max_active_per_workspace": 0,            "max_children": 0,            "max_depth": 0,            "ttl_seconds": 0          },          "spawn_depth": 0,          "spawn_role": "string",          "ttl_expires_at": "2019-08-24T14:15:22Z"        },        "model": "string",        "name": "string",        "provider": "string",        "reasoning_effort": "none",        "resolved_network_participation": {          "mode": "local",          "source": "explicit_request",          "version": "network-participation/v1"        },        "sandbox": {          "backend": "string",          "instance_id": "string",          "last_sync_error": "string",          "profile": "string",          "provider_state_json": null,          "sandbox_id": "string",          "state": "string"        },        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        },        "state": "starting",        "stop_detail": "string",        "stop_reason": "completed",        "transcript_epoch": 0,        "type": "user",        "updated_at": "2019-08-24T14:15:22Z",        "workspace_id": "string",        "workspace_path": "string"      }    ],    "workspace_id": "string"  }}

Get one network channel detail

GET/api/workspaces/{workspace_id}/network/channels/{channel}

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string"

{  "channel": {    "channel": "string",    "coordinator_peer_id": "string",    "created_at": "2019-08-24T14:15:22Z",    "created_by": "string",    "fanout_policy": "string",    "historical_participant_count": 0,    "kind_counts": [      {        "count": 0,        "kind": "string"      }    ],    "last_activity_at": "2019-08-24T14:15:22Z",    "last_message_preview": "string",    "last_presence_at": "2019-08-24T14:15:22Z",    "local_peer_count": 0,    "message_count": 0,    "peer_count": 0,    "peers": [      {        "channel": "string",        "display_name": "string",        "joined_at": "2019-08-24T14:15:22Z",        "local": true,        "peer_card": {          "artifacts_supported": [            "string"          ],          "capabilities": [            {              "id": "string",              "summary": "string"            }          ],          "display_name": "string",          "ext": {            "property1": null,            "property2": null          },          "peer_id": "string",          "profiles_supported": [            "string"          ],          "trust_modes_supported": [            "string"          ]        },        "peer_id": "string",        "presence_state": "string",        "session_id": "string",        "workspace_id": "string"      }    ],    "presence_count": 0,    "purpose": "string",    "session_count": 0,    "sessions": [      {        "acp_caps": {          "config_options": [            {              "current": "string",              "description": "string",              "id": "string",              "kind": "string",              "label": "string",              "values": [                {                  "description": "string",                  "label": "string",                  "value": "string"                }              ]            }          ],          "supported_modes": [            "string"          ],          "supports_load_session": true        },        "acp_session_id": "string",        "activity": {          "current_tool": "string",          "deadline_at": "2019-08-24T14:15:22Z",          "elapsed_ms": 0,          "elapsed_seconds": 0,          "idle_seconds": 0,          "iteration_current": 0,          "iteration_max": 0,          "last_activity_at": "2019-08-24T14:15:22Z",          "last_activity_detail": "string",          "last_activity_kind": "string",          "last_progress_at": "2019-08-24T14:15:22Z",          "tool_call_id": "string",          "turn_id": "string",          "turn_source": "string",          "turn_started_at": "2019-08-24T14:15:22Z"        },        "agent_name": "string",        "attach_expires_at": "2019-08-24T14:15:22Z",        "attachable": true,        "attached_to": "string",        "available_commands": [          {            "description": "string",            "input": {              "hint": "string"            },            "name": "string"          }        ],        "badge": "string",        "created_at": "2019-08-24T14:15:22Z",        "failure": {          "crash_bundle_path": "string",          "kind": "string",          "summary": "string"        },        "health": {          "active_prompt": true,          "agent_name": "string",          "attachable": true,          "eligible_for_wake": true,          "health": "healthy",          "ineligibility_reason": "session_prompt_active",          "last_activity_at": "2019-08-24T14:15:22Z",          "last_error": "string",          "last_presence_at": "2019-08-24T14:15:22Z",          "session_id": "string",          "state": "idle",          "updated_at": "2019-08-24T14:15:22Z",          "workspace_id": "string"        },        "id": "string",        "lineage": {          "auto_stop_on_parent": true,          "parent_session_id": "string",          "permission_policy": {            "mcp_servers": [              "string"            ],            "network_channels": [              "string"            ],            "sandbox_profiles": [              "string"            ],            "skills": [              "string"            ],            "tools": [              "string"            ],            "workspace_paths": [              "string"            ]          },          "root_session_id": "string",          "spawn_budget": {            "max_active_per_workspace": 0,            "max_children": 0,            "max_depth": 0,            "ttl_seconds": 0          },          "spawn_depth": 0,          "spawn_role": "string",          "ttl_expires_at": "2019-08-24T14:15:22Z"        },        "model": "string",        "name": "string",        "provider": "string",        "reasoning_effort": "none",        "resolved_network_participation": {          "mode": "local",          "source": "explicit_request",          "version": "network-participation/v1"        },        "sandbox": {          "backend": "string",          "instance_id": "string",          "last_sync_error": "string",          "profile": "string",          "provider_state_json": null,          "sandbox_id": "string",          "state": "string"        },        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        },        "state": "starting",        "stop_detail": "string",        "stop_reason": "completed",        "transcript_epoch": 0,        "type": "user",        "updated_at": "2019-08-24T14:15:22Z",        "workspace_id": "string",        "workspace_path": "string"      }    ],    "workspace_id": "string"  }}

Update mutable delivery policy for one network channel

PATCH/api/workspaces/{workspace_id}/network/channels/{channel}

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

coordinator_peer_id?string|null

fanout_policy?string|null

purpose?string|null

`application/json`

curl -X PATCH "https://example.com/api/workspaces/string/network/channels/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "channel": {    "channel": "string",    "coordinator_peer_id": "string",    "created_at": "2019-08-24T14:15:22Z",    "created_by": "string",    "fanout_policy": "string",    "historical_participant_count": 0,    "kind_counts": [      {        "count": 0,        "kind": "string"      }    ],    "last_activity_at": "2019-08-24T14:15:22Z",    "last_message_preview": "string",    "last_presence_at": "2019-08-24T14:15:22Z",    "local_peer_count": 0,    "message_count": 0,    "peer_count": 0,    "peers": [      {        "channel": "string",        "display_name": "string",        "joined_at": "2019-08-24T14:15:22Z",        "local": true,        "peer_card": {          "artifacts_supported": [            "string"          ],          "capabilities": [            {              "id": "string",              "summary": "string"            }          ],          "display_name": "string",          "ext": {            "property1": null,            "property2": null          },          "peer_id": "string",          "profiles_supported": [            "string"          ],          "trust_modes_supported": [            "string"          ]        },        "peer_id": "string",        "presence_state": "string",        "session_id": "string",        "workspace_id": "string"      }    ],    "presence_count": 0,    "purpose": "string",    "session_count": 0,    "sessions": [      {        "acp_caps": {          "config_options": [            {              "current": "string",              "description": "string",              "id": "string",              "kind": "string",              "label": "string",              "values": [                {                  "description": "string",                  "label": "string",                  "value": "string"                }              ]            }          ],          "supported_modes": [            "string"          ],          "supports_load_session": true        },        "acp_session_id": "string",        "activity": {          "current_tool": "string",          "deadline_at": "2019-08-24T14:15:22Z",          "elapsed_ms": 0,          "elapsed_seconds": 0,          "idle_seconds": 0,          "iteration_current": 0,          "iteration_max": 0,          "last_activity_at": "2019-08-24T14:15:22Z",          "last_activity_detail": "string",          "last_activity_kind": "string",          "last_progress_at": "2019-08-24T14:15:22Z",          "tool_call_id": "string",          "turn_id": "string",          "turn_source": "string",          "turn_started_at": "2019-08-24T14:15:22Z"        },        "agent_name": "string",        "attach_expires_at": "2019-08-24T14:15:22Z",        "attachable": true,        "attached_to": "string",        "available_commands": [          {            "description": "string",            "input": {              "hint": "string"            },            "name": "string"          }        ],        "badge": "string",        "created_at": "2019-08-24T14:15:22Z",        "failure": {          "crash_bundle_path": "string",          "kind": "string",          "summary": "string"        },        "health": {          "active_prompt": true,          "agent_name": "string",          "attachable": true,          "eligible_for_wake": true,          "health": "healthy",          "ineligibility_reason": "session_prompt_active",          "last_activity_at": "2019-08-24T14:15:22Z",          "last_error": "string",          "last_presence_at": "2019-08-24T14:15:22Z",          "session_id": "string",          "state": "idle",          "updated_at": "2019-08-24T14:15:22Z",          "workspace_id": "string"        },        "id": "string",        "lineage": {          "auto_stop_on_parent": true,          "parent_session_id": "string",          "permission_policy": {            "mcp_servers": [              "string"            ],            "network_channels": [              "string"            ],            "sandbox_profiles": [              "string"            ],            "skills": [              "string"            ],            "tools": [              "string"            ],            "workspace_paths": [              "string"            ]          },          "root_session_id": "string",          "spawn_budget": {            "max_active_per_workspace": 0,            "max_children": 0,            "max_depth": 0,            "ttl_seconds": 0          },          "spawn_depth": 0,          "spawn_role": "string",          "ttl_expires_at": "2019-08-24T14:15:22Z"        },        "model": "string",        "name": "string",        "provider": "string",        "reasoning_effort": "none",        "resolved_network_participation": {          "mode": "local",          "source": "explicit_request",          "version": "network-participation/v1"        },        "sandbox": {          "backend": "string",          "instance_id": "string",          "last_sync_error": "string",          "profile": "string",          "provider_state_json": null,          "sandbox_id": "string",          "state": "string"        },        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        },        "state": "starting",        "stop_detail": "string",        "stop_reason": "completed",        "transcript_epoch": 0,        "type": "user",        "updated_at": "2019-08-24T14:15:22Z",        "workspace_id": "string",        "workspace_path": "string"      }    ],    "workspace_id": "string"  }}

List direct rooms in one network channel

GET/api/workspaces/{workspace_id}/network/channels/{channel}/directs

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

Query Parameters

session_id?string

Filter by participant session id

query?string

Filter direct rooms by title, peer, or preview text

has_work?boolean

Filter by presence of open work

sort?string

Order by recent_activity, created, or alphabetical

after?string

Return rows after the specified stable id cursor

limit?integer

Maximum number of direct rooms to return

Formatint32

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string/directs"

{  "directs": [    {      "channel": "string",      "direct_id": "string",      "last_activity_at": "2019-08-24T14:15:22Z",      "last_message_preview": "string",      "message_count": 0,      "open_work_count": 0,      "opened_at": "2019-08-24T14:15:22Z",      "session_a": "string",      "session_b": "string",      "workspace_id": "string"    }  ],  "page": {    "has_more": true,    "limit": 0,    "next_cursor": "string",    "total": 0  }}

Create or return a deterministic direct room

POST/api/workspaces/{workspace_id}/network/channels/{channel}/directs/resolve

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

peer_id*string

session_id*string

`application/json`

curl -X POST "https://example.com/api/workspaces/string/network/channels/string/directs/resolve" \  -H "Content-Type: application/json" \  -d '{    "peer_id": "string",    "session_id": "string"  }'

{  "direct": {    "channel": "string",    "direct_id": "string",    "last_activity_at": "2019-08-24T14:15:22Z",    "last_message_preview": "string",    "message_count": 0,    "open_work_count": 0,    "opened_at": "2019-08-24T14:15:22Z",    "session_a": "string",    "session_b": "string",    "workspace_id": "string"  }}

Get one direct-room summary

GET/api/workspaces/{workspace_id}/network/channels/{channel}/directs/{direct_id}

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

direct_id*string

Direct-room id

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string/directs/string"

{  "direct": {    "channel": "string",    "direct_id": "string",    "last_activity_at": "2019-08-24T14:15:22Z",    "last_message_preview": "string",    "message_count": 0,    "open_work_count": 0,    "opened_at": "2019-08-24T14:15:22Z",    "session_a": "string",    "session_b": "string",    "workspace_id": "string"  }}

List messages in one direct room

GET/api/workspaces/{workspace_id}/network/channels/{channel}/directs/{direct_id}/messages

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

direct_id*string

Direct-room id

Query Parameters

before?string

Return messages before the specified message id

after?string

Return messages after the specified message id

kind?string

Filter messages by network kind

work_id?string

Filter messages by work id

limit?integer

Maximum number of messages to return

Formatint32

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string/directs/string/messages"

{  "messages": [    {      "body": null,      "causation_id": "string",      "channel": "string",      "direct_id": "string",      "direction": "string",      "display_name": "string",      "intent": "string",      "kind": "string",      "local": true,      "mentions": [        "string"      ],      "message_id": "string",      "peer_from": "string",      "peer_to": "string",      "preview_text": "string",      "reply_to": "string",      "session_id": "string",      "size_bytes": 0,      "surface": "string",      "text": "string",      "thread_id": "string",      "timestamp": "2019-08-24T14:15:22Z",      "trace_id": "string",      "work_id": "string",      "workspace_id": "string"    }  ],  "page": {    "has_more": true,    "limit": 0,    "next_cursor": "string"  }}

List delivery subscriptions for one network channel

GET/api/workspaces/{workspace_id}/network/channels/{channel}/subscriptions

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

Query Parameters

session_id?string

Filter subscriptions by session id

thread_id?string

Filter subscriptions by thread id

limit?integer

Maximum number of subscriptions to return

Formatint32

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string/subscriptions"

{  "subscriptions": [    {      "channel": "string",      "created_at": "2019-08-24T14:15:22Z",      "mode": "string",      "session_id": "string",      "thread_id": "string",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    }  ]}

Create or update one network delivery subscription

PUT/api/workspaces/{workspace_id}/network/channels/{channel}/subscriptions

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

mode*string

session_id*string

thread_id?string

`application/json`

curl -X PUT "https://example.com/api/workspaces/string/network/channels/string/subscriptions" \  -H "Content-Type: application/json" \  -d '{    "mode": "string",    "session_id": "string"  }'

{  "subscription": {    "channel": "string",    "created_at": "2019-08-24T14:15:22Z",    "mode": "string",    "session_id": "string",    "thread_id": "string",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string"  }}

Delete one network delivery subscription

DELETE/api/workspaces/{workspace_id}/network/channels/{channel}/subscriptions/{session_id}

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

session_id*string

Network session id

Query Parameters

thread_id?string

Delete the thread-scoped subscription for this session

`application/json`

curl -X DELETE "https://example.com/api/workspaces/string/network/channels/string/subscriptions/string"

Empty

List public threads in one network channel

GET/api/workspaces/{workspace_id}/network/channels/{channel}/threads

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

Query Parameters

session_id?string

Filter by participant session id

query?string

Filter threads by title, peer, or preview text

has_work?boolean

Filter by presence of open work

sort?string

Order by recent_activity, created, or alphabetical

after?string

Return rows after the specified stable id cursor

limit?integer

Maximum number of threads to return

Formatint32

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string/threads"

{  "page": {    "has_more": true,    "limit": 0,    "next_cursor": "string",    "total": 0  },  "threads": [    {      "channel": "string",      "coordination_cost": {        "delivered_count": 0,        "estimated_prompt_tokens": 0,        "prompt_size_bytes": 0      },      "last_activity_at": "2019-08-24T14:15:22Z",      "last_message_preview": "string",      "message_count": 0,      "open_work_count": 0,      "opened_at": "2019-08-24T14:15:22Z",      "opened_by_peer_id": "string",      "opened_session_id": "string",      "participant_count": 0,      "root_message_id": "string",      "thread_id": "string",      "title": "string",      "workspace_id": "string"    }  ]}

Get one public-thread summary

GET/api/workspaces/{workspace_id}/network/channels/{channel}/threads/{thread_id}

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

thread_id*string

Public thread id

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string/threads/string"

{  "session_costs": [    {      "delivered_count": 0,      "estimated_prompt_tokens": 0,      "first_delivered_at": "2019-08-24T14:15:22Z",      "last_delivered_at": "2019-08-24T14:15:22Z",      "prompt_size_bytes": 0,      "session_id": "string"    }  ],  "task_links": [    {      "channel": "string",      "created_at": "2019-08-24T14:15:22Z",      "digest": "string",      "origin_message_id": "string",      "source_message_ids": [        "string"      ],      "task_id": "string",      "thread_id": "string",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    }  ],  "thread": {    "channel": "string",    "coordination_cost": {      "delivered_count": 0,      "estimated_prompt_tokens": 0,      "prompt_size_bytes": 0    },    "last_activity_at": "2019-08-24T14:15:22Z",    "last_message_preview": "string",    "message_count": 0,    "open_work_count": 0,    "opened_at": "2019-08-24T14:15:22Z",    "opened_by_peer_id": "string",    "opened_session_id": "string",    "participant_count": 0,    "root_message_id": "string",    "thread_id": "string",    "title": "string",    "workspace_id": "string"  }}

List messages in one public thread

GET/api/workspaces/{workspace_id}/network/channels/{channel}/threads/{thread_id}/messages

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

thread_id*string

Public thread id

Query Parameters

before?string

Return messages before the specified message id

after?string

Return messages after the specified message id

kind?string

Filter messages by network kind

work_id?string

Filter messages by work id

limit?integer

Maximum number of messages to return

Formatint32

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/channels/string/threads/string/messages"

{  "messages": [    {      "body": null,      "causation_id": "string",      "channel": "string",      "direct_id": "string",      "direction": "string",      "display_name": "string",      "intent": "string",      "kind": "string",      "local": true,      "mentions": [        "string"      ],      "message_id": "string",      "peer_from": "string",      "peer_to": "string",      "preview_text": "string",      "reply_to": "string",      "session_id": "string",      "size_bytes": 0,      "surface": "string",      "text": "string",      "thread_id": "string",      "timestamp": "2019-08-24T14:15:22Z",      "trace_id": "string",      "work_id": "string",      "workspace_id": "string"    }  ],  "page": {    "has_more": true,    "limit": 0,    "next_cursor": "string"  }}

Promote one network thread message into a durable task

POST/api/workspaces/{workspace_id}/network/channels/{channel}/threads/{thread_id}/promote-task

Path Parameters

workspace_id*string

Workspace id

channel*string

Network channel

thread_id*string

Public thread id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

description?string

metadata?unknown

origin_message_id*string

priority?string

title?string

`application/json`

curl -X POST "https://example.com/api/workspaces/string/network/channels/string/threads/string/promote-task" \  -H "Content-Type: application/json" \  -d '{    "origin_message_id": "string"  }'

{  "origin": {    "channel": "string",    "created_at": "2019-08-24T14:15:22Z",    "digest": "string",    "origin_message_id": "string",    "source_message_ids": [      "string"    ],    "task_id": "string",    "thread_id": "string",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string"  },  "task": {    "approval_policy": "none",    "approval_state": "not_required",    "auto_enqueue_on_ready": true,    "blocked_reasons": [      {        "block_id": "string",        "depends_on_task_ids": [          "string"        ],        "kind": "needs_input",        "reason": "string",        "source": "dependency"      }    ],    "closed_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "created_by": {      "kind": "human",      "ref": "string"    },    "current_run_id": "string",    "description": "string",    "draft": true,    "effective_paused": true,    "id": "string",    "identifier": "string",    "latest_event_seq": 0,    "max_attempts": 0,    "metadata": null,    "needs_attention": true,    "needs_attention_at": "2019-08-24T14:15:22Z",    "needs_attention_by": {      "kind": "human",      "ref": "string"    },    "needs_attention_reason": "string",    "origin": {      "kind": "cli",      "ref": "string"    },    "owner": {      "kind": "human",      "ref": "string"    },    "parent_task_id": "string",    "paused": true,    "paused_at": "2019-08-24T14:15:22Z",    "paused_by": "string",    "paused_by_task_id": "string",    "paused_reason": "string",    "priority": "low",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "scope": "global",    "status": "draft",    "title": "string",    "updated_at": "2019-08-24T14:15:22Z",    "wake_creator": true,    "workspace_id": "string"  }}

List queued network inbox messages for one local session

GET/api/workspaces/{workspace_id}/network/inbox

Query Parameters

session_id*string

Target local session id

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/inbox?session_id=string"

{  "messages": [    {      "body": null,      "causation_id": "string",      "channel": "string",      "direct_id": "string",      "expires_at": 0,      "ext": {        "property1": null,        "property2": null      },      "from": "string",      "id": "string",      "kind": "string",      "mentions": [        "string"      ],      "proof": {        "property1": null,        "property2": null      },      "protocol": "string",      "reply_to": "string",      "surface": "string",      "thread_id": "string",      "to": "string",      "trace_id": "string",      "ts": 0,      "work_id": "string",      "workspace_id": "string"    }  ]}

List visible network peers

GET/api/workspaces/{workspace_id}/network/peers

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/peers"

{  "peers": [    {      "channel": "string",      "display_name": "string",      "joined_at": "2019-08-24T14:15:22Z",      "local": true,      "peer_card": {        "artifacts_supported": [          "string"        ],        "capabilities": [          {            "id": "string",            "summary": "string"          }        ],        "display_name": "string",        "ext": {          "property1": null,          "property2": null        },        "peer_id": "string",        "profiles_supported": [          "string"        ],        "trust_modes_supported": [          "string"        ]      },      "peer_id": "string",      "presence_state": "string",      "session_id": "string",      "workspace_id": "string"    }  ]}

Get one visible network peer detail

GET/api/workspaces/{workspace_id}/network/peers/{peer_id}

Path Parameters

workspace_id*string

Workspace id

peer_id*string

Network peer id

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/peers/string"

{  "peer": {    "capability_catalog": {      "capabilities": [        {          "artifacts_expected": [            "string"          ],          "constraints": [            "string"          ],          "context_needed": [            "string"          ],          "digest": "string",          "examples": [            "string"          ],          "execution_outline": [            "string"          ],          "id": "string",          "outcome": "string",          "requirements": [            "string"          ],          "summary": "string",          "version": "string"        }      ]    },    "channel": "string",    "display_name": "string",    "joined_at": "2019-08-24T14:15:22Z",    "local": true,    "metrics": {      "delivered": 0,      "delivered_size_bytes": 0,      "received": 0,      "received_size_bytes": 0,      "rejected": 0,      "rejected_size_bytes": 0,      "sent": 0,      "sent_size_bytes": 0,      "total_size_bytes": 0    },    "peer_card": {      "artifacts_supported": [        "string"      ],      "capabilities": [        {          "id": "string",          "summary": "string"        }      ],      "display_name": "string",      "ext": {        "property1": null,        "property2": null      },      "peer_id": "string",      "profiles_supported": [        "string"      ],      "trust_modes_supported": [        "string"      ]    },    "peer_id": "string",    "presence_state": "string",    "session_id": "string"  }}

Send one network message

POST/api/workspaces/{workspace_id}/network/send

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

For say, capability, receipt, and trace, surface is required. surface=thread requires thread_id; the first valid send creates the public thread. surface=direct requires an existing direct_id. capability, receipt, and trace also require work_id. capability and lifecycle-bearing say also require to. greet and whois omit conversation and work fields.

body*

Kind-specific object. say requires a non-empty text field; other kinds follow the Compozy Network message body rules.

causation_id?string

channel*string

direct_id?string

Required with surface=direct. Resolve the existing room before sending.

Match^direct_[a-f0-9]{32}$

expires_at?|

Formatint64

ext?

id?string

kind*string

Value in

"greet"
"whois"
"say"
"capability"
"receipt"
"trace"

mentions?array<string>

reply_to?string

session_id*string

surface?string

Required for say, capability, receipt, and trace; omitted for greet and whois.

Value in

"thread"
"direct"

thread_id?string

Required with surface=thread. Use a fresh valid ID. The first valid send creates the public thread; later sends reuse the same ID.

Match^thread_[a-z0-9][a-z0-9_-]{2,95}$

to?string

Target peer. Required for capability and for say carrying work_id.

trace_id?string

work_id?string

Required for capability, receipt, and trace; optional for lifecycle-bearing say messages.

workspace_id?string

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/network/send" \  -H "Content-Type: application/json" \  -d '{    "body": {      "property1": null,      "property2": null    },    "channel": "string",    "kind": "greet",    "session_id": "string"  }'

{  "message": {    "causation_id": "string",    "channel": "string",    "direct_id": "string",    "expires_at": 0,    "ext": {      "property1": null,      "property2": null    },    "id": "string",    "kind": "string",    "mentions": [      "string"    ],    "reply_to": "string",    "session_id": "string",    "surface": "string",    "thread_id": "string",    "to": "string",    "trace_id": "string",    "work_id": "string",    "workspace_id": "string"  }}

Value in

"session"
"task_run"
"loop_run"
"automation_run"

owner_id?string

Filter by participation owner id; requires owner_kind

run_id?string

Filter by task or loop run id; mutually exclusive with owner

channel?string

Filter by Network channel

cursor?string

Continue from an opaque query-bound usage cursor

limit?integer

Maximum usage details to return; defaults to 50 and cannot exceed 200

Formatint32

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/usage"

{  "budget": {    "exhausted_reason": "string",    "input_tokens_used": 0,    "output_tokens_used": 0,    "participation_status": {      "available": true,      "owner": {        "id": "string",        "kind": "session",        "workspace_id": "string"      },      "participating": true,      "reason": "string"    },    "updated_at": "2019-08-24T14:15:22Z",    "wakes_used": 0,    "wall_time_used": "string"  },  "details": [    {      "channel": "string",      "charged_wall_time": "string",      "depth": 0,      "input_tokens": 0,      "output_tokens": 0,      "participation_status": {        "available": true,        "owner": {          "id": "string",          "kind": "session",          "workspace_id": "string"        },        "participating": true,        "reason": "string"      },      "reason": "string",      "reserved_at": "2019-08-24T14:15:22Z",      "root_id": "string",      "settled_at": "2019-08-24T14:15:22Z",      "state": "string",      "task_run_id": "string",      "usage_state": "string",      "wake_id": "string",      "workspace_id": "string"    }  ],  "next_cursor": "string",  "total": {    "actual_wake_count": 0,    "charged_wall_time": "string",    "input_tokens": 0,    "output_tokens": 0,    "reserved_wake_count": 0,    "unavailable_wake_count": 0,    "wake_count": 0  },  "workspace_id": "string"}

Get one network work item

GET/api/workspaces/{workspace_id}/network/work/{work_id}

Path Parameters

workspace_id*string

Workspace id

work_id*string

Network work id

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/string/network/work/string"

{  "work": {    "channel": "string",    "direct_id": "string",    "last_activity_at": "2019-08-24T14:15:22Z",    "opened_at": "2019-08-24T14:15:22Z",    "opened_session_id": "string",    "state": "string",    "surface": "string",    "target_session_id": "string",    "terminal_at": "2019-08-24T14:15:22Z",    "thread_id": "string",    "work_id": "string",    "workspace_id": "string"  }}

200application/json

500application/json

200text/event-stream

404application/json

409application/json

422application/json

500application/json

503application/json

201application/json

404application/json

409application/json

422application/json

500application/json

503application/json

200application/json

400application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

403application/json

404application/json

409application/json

500application/json

503application/json

200application/json

400application/json

403application/json

404application/json

409application/json

500application/json

503application/json

200application/json

500application/json

503application/json

201application/json

400application/json

404application/json

500application/json

503application/json

200application/json

400application/json

404application/json

500application/json

503application/json

200application/json

400application/json

404application/json

500application/json

503application/json

200application/json

400application/json

500application/json

503application/json

200application/json

400application/json

404application/json

409application/json

500application/json

503application/json

200application/json

400application/json

404application/json

500application/json

503application/json

200application/json

400application/json

404application/json

500application/json

503application/json

200application/json

400application/json

500application/json

503application/json

200application/json

400application/json

500application/json

503application/json

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`