> ## 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 conversation operations: list conversations, read one conversation, and claim it for takeover. 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**.

### List conversations

<Note>
  `GET /api/v1/conversations/`
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
        "contact_id": "contact_4d2f6a8c1e3b5d7f9a1c3e5b",
        "channel": "sms",
        "status": "open",
        "assigned_to": "usr_3f8a1c2b9d4e5f60718293a4b5c6d7e8"
      }
    ],
    "meta": {
      "request_id": "req_list",
      "timestamp": "2026-08-01T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

### Get a conversation

<Note>
  `GET /api/v1/conversations/{id}`
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
      "contact_id": "contact_4d2f6a8c1e3b5d7f9a1c3e5b",
      "channel": "sms",
      "status": "open",
      "agent_active": true
    },
    "meta": {
      "request_id": "req_conv",
      "timestamp": "2026-08-01T12:01:00.000Z"
    }
  }
  ```
</ResponseExample>

### Take over a conversation

<Note>
  `POST /api/v1/inbox/conversations/{id}/takeover/start`
</Note>

Claim the conversation so it stops routing to robots and routes to your session instead.

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "conversation_id": "conv_8b2c4d6e1f3a5b7c9d0e2f4a",
      "taken_over_by": "usr_3f8a1c2b9d4e5f60718293a4b5c6d7e8",
      "agent_active": false
    },
    "meta": {
      "request_id": "req_takeover",
      "timestamp": "2026-08-01T12:02:00.000Z"
    }
  }
  ```
</ResponseExample>

### Error envelope

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