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

# API conventions

> Base URL, versioning, data formats, IDs, and the patterns shared across every HQ endpoint.

## Base URL & transport

All requests go to `https://api.hq.zone` over HTTPS; plain HTTP is redirected to HTTPS.

## Versioning

Every path carries a `/v1/` prefix (e.g. `/v1/api/conversations`). Backwards-incompatible changes ship under a new prefix; additive changes — new endpoints, new optional request fields, new response fields — can appear within `v1`, so write clients that **ignore unknown fields**.

## Authentication

Send a bearer token on every request: `Authorization: Bearer hq_pat_...` (a [personal access token](/get-started/authentication)) or an OAuth 2.1 access token. Each endpoint's required permission is listed under its **Authorizations** and in [Scopes](/api/scopes).

## Content types

* Most endpoints accept and return **`application/json`**.
* The OAuth `token`/`introspect`/`revoke` endpoints accept **`application/x-www-form-urlencoded`** (or JSON) — see the [OAuth guide](/guides/oauth).
* File uploads use **`multipart/form-data`** (e.g. [Upload a document](/api-reference/documents/upload-multipart)); some take base64 in a JSON field.
* File downloads return **raw bytes** with the stored `Content-Type`, not JSON.

## Identifiers & timestamps

* Resource IDs are **UUIDs**.
* Timestamps are **RFC 3339 / ISO 8601** strings in UTC (e.g. `2026-06-10T09:14:00Z`).

## Idempotency

Endpoints that start work accept an idempotency token so retries are safe. For turns, pass `idempotency_key` in the [message body](/api-reference/conversations/post-message); re-sending the same key on the same conversation returns the original turn instead of starting a duplicate (deduplicated for 24 hours).

## Pagination

List endpoints that can grow are bounded. Where paging is supported (e.g. [List activity](/api-reference/admin/list-activity)) use `limit` (1–200, default 50), `offset`, and `sort` (`recent` default, or `oldest`). Other list endpoints return a capped, newest-first set (artifacts, for example, cap at 500).

## Errors

Failures return the JSON body `{ "error": "<message>" }` with a standard HTTP status — see [Errors](/api/errors).

## Realtime & binary

Conversation turns stream over **Server-Sent Events**, and file endpoints return **binary** — neither maps onto a plain JSON client. Handle them as shown in [Stream a chat](/guides/streaming-chat) and [Work with artifacts](/guides/artifacts).