Conventions

Authentication

Send Authorization: Bearer <key> on every request. Keys start with qk_. A missing or invalid key returns HTTP 401 with error code unauthorized or invalid_key.

Response envelope

Every response, success or error, has the same shape:

{
  "contract_version": "quoin-v2",
  "request_id": "cb06fdaa-cc25-4715-8b3b-a2d7d4c5b320",
  "operation": "search_properties",
  "status": "ok",
  "data": { },
  "error": null,
  "meta": { "served_at": "2026-09-10T02:17:42.045Z", "truncated": false },
  "provenance": { "source_refs": [], "sources": [] }
}

Field	Meaning
`status`	`ok`, `partial` (some items failed, see per-item `outcome`), or `error`
`data`	Operation result, `null` on error
`error`	`null` on success; otherwise `{ code, message, retryable, retry_after_seconds?, details? }`
`meta.truncated`	`true` when a bound was hit and more data exists
`meta.next_cursor`	Present when another page is available
`meta.warnings`	Optional human-readable notes
`provenance`	Optional list of `source_refs` and source descriptions for the facts returned

All field names are snake_case. Unknown fields in requests are rejected.

Identifiers and references

Prefix	What it is	Where it comes from
`qprop_…`	A tax account that the property reader supports	`entity_ref` and `property_ref` on those tax accounts
`qentity_…`	Every other canonical entity: parcels, addresses, units, and tax accounts without property-read support (mostly retired ones)	`entity_ref`
`qrel_…`	A relationship (edge)	`relationship_ref`
`qev1.i.…`, `qev1.r.…`	Canonical evidence for an identifier or relationship	`source_refs` on entities and edges
`dataset\|record\|field\|key`	Legacy field-level evidence, for example `itspe_current\|203150\|assessment.current.total_value\|04842250`	`source_refs` inside property sections

References are opaque. Do not parse them; store them and pass them back. A property_ref is present only when the entity is a tax account that the property reader supports; it always equals the entity_ref. Decide by the presence of property_ref, not by the prefix.

Idempotency

Send a unique Idempotency-Key header (1–256 characters) on every request, including GETs. The key identifies one logical request:

Situation	Result
Fresh key	Normal processing
Same key, same operation, completed request	HTTP 409 `request_replayed`, no charge
Same key, different API key or operation	HTTP 409 `request_id_mismatch`
Same key, same operation, different body	HTTP 409 `request_id_mismatch`; normalized input is compared
No key	The server generates one per request; you lose replay protection

The API does not return the original response on replay, and a lost response cannot be recovered through the key. Use a new key for new work and keep responses you need. Retention: a completed request’s key is blocked for as long as the account exists; there is no expiry. A key whose request failed and was not charged is released and may be reused.

Pagination

get_catalog, traverse_relationships and search_properties return meta.next_cursor when more results exist. Pass it back as cursor (query parameter for GET, body field for POST) with the same other parameters. Cursors are signed, bound to your account and to the request they came from, and expire after 15 minutes. If the published data changes between pages, the next request returns HTTP 409 cursor_generation_changed; restart without a cursor.

Limits

Limit	Value
Requests per key	6,000 successful calls per rolling 60 seconds; HTTP 429 `rate_limited` with `retry_after_seconds`
Request body	256 KiB; HTTP 413 `request_too_large`
Response page	256 KiB; arrays are shortened and `meta.truncated` is set
Request deadline	12 seconds; HTTP 503 `query_timeout`, not charged
Page size	1–100 items, default 20

Billing headers

Successful responses include your account position after the call:

Header	Meaning
`X-Quoin-Price-Micro-USD`	Price of this call in micro-dollars (`50000` = $0.05)
`X-Quoin-Balance-Micro-USD`	Remaining welcome credit
`X-Quoin-Held-Micro-USD`	Outstanding reserved credit; zero after settlement
`X-Quoin-Rate-Version`	Rate card in effect, currently `portal-2026-09`
`X-Quoin-Calls-30d`	Successful billable calls in the last 30 days

You are charged only when a paid operation completes with status ok or partial. Invalid requests, refused requests and Quoin-side failures are free. When welcome credit cannot cover a call and no card is saved, you receive HTTP 402 insufficient_balance. Suspended accounts cannot make calls.

Get started

Using the API

Authentication

Response envelope

Identifiers and references

Idempotency

Limits

Billing headers

​Authentication

​Response envelope

​Identifiers and references

​Idempotency

​Pagination

​Limits

​Billing headers

Authentication

Response envelope

Identifiers and references

Idempotency

Pagination

Limits

Billing headers