REST API

Every SDK method maps to an HTTP endpoint. Use the REST surface directly from any language or runtime. All endpoints require a bearer token and are tenant-scoped by the API key (or explicit X-Tenant-ID header for account-scoped keys).

Base URL

https://api.veroagents.com

Authentication

Authorization: Bearer sk_live_...
Content-Type:  application/json
X-Tenant-ID:   tnt_...   (optional, account-scoped keys only)

Agents

MethodPathDescription
GET/v1/agentsList agents
POST/v1/agentsCreate agent
GET/v1/agents/:idGet agent
PATCH/v1/agents/:idUpdate agent
DELETE/v1/agents/:idDelete agent
POST/v1/agents/:id/triggerTrigger a run
GET/v1/agents/:id/filesList workspace files
GET/v1/agents/:id/files/:nameRead file
PUT/v1/agents/:id/files/:nameWrite file
DELETE/v1/agents/:id/files/:nameDelete file
GET/v1/agents/rolesList job roles

Runs

MethodPathDescription
GET/v1/agents/runsList runs
GET/v1/agents/runs/:idGet run
POST/v1/agents/runs/:id/cancelCancel run
GET/v1/agents/runs/:id/eventsSSE event stream

Trigger example

bash
curl -X POST https://api.veroagents.com/v1/agents/coordinator/trigger \
  -H "Authorization: Bearer $VERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "call_8291",
    "sender_id":       "david-cohen",
    "message":         "I need help with my denied claim"
  }'

# => { "run_id": "run_01h...", "status": "accepted" }

SSE stream example

bash
curl -N \
  -H "Authorization: Bearer $VERO_API_KEY" \
  -H "Accept: text/event-stream" \
  https://api.veroagents.com/v1/agents/runs/run_01h.../events

Brain

MethodPathDescription
POST/v1/brain/:agentIdWrite entry
GET/v1/brain/:agentId/:scope/:keyRead by key
DELETE/v1/brain/:agentId/:scope/:keyDelete entry
GET/v1/brain/:agentId/queryHybrid search + budgeted context
GET/v1/brain/:agentId/subscribeSSE subscription

Sandcastle

MethodPathDescription
POST/v1/sandcastleCreate & boot VM
GET/v1/sandcastleList VMs
GET/v1/sandcastle/:idGet VM
DELETE/v1/sandcastle/:idDestroy VM
POST/v1/sandcastle/:id/execRun one-shot shell

Errors

All errors return a JSON body:

json
{
  "error": {
    "code":    "not_found",
    "message": "Agent agent_xxx not found",
    "details": {}
  }
}

Common codes:

  • 401 authentication_error — missing / invalid API key
  • 403 authorization_error — key not authorized for this resource
  • 404 not_found — resource does not exist
  • 422 validation_error — bad request body
  • 429 rate_limit — respect Retry-After
  • 5xx server_error — retry with backoff