AGH RuntimeAPI Reference
Agents
AGH Agents HTTP endpoints.
- Audience
- Operators running durable agent work
- Focus
- API Reference guidance shaped for scanability, day-two clarity, and operator context.
List all readable agent definitions, optionally resolved for a workspace
GET
/api/agentsQuery Parameters
workspace?string
Workspace id, name, or path used to resolve workspace-local agents
Response Body
application/json
application/json
curl -X GET "https://loading/api/agents"{
"agents": [
{
"command": "string",
"deny_tools": [
"string"
],
"mcp_servers": [
{
"args": [
"string"
],
"auth": {
"authorization_url": "string",
"client_id": "string",
"client_secret_ref": "string",
"issuer_url": "string",
"metadata_url": "string",
"revocation_url": "string",
"scopes": [
"string"
],
"token_url": "string",
"type": "string"
},
"command": "string",
"env": {
"property1": "string",
"property2": "string"
},
"name": "string",
"secret_env": {
"property1": "string",
"property2": "string"
},
"transport": "string",
"url": "string"
}
],
"model": "string",
"name": "string",
"permissions": "string",
"prompt": "string",
"provider": "string",
"tools": [
"string"
],
"toolsets": [
"string"
]
}
]
}{
"error": "string"
}Empty
Inspect the resolved Heartbeat policy for an agent definition
GET
/api/agents/{agent_name}/heartbeatPath Parameters
agent_name*string
Agent name
Query Parameters
workspace_id?string
Workspace id
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://loading/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"
}{
"error": "string"
}{
"error": "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"
}{
"error": "string"
}Empty
Delete HEARTBEAT.md through managed authoring
DELETE
/api/agents/{agent_name}/heartbeatPath Parameters
agent_name*string
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 DELETE "https://loading/api/agents/string/heartbeat" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "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"
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty
Create or replace HEARTBEAT.md through managed authoring
PUT
/api/agents/{agent_name}/heartbeatPath Parameters
agent_name*string
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 PUT "https://loading/api/agents/string/heartbeat" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "string", "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"
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "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"
}{
"error": "string"
}Empty
List managed HEARTBEAT.md authoring revisions
GET
/api/agents/{agent_name}/heartbeat/historyPath Parameters
agent_name*string
Agent name
Query Parameters
workspace_id?string
Workspace id
limit?integer
Maximum number of revisions to return
Format
int32cursor?string
Revision cursor
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://loading/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"
}
]
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty
Rollback HEARTBEAT.md through managed authoring
POST
/api/agents/{agent_name}/heartbeat/rollbackPath Parameters
agent_name*string
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://loading/api/agents/string/heartbeat/rollback" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "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"
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "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"
}{
"error": "string"
}Empty
Read Heartbeat policy status, wake state, and optional session health
GET
/api/agents/{agent_name}/heartbeat/statusPath Parameters
agent_name*string
Agent name
Query Parameters
workspace_id?string
Workspace id
session_id?string
Session id for wake state and health
include_session_health?boolean
Include session health when a session id is supplied
include_recent_wake_events?boolean
Include recent wake audit rows
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://loading/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,
"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"
},
"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"
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty
Validate a proposed HEARTBEAT.md body
POST
/api/agents/{agent_name}/heartbeat/validatePath Parameters
agent_name*string
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
curl -X POST "https://loading/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"
}{
"error": "string"
}{
"error": "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"
}{
"error": "string"
}Empty
Request one advisory Heartbeat wake for an eligible session
POST
/api/agents/{agent_name}/heartbeat/wakePath Parameters
agent_name*string
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://loading/api/agents/string/heartbeat/wake" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "string", "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"
}
}{
"error": "string"
}{
"error": "string"
}{
"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"
}
}{
"error": "string"
}{
"error": "string"
}Empty
Inspect the resolved Soul read model for an agent definition
GET
/api/agents/{agent_name}/soulPath Parameters
agent_name*string
Agent name
Query Parameters
workspace_id?string
Workspace id
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://loading/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"
],
"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"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty
Delete SOUL.md through managed authoring
DELETE
/api/agents/{agent_name}/soulPath Parameters
agent_name*string
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 DELETE "https://loading/api/agents/string/soul" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "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"
],
"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"
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty
Create or replace SOUL.md through managed authoring
PUT
/api/agents/{agent_name}/soulPath Parameters
agent_name*string
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 PUT "https://loading/api/agents/string/soul" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "string", "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"
],
"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"
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "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"
}{
"error": "string"
}Empty
List managed SOUL.md authoring revisions
GET
/api/agents/{agent_name}/soul/historyPath Parameters
agent_name*string
Agent name
Query Parameters
workspace_id?string
Workspace id
limit?integer
Maximum number of revisions to return
Format
int32cursor?string
Revision cursor
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://loading/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"
}
]
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty
Rollback SOUL.md through managed authoring
POST
/api/agents/{agent_name}/soul/rollbackPath Parameters
agent_name*string
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://loading/api/agents/string/soul/rollback" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "string", "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"
],
"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"
}
}{
"error": "string"
}{
"error": "string"
}{
"error": "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"
}{
"error": "string"
}Empty
Validate a proposed Soul body for an agent definition
POST
/api/agents/{agent_name}/soul/validatePath Parameters
agent_name*string
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
curl -X POST "https://loading/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"
],
"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"
}{
"error": "string"
}{
"error": "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"
}{
"error": "string"
}Empty
Get one agent definition by name, optionally resolved for a workspace
GET
/api/agents/{name}Path Parameters
name*string
Agent name
Query Parameters
workspace?string
Workspace id, name, or path used to resolve a workspace-local agent
Response Body
application/json
application/json
application/json
curl -X GET "https://loading/api/agents/string"{
"agent": {
"command": "string",
"deny_tools": [
"string"
],
"mcp_servers": [
{
"args": [
"string"
],
"auth": {
"authorization_url": "string",
"client_id": "string",
"client_secret_ref": "string",
"issuer_url": "string",
"metadata_url": "string",
"revocation_url": "string",
"scopes": [
"string"
],
"token_url": "string",
"type": "string"
},
"command": "string",
"env": {
"property1": "string",
"property2": "string"
},
"name": "string",
"secret_env": {
"property1": "string",
"property2": "string"
},
"transport": "string",
"url": "string"
}
],
"model": "string",
"name": "string",
"permissions": "string",
"prompt": "string",
"provider": "string",
"tools": [
"string"
],
"toolsets": [
"string"
]
}
}{
"error": "string"
}{
"error": "string"
}Empty