# Response Formats

All API responses follow a consistent structure for predictability and ease of parsing. The platform supports JSON as the primary format with optional XML support for legacy integrations.

## JSON Response Structure

Standard response envelope:

```json
{
  "data": { /* the actual response data */ },
  "meta": {
    "timestamp": "2026-02-18T12:34:56Z",
    "request_id": "req_abc123",
    "version": "2.0"
  },
  "status": "success"
}
```

**data**: The actual requested resource(s) or operation result.

**meta**: Metadata about the response (timestamp, request ID, API version).

**status**: "success" for successful requests, "error" for failures (rarely used with appropriate HTTP status codes).

## Collection Responses

List endpoints return collections with pagination metadata:

```json
{
  "data": [
    {"id": "user_1", "name": "Alice"},
    {"id": "user_2", "name": "Bob"}
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "pages": 3
  },
  "meta": { /* ... */ }
}
```

## Error Responses

Error responses follow the same structure:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid parameter: status",
    "details": [
      {
        "field": "status",
        "issue": "Unknown status value 'pending'. Expected: active, inactive, archived"
      }
    ]
  },
  "meta": { /* ... */ },
  "status": "error"
}
```

Errors use HTTP status codes (400, 401, 404, etc.) matching the error type.

## Nested Resources

Related resources can be embedded or referenced:

Referenced (default):

```json
{
  "data": {
    "id": "order_123",
    "user_id": "user_456",
    "status": "completed"
  }
}
```

Embedded (with `expand` parameter):

```json
{
  "data": {
    "id": "order_123",
    "user": {
      "id": "user_456",
      "name": "Alice",
      "email": "alice@example.com"
    },
    "status": "completed"
  }
}
```

## Content Negotiation

Specify desired response format via Accept header:

```
Accept: application/json  // JSON (default)
Accept: application/xml   // XML (legacy support)
```

The API returns the requested format if supported. Default is JSON.

## Field Formatting

**Numbers**: Floats include decimal point; integers may be strings for large numbers to avoid precision loss in JavaScript.

```json
{
  "price": 19.99,
  "user_id": "user_9007199254740991"  // String to preserve precision
}
```

**Dates**: ISO 8601 format with UTC timezone:

```json
{
  "created_at": "2026-02-18T12:34:56Z",
  "updated_at": "2026-02-18T12:35:10.123Z"  // With milliseconds
}
```

**Null values**: Explicitly represented as `null`:

```json
{
  "id": "user_123",
  "phone": null
}
```

Omitted fields indicate "no value" in requests; in responses, null values are always explicit.

## Binary and File Responses

File downloads return binary content with appropriate headers:

```
GET /exports/report.csv
Content-Type: text/csv
Content-Disposition: attachment; filename="report.csv"
```

The response body is the file content, not JSON.

## Streaming Responses

For large datasets, streaming responses are available:

```
GET /events/stream?start=2026-02-01
Content-Type: application/x-ndjson

{"id": "event_1", "timestamp": "2026-02-01T00:00:00Z"}
{"id": "event_2", "timestamp": "2026-02-01T00:00:01Z"}
...
```

NDJSON (newline-delimited JSON) allows processing large results without loading everything into memory.

## Response Size Optimization

Use `fields` query parameter to reduce response size:

```
GET /users?fields=id,name,email
```

Returns only specified fields, reducing bandwidth.

## Caching Headers

Responses include cache control headers:

```
Cache-Control: public, max-age=300
ETag: "abc123def456"
Last-Modified: Wed, 18 Feb 2026 12:00:00 GMT
```

Clients can use these for efficient caching and conditional requests.

## Content Encoding

Responses are compressed when beneficial:

```
Content-Encoding: gzip
```

Most HTTP clients handle decompression automatically.