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

# Requests and responses

> Use the REST base URL, JSON envelopes, request IDs, and nullable fields correctly.

## Base URL and media type

REST v1 operations use `https://api.qoory.ai/v1`. Send JSON request bodies
with `Content-Type: application/json` and request JSON responses.

## Success envelope

Successful operations return a stable envelope:

```json theme={null}
{
  "data": {},
  "meta": {
    "request_id": "req_example_12345",
    "credits_used": 1,
    "credits_remaining": 19,
    "rate_limit": {
      "limit": 30,
      "remaining": 29,
      "reset_at": "2026-07-18T07:00:00.000Z",
      "tier": "free"
    }
  }
}
```

`request_id` is always present. Credit and rate-limit values are present when
that stage of request processing ran.

## Response headers

| Header                      | Meaning                                              |
| --------------------------- | ---------------------------------------------------- |
| `x-qoory-request-id`        | Public-safe identifier for support and tracing.      |
| `x-qoory-credits-used`      | Credits charged by the operation.                    |
| `x-qoory-credits-remaining` | Remaining account balance after the request.         |
| `x-qoory-rate-limit`        | JSON rate-limit metadata matching the response body. |

You may send a public-safe `x-request-id` containing 8 to 96 letters, numbers,
underscores, periods, colons, or hyphens. Qoory replaces malformed values.

## Nullable and omitted values

Treat `null` as unavailable, unresolved, or not applicable according to the
schema. Do not coerce it to zero or an empty string. Unknown object properties
are not part of the contract; generate types from OpenAPI and tolerate additive
fields within the same API version.

Timestamps use ISO 8601 date-time strings. Market observations and publication
times describe different events, so keep the field name with the value.