Agents
CompozyOS Agents HTTP endpoints.
GET
workspace?stringWorkspace id, name, or path used to resolve workspace-local agents
profile?stringAct as this profile by name
OK
application/json- response
agents*array<>curl -X GET "https://example.com/api/agents"{ "agents": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "category_path": [ "string" ], "command": "string", "definition_digest": "string", "deny_tools": [ "string" ], "diagnostics": [ { "error_kind": "string", "message": "string", "path": "string" } ], "effective_runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "session_env_status": [ { "kind": "string", "name": "string", "present": true, "required": true, "secret_ref": "string", "source": "string", "target_env": "string" } ], "sources": { "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "speed": "normal" }, "fallback_chain": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "command": "string", "command_fingerprint": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "speed": "normal" } ], "layer": "string", "mcp_servers": [ { "args": [ "string" ], "auth": { "client_id": "string", "client_secret_configured": true, "issuer_url": "string", "registration": "string", "scopes": [ "string" ] }, "command": "string", "env": { "property1": "string", "property2": "string" }, "name": "string", "secret_env": { "property1": "string", "property2": "string" }, "transport": "string", "url": "string" } ], "model": "string", "name": "string", "origin": "global", "permissions": "string", "prompt": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "shadows": [ { "layer": "string", "path": "string" } ], "skills": { "disabled": [ "string" ] }, "speed": "normal", "tools": [ "string" ], "toolsets": [ "string" ], "workspace_access": "string", "workspace_id": "string" } ]}POST
profile?stringAct as this profile by name
JSON request body
application/json- body
agent*scope*stringValue in
"workspace""global"workspace?stringCreated
application/json- response
agent*curl -X POST "https://example.com/api/agents" \ -H "Content-Type: application/json" \ -d '{ "agent": { "name": "string", "prompt": "string" }, "scope": "workspace" }'{ "agent": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "category_path": [ "string" ], "command": "string", "definition_digest": "string", "deny_tools": [ "string" ], "diagnostics": [ { "error_kind": "string", "message": "string", "path": "string" } ], "effective_runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "session_env_status": [ { "kind": "string", "name": "string", "present": true, "required": true, "secret_ref": "string", "source": "string", "target_env": "string" } ], "sources": { "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "speed": "normal" }, "fallback_chain": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "command": "string", "command_fingerprint": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "speed": "normal" } ], "layer": "string", "mcp_servers": [ { "args": [ "string" ], "auth": { "client_id": "string", "client_secret_configured": true, "issuer_url": "string", "registration": "string", "scopes": [ "string" ] }, "command": "string", "env": { "property1": "string", "property2": "string" }, "name": "string", "secret_env": { "property1": "string", "property2": "string" }, "transport": "string", "url": "string" } ], "model": "string", "name": "string", "origin": "global", "permissions": "string", "prompt": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "shadows": [ { "layer": "string", "path": "string" } ], "skills": { "disabled": [ "string" ] }, "speed": "normal", "tools": [ "string" ], "toolsets": [ "string" ], "workspace_access": "string", "workspace_id": "string" }}GET
all_workspaces?booleanRead all projects and User rows
workspace_ids?array<string>Repeatable project IDs or @user; requires all_workspaces=true
name?stringExact agent name
q?stringCase-insensitive agent name or category search
category?stringExact category path joined by slash separators
status?stringAgent session status
Value in
"active""idle"cursor?stringOpaque cursor bound to workspace and filters
limit?integerAgents per page (1-100; default 50)
Format
int32profile?stringAct as this profile by name
OK
application/json- response
agents*array<>diagnostics?array<>facets*page*sessions_available*booleancurl -X GET "https://example.com/api/agents/aggregate"{ "agents": [ { "agent": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "category_path": [ "string" ], "command": "string", "definition_digest": "string", "deny_tools": [ "string" ], "diagnostics": [ { "error_kind": "string", "message": "string", "path": "string" } ], "effective_runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "session_env_status": [ { "kind": "string", "name": "string", "present": true, "required": true, "secret_ref": "string", "source": "string", "target_env": "string" } ], "sources": { "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "speed": "normal" }, "fallback_chain": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "command": "string", "command_fingerprint": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "speed": "normal" } ], "layer": "string", "mcp_servers": [ { "args": [ "string" ], "auth": { "client_id": "string", "client_secret_configured": true, "issuer_url": "string", "registration": "string", "scopes": [ "string" ] }, "command": "string", "env": { "property1": "string", "property2": "string" }, "name": "string", "secret_env": { "property1": "string", "property2": "string" }, "transport": "string", "url": "string" } ], "model": "string", "name": "string", "origin": "global", "permissions": "string", "prompt": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "shadows": [ { "layer": "string", "path": "string" } ], "skills": { "disabled": [ "string" ] }, "speed": "normal", "tools": [ "string" ], "toolsets": [ "string" ], "workspace_access": "string", "workspace_id": "string" }, "sessions": { "active": 0, "failed": 0, "last_activity_at": "2019-08-24T14:15:22Z", "runtime_seconds": 0, "total": 0 } } ], "diagnostics": [ { "category": "string", "code": "string", "data_freshness": "string", "doc_url": "string", "evidence": { "property1": null, "property2": null }, "id": "string", "message": "string", "severity": "string", "suggested_command": "string", "title": "string" } ], "facets": { "active": 0, "categories": [ "string" ], "idle": 0, "total": 0 }, "page": { "has_more": true, "limit": 0, "next_cursor": "string", "total": 0 }, "sessions_available": true}GET
workspace?stringWorkspace id, name, or path; omit for Global definitions and cross-workspace session metrics
name?stringExact agent name
q?stringCase-insensitive agent name or category search
category?stringExact category path joined by slash separators
status?stringAgent session status
Value in
"active""idle"cursor?stringOpaque cursor bound to workspace and filters
limit?integerAgents per page (1-100; default 50)
Format
int32profile?stringAct as this profile by name
OK
application/json- response
agents*array<>diagnostics?array<>facets*page*sessions_available*booleancurl -X GET "https://example.com/api/agents/catalog"{ "agents": [ { "agent": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "category_path": [ "string" ], "command": "string", "definition_digest": "string", "deny_tools": [ "string" ], "diagnostics": [ { "error_kind": "string", "message": "string", "path": "string" } ], "effective_runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "session_env_status": [ { "kind": "string", "name": "string", "present": true, "required": true, "secret_ref": "string", "source": "string", "target_env": "string" } ], "sources": { "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "speed": "normal" }, "fallback_chain": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "command": "string", "command_fingerprint": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "speed": "normal" } ], "layer": "string", "mcp_servers": [ { "args": [ "string" ], "auth": { "client_id": "string", "client_secret_configured": true, "issuer_url": "string", "registration": "string", "scopes": [ "string" ] }, "command": "string", "env": { "property1": "string", "property2": "string" }, "name": "string", "secret_env": { "property1": "string", "property2": "string" }, "transport": "string", "url": "string" } ], "model": "string", "name": "string", "origin": "global", "permissions": "string", "prompt": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "shadows": [ { "layer": "string", "path": "string" } ], "skills": { "disabled": [ "string" ] }, "speed": "normal", "tools": [ "string" ], "toolsets": [ "string" ], "workspace_access": "string", "workspace_id": "string" }, "sessions": { "active": 0, "failed": 0, "last_activity_at": "2019-08-24T14:15:22Z", "runtime_seconds": 0, "total": 0 } } ], "diagnostics": [ { "category": "string", "code": "string", "data_freshness": "string", "doc_url": "string", "evidence": { "property1": null, "property2": null }, "id": "string", "message": "string", "severity": "string", "suggested_command": "string", "title": "string" } ], "facets": { "active": 0, "categories": [ "string" ], "idle": 0, "total": 0 }, "page": { "has_more": true, "limit": 0, "next_cursor": "string", "total": 0 }, "sessions_available": true}GET
name*stringAgent name
workspace?stringWorkspace id, name, or path used to resolve a workspace-local agent
profile?stringAct as this profile by name
OK
application/json- response
agent*curl -X GET "https://example.com/api/agents/string"{ "agent": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "category_path": [ "string" ], "command": "string", "definition_digest": "string", "deny_tools": [ "string" ], "diagnostics": [ { "error_kind": "string", "message": "string", "path": "string" } ], "effective_runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "session_env_status": [ { "kind": "string", "name": "string", "present": true, "required": true, "secret_ref": "string", "source": "string", "target_env": "string" } ], "sources": { "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "speed": "normal" }, "fallback_chain": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "command": "string", "command_fingerprint": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "speed": "normal" } ], "layer": "string", "mcp_servers": [ { "args": [ "string" ], "auth": { "client_id": "string", "client_secret_configured": true, "issuer_url": "string", "registration": "string", "scopes": [ "string" ] }, "command": "string", "env": { "property1": "string", "property2": "string" }, "name": "string", "secret_env": { "property1": "string", "property2": "string" }, "transport": "string", "url": "string" } ], "model": "string", "name": "string", "origin": "global", "permissions": "string", "prompt": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "shadows": [ { "layer": "string", "path": "string" } ], "skills": { "disabled": [ "string" ] }, "speed": "normal", "tools": [ "string" ], "toolsets": [ "string" ], "workspace_access": "string", "workspace_id": "string" }}DELETE
name*stringAgent name
workspace?stringWorkspace id, name, or path used to resolve the effective definition
profile?stringAct as this profile by name
OK
application/json- response
name*stringorigin*stringValue in
"global""workspace"unshadowed_origin?stringValue in
"global""workspace"curl -X DELETE "https://example.com/api/agents/string"{ "name": "string", "origin": "global", "unshadowed_origin": "global"}PUT
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
agent*expected_digest*stringworkspace?stringOK
application/json- response
agent*curl -X PUT "https://example.com/api/agents/string" \ -H "Content-Type: application/json" \ -d '{ "agent": { "name": "string", "prompt": "string" }, "expected_digest": "string" }'{ "agent": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "category_path": [ "string" ], "command": "string", "definition_digest": "string", "deny_tools": [ "string" ], "diagnostics": [ { "error_kind": "string", "message": "string", "path": "string" } ], "effective_runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "session_env_status": [ { "kind": "string", "name": "string", "present": true, "required": true, "secret_ref": "string", "source": "string", "target_env": "string" } ], "sources": { "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "speed": "normal" }, "fallback_chain": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "command": "string", "command_fingerprint": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "speed": "normal" } ], "layer": "string", "mcp_servers": [ { "args": [ "string" ], "auth": { "client_id": "string", "client_secret_configured": true, "issuer_url": "string", "registration": "string", "scopes": [ "string" ] }, "command": "string", "env": { "property1": "string", "property2": "string" }, "name": "string", "secret_env": { "property1": "string", "property2": "string" }, "transport": "string", "url": "string" } ], "model": "string", "name": "string", "origin": "global", "permissions": "string", "prompt": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "shadows": [ { "layer": "string", "path": "string" } ], "skills": { "disabled": [ "string" ] }, "speed": "normal", "tools": [ "string" ], "toolsets": [ "string" ], "workspace_access": "string", "workspace_id": "string" }}POST
name*stringSource agent name
profile?stringAct as this profile by name
JSON request body
application/json- body
name*stringMatch
^[a-z][a-z0-9_-]{0,105}$Length
length <= 106overrides?|scope?stringValue in
"workspace""global"workspace?stringCreated
application/json- response
agent*curl -X POST "https://example.com/api/agents/string/duplicate" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "agent": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "category_path": [ "string" ], "command": "string", "definition_digest": "string", "deny_tools": [ "string" ], "diagnostics": [ { "error_kind": "string", "message": "string", "path": "string" } ], "effective_runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "session_env_status": [ { "kind": "string", "name": "string", "present": true, "required": true, "secret_ref": "string", "source": "string", "target_env": "string" } ], "sources": { "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "speed": "normal" }, "fallback_chain": [ { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "command": "string", "command_fingerprint": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "speed": "normal" } ], "layer": "string", "mcp_servers": [ { "args": [ "string" ], "auth": { "client_id": "string", "client_secret_configured": true, "issuer_url": "string", "registration": "string", "scopes": [ "string" ] }, "command": "string", "env": { "property1": "string", "property2": "string" }, "name": "string", "secret_env": { "property1": "string", "property2": "string" }, "transport": "string", "url": "string" } ], "model": "string", "name": "string", "origin": "global", "permissions": "string", "prompt": "string", "provider": "string", "reasoning_effort": "string", "session_env": { "property1": { "ref": "string", "required": true }, "property2": { "ref": "string", "required": true } }, "shadows": [ { "layer": "string", "path": "string" } ], "skills": { "disabled": [ "string" ] }, "speed": "normal", "tools": [ "string" ], "toolsets": [ "string" ], "workspace_access": "string", "workspace_id": "string" }}GET
name*stringAgent name
workspace_id?stringWorkspace id
profile?stringAct as this profile by name
OK
application/json- response
active*booleanagent_name?stringconfig_digest?stringconfig_provenance*created_at?|Format
date-timediagnostics?array<>digest?stringenabled*booleanfrontmatter*guidance_markdown?stringlimits*preferences*present*booleanprompt*schema_version*integersnapshot_id?stringsource_path?stringsummary?stringvalid*booleanvalidation_status*stringValue in
"missing""inactive""valid""invalid"curl -X GET "https://example.com/api/agents/string/heartbeat"{ "active": true, "agent_name": "string", "config_digest": "string", "config_provenance": { "digest": "string", "subset": { "active_session_only": true, "allow_active_hours_preferences": true, "context_projection_bytes": 0, "default_interval": "string", "enabled": true, "max_body_bytes": 0, "max_wakes_per_cycle": 0, "min_interval": "string", "session_health_hook_min_interval": "string", "session_health_stale_after": "string", "wake_cooldown": "string", "wake_event_retention": "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": { "context": { "include": [ "string" ] }, "enabled": true, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "summary": "string", "version": 0 }, "guidance_markdown": "string", "limits": { "context_projection_bytes": 0, "max_body_bytes": 0, "max_bytes": 0 }, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "present": true, "prompt": { "active": true, "config_digest": "string", "context": { "include": [ "string" ] }, "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "digest": "string", "guidance_markdown": "string", "max_body_bytes": 0, "max_bytes": 0, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "source_path": "string", "summary": "string", "truncated": true }, "schema_version": 0, "snapshot_id": "string", "source_path": "string", "summary": "string", "valid": true, "validation_status": "missing"}DELETE
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
expected_digest*stringworkspace_id?stringOK
application/json- response
heartbeat*revision*curl -X DELETE "https://example.com/api/agents/string/heartbeat" \ -H "Content-Type: application/json" \ -d '{ "expected_digest": "string" }'{ "heartbeat": { "active": true, "agent_name": "string", "config_digest": "string", "config_provenance": { "digest": "string", "subset": { "active_session_only": true, "allow_active_hours_preferences": true, "context_projection_bytes": 0, "default_interval": "string", "enabled": true, "max_body_bytes": 0, "max_wakes_per_cycle": 0, "min_interval": "string", "session_health_hook_min_interval": "string", "session_health_stale_after": "string", "wake_cooldown": "string", "wake_event_retention": "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": { "context": { "include": [ "string" ] }, "enabled": true, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "summary": "string", "version": 0 }, "guidance_markdown": "string", "limits": { "context_projection_bytes": 0, "max_body_bytes": 0, "max_bytes": 0 }, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "present": true, "prompt": { "active": true, "config_digest": "string", "context": { "include": [ "string" ] }, "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "digest": "string", "guidance_markdown": "string", "max_body_bytes": 0, "max_bytes": 0, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "source_path": "string", "summary": "string", "truncated": true }, "schema_version": 0, "snapshot_id": "string", "source_path": "string", "summary": "string", "valid": true, "validation_status": "missing" }, "revision": { "actor": { "kind": "user", "ref": "string" }, "agent_name": "string", "created_at": "2019-08-24T14:15:22Z", "id": "string", "new_digest": "string", "new_snapshot_id": "string", "operation": "write", "previous_digest": "string", "source_path": "string" }}PUT
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
body*stringexpected_digest*stringidempotency_key?stringworkspace_id?stringOK
application/json- response
heartbeat*revision*curl -X PUT "https://example.com/api/agents/string/heartbeat" \ -H "Content-Type: application/json" \ -d '{ "body": "string", "expected_digest": "string" }'{ "heartbeat": { "active": true, "agent_name": "string", "config_digest": "string", "config_provenance": { "digest": "string", "subset": { "active_session_only": true, "allow_active_hours_preferences": true, "context_projection_bytes": 0, "default_interval": "string", "enabled": true, "max_body_bytes": 0, "max_wakes_per_cycle": 0, "min_interval": "string", "session_health_hook_min_interval": "string", "session_health_stale_after": "string", "wake_cooldown": "string", "wake_event_retention": "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": { "context": { "include": [ "string" ] }, "enabled": true, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "summary": "string", "version": 0 }, "guidance_markdown": "string", "limits": { "context_projection_bytes": 0, "max_body_bytes": 0, "max_bytes": 0 }, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "present": true, "prompt": { "active": true, "config_digest": "string", "context": { "include": [ "string" ] }, "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "digest": "string", "guidance_markdown": "string", "max_body_bytes": 0, "max_bytes": 0, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "source_path": "string", "summary": "string", "truncated": true }, "schema_version": 0, "snapshot_id": "string", "source_path": "string", "summary": "string", "valid": true, "validation_status": "missing" }, "revision": { "actor": { "kind": "user", "ref": "string" }, "agent_name": "string", "created_at": "2019-08-24T14:15:22Z", "id": "string", "new_digest": "string", "new_snapshot_id": "string", "operation": "write", "previous_digest": "string", "source_path": "string" }}GET
name*stringAgent name
workspace_id?stringWorkspace id
limit?integerMaximum number of revisions to return
Format
int32cursor?stringRevision cursor
profile?stringAct as this profile by name
OK
application/json- response
next_cursor?stringrevisions*array<>curl -X GET "https://example.com/api/agents/string/heartbeat/history"{ "next_cursor": "string", "revisions": [ { "actor": { "kind": "user", "ref": "string" }, "agent_name": "string", "created_at": "2019-08-24T14:15:22Z", "id": "string", "new_digest": "string", "new_snapshot_id": "string", "operation": "write", "previous_digest": "string", "source_path": "string" } ]}POST
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
expected_digest*stringidempotency_key?stringrevision_id?stringtarget_digest?stringworkspace_id?stringOK
application/json- response
heartbeat*revision*curl -X POST "https://example.com/api/agents/string/heartbeat/rollback" \ -H "Content-Type: application/json" \ -d '{ "expected_digest": "string" }'{ "heartbeat": { "active": true, "agent_name": "string", "config_digest": "string", "config_provenance": { "digest": "string", "subset": { "active_session_only": true, "allow_active_hours_preferences": true, "context_projection_bytes": 0, "default_interval": "string", "enabled": true, "max_body_bytes": 0, "max_wakes_per_cycle": 0, "min_interval": "string", "session_health_hook_min_interval": "string", "session_health_stale_after": "string", "wake_cooldown": "string", "wake_event_retention": "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": { "context": { "include": [ "string" ] }, "enabled": true, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "summary": "string", "version": 0 }, "guidance_markdown": "string", "limits": { "context_projection_bytes": 0, "max_body_bytes": 0, "max_bytes": 0 }, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "present": true, "prompt": { "active": true, "config_digest": "string", "context": { "include": [ "string" ] }, "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "digest": "string", "guidance_markdown": "string", "max_body_bytes": 0, "max_bytes": 0, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "source_path": "string", "summary": "string", "truncated": true }, "schema_version": 0, "snapshot_id": "string", "source_path": "string", "summary": "string", "valid": true, "validation_status": "missing" }, "revision": { "actor": { "kind": "user", "ref": "string" }, "agent_name": "string", "created_at": "2019-08-24T14:15:22Z", "id": "string", "new_digest": "string", "new_snapshot_id": "string", "operation": "write", "previous_digest": "string", "source_path": "string" }}GET
name*stringAgent name
workspace_id?stringWorkspace id
session_id?stringSession id for wake state and health
include_session_health?booleanInclude session health when a session id is supplied
include_recent_wake_events?booleanInclude recent wake audit rows
profile?stringAct as this profile by name
OK
application/json- response
active*booleanagent_name*stringconfig_digest?stringdiagnostics?array<>digest?stringenabled*booleanpreferences*present*booleanrevision_cursor?stringsession_health?|snapshot_id?stringsource_path?stringsummary?stringvalid*booleanvalidation_status*stringValue in
"missing""inactive""valid""invalid"wake_events?array<>wake_state?|curl -X GET "https://example.com/api/agents/string/heartbeat/status"{ "active": true, "agent_name": "string", "config_digest": "string", "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, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "present": true, "revision_cursor": "string", "session_health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": 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", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "snapshot_id": "string", "source_path": "string", "summary": "string", "valid": true, "validation_status": "missing", "wake_events": [ { "agent_name": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "string", "policy_snapshot_id": "string", "reason": "wake_sent", "result": "sent", "session_id": "string", "source": "scheduler", "synthetic_prompt_id": "string", "workspace_id": "string" } ], "wake_state": { "agent_name": "string", "coalesced_count": 0, "last_reason": "wake_sent", "last_result": "sent", "last_wake_at": "2019-08-24T14:15:22Z", "next_allowed_at": "2019-08-24T14:15:22Z", "policy_snapshot_id": "string", "session_id": "string", "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" }}POST
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
body*stringworkspace_id?stringOK
application/json- response
active*booleanagent_name?stringconfig_digest?stringconfig_provenance*created_at?|Format
date-timediagnostics?array<>digest?stringenabled*booleanfrontmatter*guidance_markdown?stringlimits*preferences*present*booleanprompt*schema_version*integersnapshot_id?stringsource_path?stringsummary?stringvalid*booleanvalidation_status*stringValue in
"missing""inactive""valid""invalid"curl -X POST "https://example.com/api/agents/string/heartbeat/validate" \ -H "Content-Type: application/json" \ -d '{ "body": "string" }'{ "active": true, "agent_name": "string", "config_digest": "string", "config_provenance": { "digest": "string", "subset": { "active_session_only": true, "allow_active_hours_preferences": true, "context_projection_bytes": 0, "default_interval": "string", "enabled": true, "max_body_bytes": 0, "max_wakes_per_cycle": 0, "min_interval": "string", "session_health_hook_min_interval": "string", "session_health_stale_after": "string", "wake_cooldown": "string", "wake_event_retention": "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": { "context": { "include": [ "string" ] }, "enabled": true, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "summary": "string", "version": 0 }, "guidance_markdown": "string", "limits": { "context_projection_bytes": 0, "max_body_bytes": 0, "max_bytes": 0 }, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "present": true, "prompt": { "active": true, "config_digest": "string", "context": { "include": [ "string" ] }, "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "digest": "string", "guidance_markdown": "string", "max_body_bytes": 0, "max_bytes": 0, "preferences": { "active_hours": [ { "end": "string", "start": "string", "timezone": "string" } ], "context": { "include": [ "string" ] }, "min_interval": "string", "quiet_windows": [ { "end": "string", "start": "string", "timezone": "string" } ] }, "source_path": "string", "summary": "string", "truncated": true }, "schema_version": 0, "snapshot_id": "string", "source_path": "string", "summary": "string", "valid": true, "validation_status": "missing"}POST
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
dry_run?booleanidempotency_key?stringsession_id*stringsource*stringValue in
"scheduler""manual""harness_reentry"workspace_id?stringOK
application/json- response
decision*curl -X POST "https://example.com/api/agents/string/heartbeat/wake" \ -H "Content-Type: application/json" \ -d '{ "session_id": "string", "source": "scheduler" }'{ "decision": { "config_digest": "string", "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "policy_digest": "string", "policy_snapshot_id": "string", "reason": "wake_sent", "result": "sent", "synthetic_prompt_id": "string", "wake_event_id": "string" }}GET
name*stringAgent name
workspace_id?stringWorkspace id
profile?stringAct as this profile by name
OK
application/json- response
active*booleanagent_name?stringbody?stringconfig_provenance*created_at?|Format
date-timediagnostics?array<>digest?stringenabled*booleanfrontmatter*limits*present*booleanrevision_id?stringsnapshot_id?stringsource_path?stringtruncated?booleanvalid*booleanvalidation_status*stringValue in
"missing""inactive""valid""invalid"curl -X GET "https://example.com/api/agents/string/soul"{ "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" ], "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"}DELETE
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
expected_digest*stringworkspace_id?stringOK
application/json- response
revision*soul*curl -X DELETE "https://example.com/api/agents/string/soul" \ -H "Content-Type: application/json" \ -d '{ "expected_digest": "string" }'{ "revision": { "action": "put", "actor": { "kind": "string", "ref": "string" }, "agent_name": "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" } ], "id": "string", "new_digest": "string", "origin": { "kind": "string", "ref": "string" }, "previous_digest": "string", "source_path": "string" }, "soul": { "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" ], "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" }}PUT
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
body*stringexpected_digest*stringidempotency_key?stringworkspace_id?stringOK
application/json- response
revision*soul*curl -X PUT "https://example.com/api/agents/string/soul" \ -H "Content-Type: application/json" \ -d '{ "body": "string", "expected_digest": "string" }'{ "revision": { "action": "put", "actor": { "kind": "string", "ref": "string" }, "agent_name": "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" } ], "id": "string", "new_digest": "string", "origin": { "kind": "string", "ref": "string" }, "previous_digest": "string", "source_path": "string" }, "soul": { "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" ], "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" }}GET
name*stringAgent name
workspace_id?stringWorkspace id
limit?integerMaximum number of revisions to return
Format
int32cursor?stringRevision cursor
profile?stringAct as this profile by name
OK
application/json- response
next_cursor?stringrevisions*array<>curl -X GET "https://example.com/api/agents/string/soul/history"{ "next_cursor": "string", "revisions": [ { "action": "put", "actor": { "kind": "string", "ref": "string" }, "agent_name": "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" } ], "id": "string", "new_digest": "string", "origin": { "kind": "string", "ref": "string" }, "previous_digest": "string", "source_path": "string" } ]}POST
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
expected_digest*stringidempotency_key?stringrevision_id*stringworkspace_id?stringOK
application/json- response
revision*soul*curl -X POST "https://example.com/api/agents/string/soul/rollback" \ -H "Content-Type: application/json" \ -d '{ "expected_digest": "string", "revision_id": "string" }'{ "revision": { "action": "put", "actor": { "kind": "string", "ref": "string" }, "agent_name": "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" } ], "id": "string", "new_digest": "string", "origin": { "kind": "string", "ref": "string" }, "previous_digest": "string", "source_path": "string" }, "soul": { "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" ], "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
name*stringAgent name
profile?stringAct as this profile by name
JSON request body
application/json- body
body?stringworkspace_id?stringOK
application/json- response
active*booleanagent_name?stringbody?stringconfig_provenance*created_at?|Format
date-timediagnostics?array<>digest?stringenabled*booleanfrontmatter*limits*present*booleanrevision_id?stringsnapshot_id?stringsource_path?stringtruncated?booleanvalid*booleanvalidation_status*stringValue in
"missing""inactive""valid""invalid"curl -X POST "https://example.com/api/agents/string/soul/validate" \ -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" ], "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"}