> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Worked request and response samples

> Worked samples for the most-used agent operations: create an agent, send a chat message, and read its recent tool calls. Each sample shows the request, the success envelope, and the error envelope to expect.

## 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

<Note>
  `POST /api/v1/agents/`
</Note>

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

**Request**

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

<ResponseExample>
  ```json 201 theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Send a chat message

<Note>
  `POST /api/v1/agents/{id}/chat`
</Note>

**Request**

```json theme={null}
{
  "message": "How do I reset my password?",
  "conversation_id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a"
}
```

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### List an agent's recent tool calls

<Note>
  `GET /api/v1/agents/{id}/tool-history`
</Note>

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Error envelope

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

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