API Reference
The One Agents API provides full programmatic access to agent management, execution monitoring, approval workflows, templates, and credit tracking.
Base URL: https://api.theoneagents.app
All endpoints require authentication via Hub SSO JWT (from the Hub session cookie) or an X-Integration-Key service header for server-to-server calls.
Agents
List Agents
GET /api/agents
Returns all agents for the authenticated org, including system agents visible to the org. System agents have org_id: "system" and type: "system".
Query parameters:
status— Filter by status:active,paused,draft,errortype— Filter by type:system,template,custom,clonedcategory— Filter by category
Response:
{
"agents": [
{
"id": "agent_system_dispatch",
"org_id": "system",
"name": "Dispatch Agent",
"type": "system",
"status": "active",
"category": "service_desk",
"stats": {
"total_runs": 1247,
"success_rate": 0.97,
"avg_duration_ms": 1820,
"last_run_at": "2026-03-09T14:23:01Z",
"credits_used_this_month": 8340
}
}
],
"total": 6
}
Create Agent
POST /api/agents
Creates a new custom agent in draft status.
Request body:
{
"name": "P1 Escalation Notify",
"description": "SMS notify senior technicians when a ticket is escalated to P1",
"category": "service_desk",
"trigger": {
"type": "bus_event",
"event_type": "ticket.escalated",
"source_product": "psa",
"filters": [
{ "field": "escalated_to", "operator": "eq", "value": "p1" }
]
},
"conditions": [],
"steps": [
{
"type": "notification",
"id": "notify_senior",
"channel": "sms",
"recipients": ["+15551234567"],
"body": "P1 escalation: {{event_payload.ticket_id}}"
}
],
"conflict_behavior": "additive",
"client_scope": "all"
}
Response: Returns the created agent object with status: "draft".
Get Agent
GET /api/agents/:id
Returns the full agent definition including all steps, conditions, and stats.
Update Agent
PUT /api/agents/:id
Updates an agent definition. Pass only the fields you want to change. To activate a draft agent, include "status": "active".
type: "system") cannot be updated. A 403 Forbidden is returned if you attempt to modify a system agent. Clone it first and update the clone.Delete Agent
DELETE /api/agents/:id
Deletes a custom agent. Active executions are cancelled first. System agents cannot be deleted — use PUT /api/agents/:id with {"status": "paused"} to disable a system agent for your org.
Returns 204 No Content on success.
Executions
List Executions
GET /api/executions
Returns executions for the authenticated org, newest first.
Query parameters:
agent_id— Filter to a specific agentstatus— Filter by status:pending,running,completed,failed,cancelled,waiting_approvalfrom— ISO 8601 start date (e.g.,2026-03-01T00:00:00Z)to— ISO 8601 end datelimit— Default 50, max 200
Response:
{
"executions": [
{
"id": "exec_01HXYZ",
"agent_id": "agent_system_dispatch",
"status": "completed",
"credits_used": 20,
"created_at": "2026-03-09T14:23:01Z",
"completed_at": "2026-03-09T14:23:03Z"
}
],
"total": 842,
"next_cursor": "exec_01HABC"
}
Get Execution Detail
GET /api/executions/:id
Returns the full execution record including the trigger event and complete step-by-step trace.
Response:
{
"id": "exec_01HXYZ",
"agent_id": "agent_system_dispatch",
"trigger_event": {
"id": "evt_01HXYZ",
"event_type": "ticket.created",
"source_product": "psa",
"payload": { "ticket_id": "tkt_abc123", "priority": "p2" }
},
"status": "completed",
"steps": [
{
"step_id": "classify_ticket",
"step_type": "ai_reason",
"status": "completed",
"output": { "priority": "p1", "category": "security" },
"credits_used": 20,
"duration_ms": 843,
"started_at": "2026-03-09T14:23:01Z",
"completed_at": "2026-03-09T14:23:02Z"
}
],
"credits_used": 20,
"created_at": "2026-03-09T14:23:01Z",
"completed_at": "2026-03-09T14:23:03Z"
}
Cancel Execution
POST /api/executions/:id/cancel
Cancels a running or waiting execution. Pending steps are skipped. Approval gates are automatically denied.
Returns the updated execution record with status: "cancelled".
Retry Execution
POST /api/executions/:id/retry
Re-executes the agent from the beginning using the original trigger event. Credits are consumed again for all AI steps.
Only valid for executions in failed or cancelled status.
Approvals
List Pending Approvals
GET /api/approvals?status=pending
Returns all open approval gates waiting for a decision.
Query parameters:
status—pending,approved,denied,expired
Response:
{
"approvals": [
{
"id": "appr_01HXYZ",
"execution_id": "exec_01HABC",
"agent_id": "agent_security_response",
"step_id": "confirm_isolation",
"message": "Confirm device isolation for WORKSTATION-01 (Client: Acme Corp). Ransomware confidence: 0.97",
"status": "pending",
"expires_at": "2026-03-09T16:23:01Z",
"created_at": "2026-03-09T14:23:01Z"
}
]
}
Submit Approval Decision
POST /api/approvals/:id/decision
Approve or deny a pending approval gate. The execution resumes immediately on approval, or terminates on denial.
Request body:
{
"decision": "approved",
"note": "Confirmed ransomware — isolation authorized"
}
decision must be "approved" or "denied".
Response: Returns the updated approval record with decided_by and decided_at set.
Templates
List Templates
GET /api/templates
Returns all available agent templates, organized by category.
Query parameters:
category— Filter by category:operations,security,billing,hr,custom
Response:
{
"templates": [
{
"id": "tmpl_sla_escalation",
"category": "operations",
"name": "SLA Escalation",
"description": "Notifies the assigned technician and their manager 30 minutes before SLA breach",
"version": "1.0.0",
"trigger": { "type": "bus_event", "event_type": "ticket.sla_warning", "source_product": "psa" }
}
]
}
Clone Template
POST /api/templates/:id/clone
Clones a template to your organization as a draft agent. Returns the new agent object ready for customization.
Request body (optional):
{
"name": "My SLA Escalation"
}
If name is not provided, the template name is used.
Event Catalog
List Event Catalog
GET /api/events
Returns all registered event types.
Query parameters:
source_product— Filter to a specific product (e.g.,psa,defend,rmm)category— Filter by category:service_desk,security,operations,finance,compliance,communications,onboarding,client_success
Response:
{
"events": [
{
"id": "psa:ticket.created",
"source_product": "psa",
"event_type": "ticket.created",
"display_name": "Ticket Created",
"description": "Fires when a new PSA ticket is opened by a client or technician",
"filterable_fields": [
{ "path": "priority", "label": "Priority", "type": "enum", "enum_values": ["p1", "p2", "p3", "p4"] }
],
"sample_payload": { "ticket_id": "tkt_abc123", "priority": "p2" }
}
]
}
Credits
Get Current Month Usage
GET /api/credits
Returns credit usage for the current calendar month.
Response:
{
"org_id": "org_abc123",
"month": "2026-03",
"total_used": 11340,
"allocation": 100000,
"remaining": 88660,
"by_agent": {
"agent_system_dispatch": 8200,
"agent_system_guardian": 2800,
"agent_system_advisor": 140,
"agent_01HXYZ": 200
},
"by_model": {
"quick": 140,
"standard": 11000,
"premium": 200,
"expert": 0
},
"updated_at": "2026-03-09T15:00:00Z"
}
Get Credit History
GET /api/credits/history
Returns monthly credit usage for the past 12 months.
Response:
{
"history": [
{ "month": "2026-03", "total_used": 11340, "allocation": 100000 },
{ "month": "2026-02", "total_used": 9870, "allocation": 100000 },
{ "month": "2026-01", "total_used": 8420, "allocation": 100000 }
]
}
Error Responses
All endpoints return standard error objects:
{
"error": "agent_not_found",
"message": "Agent agent_01HXYZ not found in org org_abc123",
"status": 404
}
Common error codes:
| Code | Status | Description |
|---|---|---|
unauthorized | 401 | Missing or invalid authentication |
forbidden | 403 | Insufficient permissions (e.g., modifying system agent) |
agent_not_found | 404 | Agent does not exist in this org |
execution_not_found | 404 | Execution does not exist or belongs to another org |
credit_insufficient | 402 | Org has no remaining credit allocation |
agent_limit_reached | 429 | Active agent count at subscription tier limit |
invalid_agent_config | 400 | Agent definition failed validation |