API policy
How the APIs change
The rules the Admin, Store and AI APIs follow today: where the version lives, how a replaced operation is marked, what a limited call returns and which error codes to switch on.
- 292 operations, 0 deprecated
- 1,335 operations, 1 deprecated
+ operationAdded inside v1 as a service gains it.deprecated: trueFlagged in the document; its summary names the replacement.same requestStill answers as before; move to the named operation.
Versioning
The version is in the path
The Admin and Store APIs carry their version in the path, /api/v1, and keep serving it unchanged when a new version arrives. The URL your code calls is the version it gets.
- Admin APIEvery documented path starts with /api/v1. Its OpenAPI document is at 1.0.0.
- Store APIEvery documented path starts with /api/v1. Its document is at 2.0: the document number follows edits to the document, the path is what your code pins.
- Versioning guidePinning v1 in client code, with a worked call.
# The version is part of the URL: this call is served by v1curl https://api.tanqory.com/v1/stores \ -H "Authorization: Bearer $TANQORY_API_KEY"Changes
What changes inside v1
Inside v1 the reference grows: operations and groups are added as the services gain them. When an operation is replaced inside v1, the old one stays in the document, is marked deprecated and names the operation to call instead.
- New operationsJoin their group in the reference.1,627 documented today
- Replaced operationsStay in v1 with deprecated set to true in the OpenAPI document, and their summary names the replacement.
- A new versionTakes a new path, and v1 keeps serving unchanged beside it.
{ "/api/v1/stores/{storeId}/members/transfer-ownership": { "post": { "summary": "Transfer store ownership (DEPRECATED, use /stores/:storeId/transfer-ownership)", "deprecated": true, "tags": [ "Store Members" ] } }}Deprecations
Deprecated operations
Every operation the OpenAPI documents mark deprecated, with the operation to call instead. A deprecated operation answers as it did before; the mark lives in the document and the reference, so check here before you build on one.
- In the referenceA Deprecated mark on the operation's own page and in its group.
- In the OpenAPI documentdeprecated: true on the operation itself, beside the summary that names its replacement.
- What to call insteadThe same request body, sent to the path the deprecated summary names.
| Operation | API | Use instead |
|---|---|---|
| POST/api/v1/stores/{storeId}/members/transfer-ownershipStore Members | Store API | POST/api/v1/stores/{storeId}/transfer-ownershipTransfer store ownership to another member |
Rate limits
Rate limits and retries
A call over a limit gets 429 Too Many Requests. Wait for Retry-After when it is sent, otherwise back off with jitter and try again; treat 503 the same way.
- Retry-AfterThe Admin API sends it in seconds on the 429 its request limits return, and repeats it as retry_after in the error body.
- rate_limit_exceededThe code a 429 carries in the error object. Switch on the code, never on the message.
- Backoff with jitterWith no Retry-After, wait longer after each try and add a random delay, so many clients do not retry at once.
HTTP/1.1 429 Too Many RequestsContent-Type: application/json; charset=utf-8Retry-After: 38{ "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "title": "Rate Limit Exceeded", "message": "ThrottlerException: Too Many Requests", "status": 429, "doc_url": "https://docs.tanqory.com/errors/rate_limit_exceeded", "request_id": "3f9d2c41b07e4a58a1c6e2d97b5f0a13", "instance": "/api/v1/auth/verify-email", "timestamp": "2026-10-08T09:41:07.312Z", "retry_after": 38 }}The answer the Admin API gives when one client sends a sixth email check inside a minute.
Errors
One error object, stable codes
Every error is one error object: a stable code to switch on, the status, the field at fault and a request ID to send to support.
- Error objecttype, code, title, message, status, doc_url, request_id, instance and timestamp on every error.
- Request IDQuote request_id when you contact support; it finds the call in our traces.
- Retry or fix429 and 503 are worth retrying; any other 4xx needs a changed request first.
| Status | code | Do this |
|---|---|---|
| 400 | validation_failed | Fix the fields listed in errors; do not resend the same body. |
| 401 | auth_token_invalid | Get a new token, then call again. |
| 403 | auth_insufficient_permissions | The token lacks access to this; do not retry. |
| 404 | resource_not_found | Check the ID and the store it belongs to. |
| 409 | resource_conflict | Read the current state before you try again. |
| 429 | rate_limit_exceeded | Wait for Retry-After, then retry. |
| 503 | server_service_unavailable | Retry after retry_after seconds when it is sent, otherwise back off. |
Terms
Terms that govern use
Use of the APIs is governed by the API License and Terms and the Terms of Service on the legal site. This page describes how the APIs behave; the terms are the agreement.
Build on v1 today
Open a store, create a key and make your first call. AI is part of every plan.
- Version pinned by the path
- Deprecations marked in the spec
- Retry-After in seconds on a 429