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

# Request/Response Conventions

> Standard conventions for API requests and responses

All responses from the Turris API follow a consistent structure to facilitate integration and debugging.

## Top-Level Structure

Each response, whether successful or erroneous, includes a `requestId` field which can be used for tracing and support purposes. Response payloads are returned directly at the top level and are not wrapped in a `data` object.

```json theme={null}
{
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "timestamp": "2023-10-16T12:34:56Z",
  ...responseData
}
```

## Date Format

All date and timestamp fields are returned in **ISO 8601 format**:

```
2025-03-17T10:15:45.000Z
```

This is consistent with standard MongoDB date representations.

## Identifier Format

All unique identifiers (e.g., `agencyId`, `agentId`, `policyId`) are returned as **MongoDB ObjectId strings**:

```
5f1e88b5b8f1c8001cfb7d9a
```

## Request Headers

### Required Headers

| Header          | Value              | Description                          |
| --------------- | ------------------ | ------------------------------------ |
| `Content-Type`  | `application/json` | Required for POST/PUT/PATCH requests |
| `Authorization` | `Bearer <token>`   | OAuth JWT token                      |

### Alternative Authentication

| Header                      | Value     | Description                                    |
| --------------------------- | --------- | ---------------------------------------------- |
| `x-restricted-access-token` | `<token>` | Restricted access token (alternative to OAuth) |

### Optional Headers

| Header              | Value   | Description                    |
| ------------------- | ------- | ------------------------------ |
| `idempotency-key`   | UUID v4 | For idempotent operations      |
| `x-idempotency-key` | UUID v4 | Alternative idempotency header |

## Success Responses

Successful responses return the data directly with standard metadata:

```json theme={null}
{
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "statusCode": 200,
  "timestamp": "2023-10-16T12:34:56Z",
  "data": {
    // Response payload
  }
}
```

## Error Responses

Error responses follow a standardized schema. For detailed information about error handling, refer to the [Error Handling](/guides/error-handling) guide.

```json theme={null}
{
  "statusCode": 400,
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "errorType": "invalid_input",
  "errorMessage": ["Field 'email' is required"],
  "timestamp": "2023-10-16T12:34:56Z"
}
```

## HTTP Status Codes

| Code  | Meaning                                 |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `201` | Created                                 |
| `400` | Bad Request - Invalid input             |
| `401` | Unauthorized - Invalid or expired token |
| `403` | Forbidden - Insufficient permissions    |
| `404` | Not Found - Resource doesn't exist      |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error           |