API Reference
Agents API
API surface for SOIT agent definitions, versions, releases, and execution-related views.
The agents API manages agent definitions and the versioned capability bindings that determine how an agent executes.
Prefix
/api/v1/agentsEndpoint families
| Method | Path | Purpose |
|---|---|---|
| POST / GET | / | Create agents; list with pagination |
| GET | /workbench, /workbench/items | Workbench summary views for the UI |
| GET | /capabilities | Capability catalog available for binding |
| GET / PUT / DELETE | /{agent_id} | Inspect, update, or delete an agent |
| POST / GET | /{agent_id}/versions | Create a draft version; list versions |
| GET | /{agent_id}/releases | Release ledger (publish and rollback history) |
| GET | /{agent_id}/bindings | Resolved capability bindings |
| POST | /{agent_id}/publish, /{agent_id}/rollback | Move the live release pointer |
| POST | /{agent_id}/execute, /{agent_id}/stream | Execute the published version (sync or streaming) |
| POST | /run | Direct agent run entry point |
Related prefixes
/api/v1/threads,/api/v1/responses— conversational execution/api/v1/runs,/api/v1/tasks— execution evidence
Notes
- Formal execution resolves the published version only; bindings come from the version spec, not from execute-payload overrides.
- Publish and rollback append to the release ledger — see Versioning and Release.