Skip to main content

​
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) or an OAuth 2.1 access token. Each endpoint’s required permission is listed under its Authorizations and in 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.
  • File uploads use multipart/form-data (e.g. Upload a document); 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; 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) 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.

​
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 and Work with artifacts.