Worked request and response samples

Copy a request body as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit’s { error, meta } envelope, shown once below under Error envelope.

Create an agent

POST /api/v1/agents/

Only name is required. Everything else falls back to tenant defaults, so a minimal body is enough to spin up a draft agent. Request

{
  "name": "After-hours support",
  "type": "chatbot",
  "system_prompt": "Answer from the knowledge base; escalate billing questions.",
  "tools": ["kb-search", "handoff"]
}

{
  "data": {
    "id": "agt_3f6a81c2d4e5471a9b0c2d5e",
    "name": "After-hours support",
    "type": "chatbot",
    "status": "draft"
  },
  "meta": {
    "request_id": "req_agt_create",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Send a chat message

POST /api/v1/agents/{id}/chat

Request

{
  "message": "How do I reset my password?",
  "conversation_id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a"
}

{
  "data": {
    "conversation_id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
    "reply": "Open Settings > Security, then choose Reset password.",
    "tokens_used": 412
  },
  "meta": {
    "request_id": "req_agt_chat",
    "timestamp": "2026-08-01T12:01:00.000Z"
  }
}

List an agent’s recent tool calls

GET /api/v1/agents/{id}/tool-history

Use a different agt_ id for each sample — the examples below substitute agt_3f6a81c2d4e5471a9b0c2d5e.

{
  "data": [
    {
      "tool": "kb-search",
      "status": "success",
      "duration_ms": 86,
      "started_at": "2026-08-01T11:59:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_agt_tools",
    "timestamp": "2026-08-01T11:59:02.000Z"
  }
}

Error envelope

Most write failures return 422 VALIDATION_ERROR with the offending field named in message.

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "name: Required"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

API Reference

All Endpoints

Worked request and response samples