Skip to content
CompozyOS RuntimeAPI Reference

Agent

Compozy Agent HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.
GET/api/agent/channels

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/agent/channels" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string"
{  "channels": [    {      "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"    }  ]}
POST/api/agent/channels/reply

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/channels/reply" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{    "body": null,    "metadata": {      "channel_id": "string",      "correlation_id": "string",      "message_kind": "status",      "run_id": "string",      "task_id": "string"    },    "reply_to_message_id": "string"  }'
{  "message": {    "body": null,    "channel_id": "string",    "from_session_id": "string",    "message_id": "string",    "metadata": {      "channel_id": "string",      "correlation_id": "string",      "ext": {        "property1": null,        "property2": null      },      "message_kind": "status",      "run_id": "string",      "task_id": "string",      "workflow_id": "string"    },    "timestamp": "2019-08-24T14:15:22Z",    "to_session_id": "string"  }}
GET/api/agent/channels/{channel}/recv

Path Parameters

channel*string

Coordination channel id

Query Parameters

wait?boolean

Wait for the next message when no messages are immediately available

limit?integer

Maximum number of messages to return

Formatint32

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/agent/channels/string/recv" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string"
{  "messages": [    {      "body": null,      "channel_id": "string",      "from_session_id": "string",      "message_id": "string",      "metadata": {        "channel_id": "string",        "correlation_id": "string",        "ext": {          "property1": null,          "property2": null        },        "message_kind": "status",        "run_id": "string",        "task_id": "string",        "workflow_id": "string"      },      "timestamp": "2019-08-24T14:15:22Z",      "to_session_id": "string"    }  ]}
POST/api/agent/channels/{channel}/send

Path Parameters

channel*string

Coordination channel id

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/channels/string/send" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{    "body": null,    "metadata": {      "channel_id": "string",      "correlation_id": "string",      "message_kind": "status",      "run_id": "string",      "task_id": "string"    }  }'
{  "message": {    "body": null,    "channel_id": "string",    "from_session_id": "string",    "message_id": "string",    "metadata": {      "channel_id": "string",      "correlation_id": "string",      "ext": {        "property1": null,        "property2": null      },      "message_kind": "status",      "run_id": "string",      "task_id": "string",      "workflow_id": "string"    },    "timestamp": "2019-08-24T14:15:22Z",    "to_session_id": "string"  }}
GET/api/agent/context

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/agent/context" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string"
{  "context": {    "capabilities": {      "capabilities": [        {          "id": "string",          "source": "string",          "summary": "string"        }      ],      "section": {        "limit": 0,        "returned": 0,        "truncated": true      }    },    "coordination_channel": {      "available": true,      "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"      }    },    "inbox_summary": {      "items": [        {          "channel_id": "string",          "kind": "status",          "message_id": "string",          "metadata": {            "channel_id": "string",            "correlation_id": "string",            "ext": {              "property1": null,              "property2": null            },            "message_kind": "status",            "run_id": "string",            "task_id": "string",            "workflow_id": "string"          },          "preview": "string",          "timestamp": "2019-08-24T14:15:22Z"        }      ],      "section": {        "limit": 0,        "returned": 0,        "truncated": true      },      "unread_count": 0    },    "limits": {      "context_section_limit": 0,      "max_active_task_leases": 0,      "max_children": 0,      "max_spawn_depth": 0    },    "peer_roster": {      "peers": [        {          "capabilities": [            "string"          ],          "channel_id": "string",          "display_name": "string",          "peer_id": "string",          "session_id": "string"        }      ],      "section": {        "limit": 0,        "returned": 0,        "truncated": true      }    },    "provenance": {      "generated_at": "2019-08-24T14:15:22Z",      "source": "string"    },    "self": {      "agent_name": "string",      "model": "string",      "provider": "string",      "session_id": "string"    },    "session": {      "created_at": "2019-08-24T14:15:22Z",      "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"      },      "name": "string",      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "state": "starting",      "type": "user",      "updated_at": "2019-08-24T14:15:22Z"    },    "soul": {      "active": true,      "config_digest": "string",      "digest": "string",      "enabled": true,      "max_body_bytes": 0,      "max_bytes": 0,      "present": true,      "principles": [        "string"      ],      "role": "string",      "snapshot_id": "string",      "source_path": "string",      "tone": [        "string"      ],      "truncated": true,      "valid": true,      "validation_status": "missing"    },    "task": {      "available": true,      "bundle": {        "current_run": {          "attempt": 0,          "claim_token_hash": "string",          "claimed_at": "2019-08-24T14:15:22Z",          "claimed_by": {            "kind": "human",            "ref": "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",          "lease_until": "2019-08-24T14:15:22Z",          "loop_run_id": "string",          "max_attempts": 0,          "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"          },          "run_kind": 0,          "session_id": "string",          "started_at": "2019-08-24T14:15:22Z",          "status": "queued",          "task_id": "string",          "tokens_used": 0        },        "execution_profile": {          "coordinator": {            "agent_name": "string",            "guidance": "string",            "mode": "inherit",            "model": "string",            "provider": "string"          },          "created_at": "2019-08-24T14:15:22Z",          "network_participation": {            "mode": "local"          },          "participants": {            "allowed_agent_names": [              "string"            ],            "allowed_channel_ids": [              "string"            ],            "allowed_peer_ids": [              "string"            ],            "preferred_agent_names": [              "string"            ],            "preferred_capabilities": [              "string"            ],            "preferred_channel_ids": [              "string"            ],            "preferred_peer_ids": [              "string"            ],            "required_capabilities": [              "string"            ]          },          "review": {            "agent_name": "string",            "allowed_agent_names": [              "string"            ],            "allowed_channel_ids": [              "string"            ],            "allowed_peer_ids": [              "string"            ],            "model": "string",            "preferred_agent_names": [              "string"            ],            "preferred_capabilities": [              "string"            ],            "preferred_channel_ids": [              "string"            ],            "preferred_peer_ids": [              "string"            ],            "provider": "string",            "required_capabilities": [              "string"            ]          },          "runtime": {            "mode": "default"          },          "sandbox": {            "mode": "inherit",            "sandbox_ref": "string"          },          "task_id": "string",          "updated_at": "2019-08-24T14:15:22Z",          "worker": {            "agent_name": "string",            "allowed_agent_names": [              "string"            ],            "mode": "inherit",            "model": "string",            "preferred_agent_names": [              "string"            ],            "preferred_capabilities": [              "string"            ],            "provider": "string",            "required_capabilities": [              "string"            ]          }        },        "handoff_summary": "string",        "latest_event_seq": 0,        "limits": {          "context_body_max_bytes": 0,          "max_runtime_seconds": 0,          "summary_max_bytes": 0        },        "prior_attempts": [          {            "attempt": 0,            "claim_token_hash": "string",            "claimed_at": "2019-08-24T14:15:22Z",            "claimed_by": {              "kind": "human",              "ref": "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",            "lease_until": "2019-08-24T14:15:22Z",            "loop_run_id": "string",            "max_attempts": 0,            "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"            },            "run_kind": 0,            "session_id": "string",            "started_at": "2019-08-24T14:15:22Z",            "status": "queued",            "task_id": "string",            "tokens_used": 0          }        ],        "recent_events": [          {            "actor": {              "kind": "human",              "ref": "string"            },            "event_id": "string",            "event_type": "string",            "origin": {              "kind": "cli",              "ref": "string"            },            "payload": null,            "run": {              "attempt": 0,              "claim_token_hash": "string",              "claimed_at": "2019-08-24T14:15:22Z",              "claimed_by": {                "kind": "human",                "ref": "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",              "lease_until": "2019-08-24T14:15:22Z",              "loop_run_id": "string",              "max_attempts": 0,              "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"              },              "run_kind": 0,              "session_id": "string",              "started_at": "2019-08-24T14:15:22Z",              "status": "queued",              "task_id": "string",              "tokens_used": 0            },            "sequence": 0,            "task": {              "effective_paused": true,              "id": "string",              "identifier": "string",              "latest_event_seq": 0,              "owner": {                "kind": "human",                "ref": "string"              },              "paused": true,              "paused_by_task_id": "string",              "priority": "low",              "scope": "global",              "status": "draft",              "title": "string",              "workspace_id": "string"            },            "timestamp": "2019-08-24T14:15:22Z"          }        ],        "review_continuation": {          "missing_work": [            "string"          ],          "next_round_guidance": "string",          "outcome": "string",          "reason": "string",          "review_id": "string",          "review_round": 0,          "reviewed_run_id": "string"        },        "review_history": [          {            "attempt": 0,            "outcome": "string",            "reason": "string",            "review_id": "string",            "review_round": 0,            "reviewed_at": "string",            "reviewer_label": "string",            "run_id": "string",            "status": "string"          }        ],        "task": {          "effective_paused": true,          "id": "string",          "identifier": "string",          "latest_event_seq": 0,          "owner": {            "kind": "human",            "ref": "string"          },          "paused": true,          "paused_by_task_id": "string",          "priority": "low",          "scope": "global",          "status": "draft",          "title": "string",          "workspace_id": "string"        }      },      "lease": {        "claim_token_hash": "string",        "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"        },        "heartbeat_at": "2019-08-24T14:15:22Z",        "lease_until": "2019-08-24T14:15:22Z",        "resolved_network_participation": {          "mode": "local",          "source": "explicit_request",          "version": "network-participation/v1"        },        "run_id": "string",        "session_id": "string",        "status": "queued",        "task_id": "string"      },      "task": {        "effective_paused": true,        "id": "string",        "identifier": "string",        "latest_event_seq": 0,        "owner": {          "kind": "human",          "ref": "string"        },        "paused": true,        "paused_by_task_id": "string",        "priority": "low",        "scope": "global",        "status": "draft",        "title": "string",        "workspace_id": "string"      }    },    "workspace": {      "id": "string",      "name": "string",      "root_dir": "string"    }  }}
GET/api/agent/coordinator/config

Query Parameters

workspace?string

Workspace id or path

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/agent/coordinator/config" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string"
{  "coordinator": {    "agent_name": "string",    "default_ttl_seconds": 0,    "enabled": true,    "max_active_sessions_per_workspace": 0,    "max_children": 0,    "model": "string",    "provider": "string",    "source": "workspace",    "workspace_id": "string"  }}
GET/api/agent/me

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/agent/me" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string"
{  "me": {    "active_task_leases": [      {        "claim_token_hash": "string",        "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"        },        "heartbeat_at": "2019-08-24T14:15:22Z",        "lease_until": "2019-08-24T14:15:22Z",        "resolved_network_participation": {          "mode": "local",          "source": "explicit_request",          "version": "network-participation/v1"        },        "run_id": "string",        "session_id": "string",        "status": "queued",        "task_id": "string"      }    ],    "capabilities": [      {        "id": "string",        "source": "string",        "summary": "string"      }    ],    "channels": [      {        "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"      }    ],    "coordinator": {      "agent_name": "string",      "default_ttl_seconds": 0,      "enabled": true,      "max_active_sessions_per_workspace": 0,      "max_children": 0,      "model": "string",      "provider": "string",      "source": "workspace",      "workspace_id": "string"    },    "limits": {      "context_section_limit": 0,      "max_active_task_leases": 0,      "max_children": 0,      "max_spawn_depth": 0    },    "self": {      "agent_name": "string",      "model": "string",      "provider": "string",      "session_id": "string"    },    "session": {      "created_at": "2019-08-24T14:15:22Z",      "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"      },      "name": "string",      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "state": "starting",      "type": "user",      "updated_at": "2019-08-24T14:15:22Z"    },    "workspace": {      "id": "string",      "name": "string",      "root_dir": "string"    }  }}
GET/api/agent/soul

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/agent/soul" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string"
{  "active": true,  "agent_name": "string",  "body": "string",  "config_provenance": {    "context_projection_bytes": 0,    "digest": "string",    "enabled": true,    "max_body_bytes": 0,    "source": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "diagnostics": [    {      "code": "string",      "column": 0,      "field": "string",      "line": 0,      "message": "string",      "owner_surface": "string",      "section": "string",      "severity": "info",      "source_path": "string"    }  ],  "digest": "string",  "enabled": true,  "frontmatter": {    "collaboration": [      "string"    ],    "constraints": [      "string"    ],    "memory_policy": [      "string"    ],    "principles": [      "string"    ],    "role": "string",    "tags": [      "string"    ],    "tone": [      "string"    ],    "version": "string"  },  "limits": {    "context_projection_bytes": 0,    "max_body_bytes": 0,    "max_bytes": 0  },  "present": true,  "revision_id": "string",  "snapshot_id": "string",  "source_path": "string",  "truncated": true,  "valid": true,  "validation_status": "missing"}
POST/api/agent/soul/validate

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/soul/validate" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{}'
{  "active": true,  "agent_name": "string",  "body": "string",  "config_provenance": {    "context_projection_bytes": 0,    "digest": "string",    "enabled": true,    "max_body_bytes": 0,    "source": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "diagnostics": [    {      "code": "string",      "column": 0,      "field": "string",      "line": 0,      "message": "string",      "owner_surface": "string",      "section": "string",      "severity": "info",      "source_path": "string"    }  ],  "digest": "string",  "enabled": true,  "frontmatter": {    "collaboration": [      "string"    ],    "constraints": [      "string"    ],    "memory_policy": [      "string"    ],    "principles": [      "string"    ],    "role": "string",    "tags": [      "string"    ],    "tone": [      "string"    ],    "version": "string"  },  "limits": {    "context_projection_bytes": 0,    "max_body_bytes": 0,    "max_bytes": 0  },  "present": true,  "revision_id": "string",  "snapshot_id": "string",  "source_path": "string",  "truncated": true,  "valid": true,  "validation_status": "missing"}
POST/api/agent/spawn

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/spawn" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{    "agent_name": "string",    "auto_stop_on_parent": true,    "permissions": {      "mcp_servers": [        "string"      ],      "network_channels": [        "string"      ],      "sandbox_profiles": [        "string"      ],      "skills": [        "string"      ],      "tools": [        "string"      ],      "workspace_paths": [        "string"      ]    },    "spawn_role": "string",    "ttl_seconds": 0  }'
{  "spawn": {    "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"    },    "permissions": {      "mcp_servers": [        "string"      ],      "network_channels": [        "string"      ],      "sandbox_profiles": [        "string"      ],      "skills": [        "string"      ],      "tools": [        "string"      ],      "workspace_paths": [        "string"      ]    },    "session": {      "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"    }  }}
POST/api/agent/tasks/claim-next

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/tasks/claim-next" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{}'
{  "claim": {    "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"    },    "lease": {      "claim_token_hash": "string",      "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"      },      "heartbeat_at": "2019-08-24T14:15:22Z",      "lease_until": "2019-08-24T14:15:22Z",      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "run_id": "string",      "session_id": "string",      "status": "queued",      "task_id": "string"    },    "run": {      "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"    },    "task": {      "effective_paused": true,      "id": "string",      "identifier": "string",      "latest_event_seq": 0,      "owner": {        "kind": "human",        "ref": "string"      },      "paused": true,      "paused_by_task_id": "string",      "priority": "low",      "scope": "global",      "status": "draft",      "title": "string",      "workspace_id": "string"    }  }}
POST/api/agent/tasks/{run_id}/complete

Path Parameters

run_id*string

Task run id

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/tasks/string/complete" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{}'
{  "lease": {    "claim_token_hash": "string",    "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"    },    "heartbeat_at": "2019-08-24T14:15:22Z",    "lease_until": "2019-08-24T14:15:22Z",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "run_id": "string",    "session_id": "string",    "status": "queued",    "task_id": "string"  }}
POST/api/agent/tasks/{run_id}/fail

Path Parameters

run_id*string

Task run id

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/tasks/string/fail" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{    "error": "string"  }'
{  "lease": {    "claim_token_hash": "string",    "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"    },    "heartbeat_at": "2019-08-24T14:15:22Z",    "lease_until": "2019-08-24T14:15:22Z",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "run_id": "string",    "session_id": "string",    "status": "queued",    "task_id": "string"  }}
POST/api/agent/tasks/{run_id}/heartbeat

Path Parameters

run_id*string

Task run id

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/tasks/string/heartbeat" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{}'
{  "lease": {    "claim_token_hash": "string",    "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"    },    "heartbeat_at": "2019-08-24T14:15:22Z",    "lease_until": "2019-08-24T14:15:22Z",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "run_id": "string",    "session_id": "string",    "status": "queued",    "task_id": "string"  }}
POST/api/agent/tasks/{run_id}/release

Path Parameters

run_id*string

Task run id

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/agent/tasks/string/release" \  -H "X-Compozy-Session-ID: string" \  -H "X-Compozy-Agent: string" \  -H "Content-Type: application/json" \  -d '{}'
{  "lease": {    "claim_token_hash": "string",    "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"    },    "heartbeat_at": "2019-08-24T14:15:22Z",    "lease_until": "2019-08-24T14:15:22Z",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "run_id": "string",    "session_id": "string",    "status": "queued",    "task_id": "string"  }}