Agents

List all readable agent definitions, optionally resolved for a workspace

GET/api/agents

Query Parameters

workspace?string

Workspace id, name, or path used to resolve workspace-local agents

Response Body

`application/json`

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

{  "agents": [    {      "category_path": [        "string"      ],      "command": "string",      "definition_digest": "string",      "deny_tools": [        "string"      ],      "diagnostics": [        {          "error_kind": "string",          "message": "string",          "path": "string"        }      ],      "effective_runtime": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "sources": {          "model": "string",          "provider": "string",          "reasoning_effort": "string"        }      },      "mcp_servers": [        {          "args": [            "string"          ],          "auth": {            "authorization_url": "string",            "client_id": "string",            "client_secret_configured": true,            "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",      "origin": "global",      "permissions": "string",      "prompt": "string",      "provider": "string",      "reasoning_effort": "none",      "skills": {        "disabled": [          "string"        ]      },      "tools": [        "string"      ],      "toolsets": [        "string"      ],      "workspace_id": "string"    }  ]}

Create a global or workspace-local AGENT.md definition

POST/api/agents

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

agent*

scope*string

Value in

"workspace"
"global"

workspace?string

Response Body

`application/json`

curl -X POST "https://example.com/api/agents" \  -H "Content-Type: application/json" \  -d '{    "agent": {      "name": "string",      "prompt": "string"    },    "scope": "workspace"  }'

{  "agent": {    "category_path": [      "string"    ],    "command": "string",    "definition_digest": "string",    "deny_tools": [      "string"    ],    "diagnostics": [      {        "error_kind": "string",        "message": "string",        "path": "string"      }    ],    "effective_runtime": {      "model": "string",      "provider": "string",      "reasoning_effort": "none",      "sources": {        "model": "string",        "provider": "string",        "reasoning_effort": "string"      }    },    "mcp_servers": [      {        "args": [          "string"        ],        "auth": {          "authorization_url": "string",          "client_id": "string",          "client_secret_configured": true,          "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",    "origin": "global",    "permissions": "string",    "prompt": "string",    "provider": "string",    "reasoning_effort": "none",    "skills": {      "disabled": [        "string"      ]    },    "tools": [      "string"    ],    "toolsets": [      "string"    ],    "workspace_id": "string"  }}

List a filtered workspace agent fleet with exact session metrics

GET/api/agents/catalog

Query Parameters

workspace*string

Workspace id, name, or path

name?string

Exact agent name

q?string

Case-insensitive agent name or category search

category?string

Exact category path joined by slash separators

status?string

Agent session status

Value in

"active"
"idle"

cursor?string

Opaque cursor bound to workspace and filters

limit?integer

Agents per page (1-100; default 50)

Formatint32

Response Body

`application/json`

curl -X GET "https://example.com/api/agents/catalog?workspace=string"

{  "agents": [    {      "agent": {        "category_path": [          "string"        ],        "command": "string",        "definition_digest": "string",        "deny_tools": [          "string"        ],        "diagnostics": [          {            "error_kind": "string",            "message": "string",            "path": "string"          }        ],        "effective_runtime": {          "model": "string",          "provider": "string",          "reasoning_effort": "none",          "sources": {            "model": "string",            "provider": "string",            "reasoning_effort": "string"          }        },        "mcp_servers": [          {            "args": [              "string"            ],            "auth": {              "authorization_url": "string",              "client_id": "string",              "client_secret_configured": true,              "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",        "origin": "global",        "permissions": "string",        "prompt": "string",        "provider": "string",        "reasoning_effort": "none",        "skills": {          "disabled": [            "string"          ]        },        "tools": [          "string"        ],        "toolsets": [          "string"        ],        "workspace_id": "string"      },      "sessions": {        "active": 0,        "failed": 0,        "last_activity_at": "2019-08-24T14:15:22Z",        "runtime_seconds": 0,        "total": 0      }    }  ],  "facets": {    "active": 0,    "categories": [      "string"    ],    "idle": 0,    "total": 0  },  "page": {    "has_more": true,    "limit": 0,    "next_cursor": "string",    "total": 0  },  "sessions_available": true}

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`

curl -X GET "https://example.com/api/agents/string"

{  "agent": {    "category_path": [      "string"    ],    "command": "string",    "definition_digest": "string",    "deny_tools": [      "string"    ],    "diagnostics": [      {        "error_kind": "string",        "message": "string",        "path": "string"      }    ],    "effective_runtime": {      "model": "string",      "provider": "string",      "reasoning_effort": "none",      "sources": {        "model": "string",        "provider": "string",        "reasoning_effort": "string"      }    },    "mcp_servers": [      {        "args": [          "string"        ],        "auth": {          "authorization_url": "string",          "client_id": "string",          "client_secret_configured": true,          "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",    "origin": "global",    "permissions": "string",    "prompt": "string",    "provider": "string",    "reasoning_effort": "none",    "skills": {      "disabled": [        "string"      ]    },    "tools": [      "string"    ],    "toolsets": [      "string"    ],    "workspace_id": "string"  }}

Durably delete one effective authored agent definition

DELETE/api/agents/{name}

Path Parameters

name*string

Agent name

Query Parameters

workspace?string

Workspace id, name, or path used to resolve the effective definition

Response Body

`application/json`

curl -X DELETE "https://example.com/api/agents/string"

{  "name": "string",  "origin": "global",  "unshadowed_origin": "global"}

Replace one effective AGENT.md definition with digest CAS

PUT/api/agents/{name}

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

agent*

expected_digest*string

workspace?string

Response Body

`application/json`

curl -X PUT "https://example.com/api/agents/string" \  -H "Content-Type: application/json" \  -d '{    "agent": {      "name": "string",      "prompt": "string"    },    "expected_digest": "string"  }'

{  "agent": {    "category_path": [      "string"    ],    "command": "string",    "definition_digest": "string",    "deny_tools": [      "string"    ],    "diagnostics": [      {        "error_kind": "string",        "message": "string",        "path": "string"      }    ],    "effective_runtime": {      "model": "string",      "provider": "string",      "reasoning_effort": "none",      "sources": {        "model": "string",        "provider": "string",        "reasoning_effort": "string"      }    },    "mcp_servers": [      {        "args": [          "string"        ],        "auth": {          "authorization_url": "string",          "client_id": "string",          "client_secret_configured": true,          "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",    "origin": "global",    "permissions": "string",    "prompt": "string",    "provider": "string",    "reasoning_effort": "none",    "skills": {      "disabled": [        "string"      ]    },    "tools": [      "string"    ],    "toolsets": [      "string"    ],    "workspace_id": "string"  }}

Duplicate one effective authored agent definition server-side

POST/api/agents/{name}/duplicate

Path Parameters

name*string

Source agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

name*string

overrides?|null

scope?string

Value in

"workspace"
"global"

workspace?string

Response Body

`application/json`

curl -X POST "https://example.com/api/agents/string/duplicate" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "agent": {    "category_path": [      "string"    ],    "command": "string",    "definition_digest": "string",    "deny_tools": [      "string"    ],    "diagnostics": [      {        "error_kind": "string",        "message": "string",        "path": "string"      }    ],    "effective_runtime": {      "model": "string",      "provider": "string",      "reasoning_effort": "none",      "sources": {        "model": "string",        "provider": "string",        "reasoning_effort": "string"      }    },    "mcp_servers": [      {        "args": [          "string"        ],        "auth": {          "authorization_url": "string",          "client_id": "string",          "client_secret_configured": true,          "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",    "origin": "global",    "permissions": "string",    "prompt": "string",    "provider": "string",    "reasoning_effort": "none",    "skills": {      "disabled": [        "string"      ]    },    "tools": [      "string"    ],    "toolsets": [      "string"    ],    "workspace_id": "string"  }}

Inspect the resolved Heartbeat policy for an agent definition

GET/api/agents/{name}/heartbeat

Path Parameters

name*string

Agent name

Query Parameters

workspace_id?string

Workspace id

Response Body

`application/json`

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 HEARTBEAT.md through managed authoring

DELETE/api/agents/{name}/heartbeat

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_digest*string

workspace_id?string

Response Body

`application/json`

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"  }}

Create or replace HEARTBEAT.md through managed authoring

PUT/api/agents/{name}/heartbeat

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

body*string

expected_digest*string

idempotency_key?string

workspace_id?string

Response Body

`application/json`

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"  }}

List managed HEARTBEAT.md authoring revisions

GET/api/agents/{name}/heartbeat/history

Path Parameters

name*string

Agent name

Query Parameters

workspace_id?string

Workspace id

limit?integer

Maximum number of revisions to return

Formatint32

cursor?string

Revision cursor

Response Body

`application/json`

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"    }  ]}

Rollback HEARTBEAT.md through managed authoring

POST/api/agents/{name}/heartbeat/rollback

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_digest*string

idempotency_key?string

revision_id?string

target_digest?string

workspace_id?string

Response Body

`application/json`

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"  }}

Read Heartbeat policy status, wake state, and optional session health

GET/api/agents/{name}/heartbeat/status

Path Parameters

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`

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,    "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"  }}

Validate a proposed HEARTBEAT.md body

POST/api/agents/{name}/heartbeat/validate

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

body*string

workspace_id?string

Response Body

`application/json`

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"}

Request one advisory Heartbeat wake for an eligible session

POST/api/agents/{name}/heartbeat/wake

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

dry_run?boolean

idempotency_key?string

session_id*string

source*string

Value in

"scheduler"
"manual"
"harness_reentry"

workspace_id?string

Response Body

`application/json`

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"  }}

Inspect the resolved Soul read model for an agent definition

GET/api/agents/{name}/soul

Path Parameters

name*string

Agent name

Query Parameters

workspace_id?string

Workspace id

Response Body

`application/json`

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"    ],    "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"}

Delete SOUL.md through managed authoring

DELETE/api/agents/{name}/soul

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_digest*string

workspace_id?string

Response Body

`application/json`

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"      ],      "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"  }}

Create or replace SOUL.md through managed authoring

PUT/api/agents/{name}/soul

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

body*string

expected_digest*string

idempotency_key?string

workspace_id?string

Response Body

`application/json`

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"      ],      "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"  }}

List managed SOUL.md authoring revisions

GET/api/agents/{name}/soul/history

Path Parameters

name*string

Agent name

Query Parameters

workspace_id?string

Workspace id

limit?integer

Maximum number of revisions to return

Formatint32

cursor?string

Revision cursor

Response Body

`application/json`

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"    }  ]}

Rollback SOUL.md through managed authoring

POST/api/agents/{name}/soul/rollback

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_digest*string

idempotency_key?string

revision_id*string

workspace_id?string

Response Body

`application/json`

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"      ],      "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"  }}

Validate a proposed Soul body for an agent definition

POST/api/agents/{name}/soul/validate

Path Parameters

name*string

Agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

body?string

workspace_id?string

Response Body

`application/json`

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"    ],    "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"}

200application/json

500application/json

201application/json

400application/json

404application/json

409application/json

410application/json

422application/json

500application/json

503application/json

200application/json

400application/json

404application/json

410application/json

500application/json

503application/json

200application/json

404application/json

500application/json

200application/json

404application/json

410application/json

500application/json

503application/json

200application/json

400application/json

404application/json

409application/json

410application/json

422application/json

500application/json

503application/json

201application/json

400application/json

404application/json

409application/json

410application/json

422application/json

500application/json

503application/json

200application/json

403application/json

404application/json

422application/json

500application/json

200application/json

403application/json

404application/json

409application/json

422application/json

500application/json

200application/json

403application/json

404application/json

409application/json

422application/json

500application/json

200application/json

403application/json

404application/json

422application/json

500application/json

200application/json

403application/json

404application/json

409application/json

422application/json

500application/json

200application/json

403application/json

404application/json

422application/json

500application/json

200application/json

403application/json

404application/json

422application/json

500application/json

200application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`