API Reference

The xQR API lets you manage links, QR codes, analytics, assets, and workspaces programmatically. Every endpoint documented in this reference is available to Pro plan accounts and above.

Base URL

All API requests are made to:

https://xqr.co/api/v1

Note

The API is versioned via the URL path. The current (and only) stable version is v1. When a breaking change is introduced, a new version will be published and v1 will remain supported for at least 12 months. See the Versioning & Deprecation policy for details.

A machine-readable OpenAPI 3.1 specification is also available for import into Postman, Insomnia, or code generators.

Authentication

Authenticate every request by sending your API key in the Authorization header:

Authorization: Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped. Each endpoint requires a specific scope (e.g. links:read, qr:render). If the key does not include the required scope, the API returns 403 Forbidden.

Create and manage keys in Settings → Developers in the xQR dashboard.

Content Type

All request and response bodies use JSON. Set the Content-Type header on every request that includes a body:

Content-Type: application/json

The only exception is the QR render endpoint, which returns binary image data (image/svg+xml or image/png).

Response Envelope

Every JSON response is wrapped in a standard envelope:

{
  "data": { ... },
  "meta": {
    "request_id": "req_8f3a2b1c4d5e6f70",
    "rate_limit": {
      "limit": 600,
      "remaining": 594,
      "reset": 1742572800
    }
  }
}

Field	Type	Description
data	object | array	The requested resource or collection.
meta.request_id	string	Unique identifier for the request, useful for support tickets.
meta.rate_limit.limit	number	Maximum requests allowed in the current window.
meta.rate_limit.remaining	number	Requests remaining before throttling.
meta.rate_limit.reset	number	Unix timestamp (seconds) when the window resets.

Error responses follow the same envelope but replace data with an error object. See Error Handling for details.

Pagination

List endpoints accept two query parameters:

Parameter	Type	Default	Description
limit	integer	50	Number of items to return (1 – 200).
offset	integer	0	Number of items to skip.

The response meta includes pagination info when applicable:

{
  "data": [ ... ],
  "meta": {
    "request_id": "req_8f3a2b1c4d5e6f70",
    "total": 342,
    "limit": 50,
    "offset": 100,
    "rate_limit": { ... }
  }
}

Rate Limits

Default rate limits are 600 requests per minute per API key. The current usage is returned in every response via meta.rate_limit. When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

See Rate Limits for plan-specific quotas and best practices.