Every successful response uses one envelope:

```json
{
  "data": { },
  "meta": { }
}
```

- `data` is the payload (an object, an array, or a scalar).
- `meta` is present for paginated or attributed responses (pagination, source attribution, cache info).

Errors use:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown catalog id"
  }
}
```

## Headers

| Header | Direction | Meaning |
| --- | --- | --- |
| `Authorization: Bearer <key>` | request | The credential. |
| `X-ToolRing-Credits` | response | Credits actually charged for this call; `0` when nothing was charged. |
| `X-ToolRing-Cache` | response | `hit` or `miss`. |
| `X-ToolRing-Cache-Age` | response | Age of a cached answer, in seconds. |
| `X-ToolRing-Max-Age` | request | Caps the cache TTL for this call; `0` means do not cache. |
| `X-ToolRing-Tag` | request | A `k=v` metadata bag; `customer=<id>` attributes spend to a per-tag budget. |
| `X-ToolRing-Capability`, `-Route`, `-Source`, `-Failover` | response | Which job, endpoint and source answered a routed `toolring.<capability>` call. |

## Dates

Dates use ISO 8601: `YYYY-MM-DD` for dates, `YYYY-MM-DDTHH:mm:ssZ` for timestamps.