API Conventions
OpenAPI document
The full contract — every operation, parameter, schema and error — is an OpenAPI 3.1 document, served without a key:
https://api.apptonomy.ai/v1/openapi.json
Load it into Swagger UI, Postman, Insomnia or a code generator. Field descriptions in this page and the document come from the same source.
Conventions
- Identifiers are opaque strings of letters, digits,
_and-, up to 128 characters. Don’t parse them. - Times are RFC 3339 in UTC (
2026-11-16T09:30:00.000Z). Dates (2026-11-16) are store reporting days. - Scores are 0–100. Rates such as
conversionRateare fractions between 0 and 1, never percent. - Every field is always present, and
nullwhen it has no value — the one exception being a personal field your key’s scopes leave out. - Ignore what you don’t know. New fields can appear in any response, and enums marked extensible in the OpenAPI document can gain values. Write clients that ignore unknown fields and handle an unknown enum value.
- A record you can’t see answers like one that doesn’t exist. An id from another organization answers
404 not_found, exactly as a missing id does.
Responses
A single resource:
{
"data": { "id": "…", "name": "…" },
"meta": { "requestId": "req_…", "apiVersion": "v1", "freshness": null, "warnings": [] }
}
A recommendation, score or impact result adds a provenance block beside data.
A list:
{
"data": [ … ],
"pagination": { "limit": 25, "nextCursor": "…", "hasMore": true },
"meta": { "requestId": "req_…", "apiVersion": "v1", "freshness": null, "warnings": [] }
}
meta.requestId is also sent as the X-Request-Id header. Quote it when you contact support about a request.
Pagination
Lists are paged with a cursor. limit is 1 to 100 (default 25). When pagination.hasMore is true, request the next page with the same query plus cursor=<pagination.nextCursor>. On the last page nextCursor is null.
- Each list’s order is fixed and stated in the OpenAPI document (audits and scores newest first, projects by name). For data that doesn’t change while you page, following the cursor returns every item once. A cursor is not a snapshot: a record that changes between two pages (a project renamed, a new audit) can move across the page boundary and show up twice or not at all. To keep a complete copy, merge pages by
idand re-read periodically. - A cursor is tied to the query it came from. Reusing it with different filters, or sending a malformed or expired one, answers
400 invalid_cursor— start again from the first page. - A page can hold fewer than
limititems whilehasMoreis stilltrue. Keep following the cursor untilhasMoreisfalse.
Freshness
meta.freshness is null when the data was read live. For data refreshed in the background — store analytics — it says how current the answer is:
| Field | Meaning |
|---|---|
asOf | When the data was last refreshed |
consistency | strong or eventual |
stale | true when the data is older than its normal refresh cycle |
nextUpdateExpectedAt | When the next refresh is due |
Store analytics is read from App Store Connect and Google Play Console once a day (06:00 UTC) and is stale after 36 hours. meta.warnings explains anything partial:
| Warning | Meaning |
|---|---|
partial_result | Part of the answer isn’t final: an audit still running, or a store whose data stops before to |
stale_data | The data is older than its refresh cycle |
fields_omitted | Fields left out because the key lacks a scope; fields and requiredScopes name them |
Provenance
A recommendation, a score and an impact result each come with a provenance block: one claim per statement, each saying what kind of claim it is and the sources it rests on.
| Claim kind | Meaning |
|---|---|
measured | Read directly from a source, such as the store listing or store analytics |
derived | Calculated from measured values |
interpretation | A judgment drawn from the evidence by Apptonomy’s AI analysis, with the evidence it rests on |
unavailable | The evidence exists but your key can’t see it |
Each source names its type (audit, audit_finding, listing_snapshot, review, …), its id and when it was observed. A source your key isn’t allowed to read is dropped; a claim left with no evidence you may see is returned as unavailable with its statement withheld. For example, a key without audits:read sees a recommendation but not the audit evidence behind it. A recommendation also lists its evidence — the specific values the audit observed.
Errors
Every error has the same shape:
{
"error": {
"code": "invalid_request",
"message": "The request has invalid parameters.",
"requestId": "req_…",
"retryable": false,
"details": [{ "field": "limit", "code": "out_of_range", "message": "…" }]
}
}
Branch on code, not on message; messages can be reworded. retryable says whether the same request can succeed later.
| Code | Status | Retry? | Meaning |
|---|---|---|---|
invalid_request | 400 | no | A parameter is missing, malformed or out of range; details names each one |
invalid_cursor | 400 | no | The cursor is malformed, expired, or was issued for a different query |
unauthenticated | 401 | no | No credential, or a malformed one, was sent |
invalid_credential | 401 | no | The key is unknown, revoked or expired |
forbidden | 403 | no | The organization turned API keys off, or Apptonomy has paused programmatic access; the message says which |
insufficient_scope | 403 | no | The key lacks the scope this operation needs |
entitlement_required | 403 | no | The organization’s plan doesn’t include this |
organization_suspended | 403 | no | The organization is suspended |
operation_not_enabled | 403 | no | The operation isn’t available yet |
not_found | 404 | no | The resource doesn’t exist, or isn’t in your organization |
method_not_allowed | 405 | no | The path doesn’t take this method; Allow lists the ones it does |
not_acceptable | 406 | no | The Accept header excludes application/json |
idempotency_conflict | 409 | no | The Idempotency-Key was already used with a different request |
conflict | 409 | no | An action named work already running, a recommendation that isn’t accepted or can’t move to the state asked for, or a draft or recommendation that changed since you read it; nothing was queued |
rate_limited | 429 | yes | A per-minute limit was exceeded; wait Retry-After seconds |
quota_exceeded | 429 | yes | The organization’s daily quota is spent; Retry-After is the time to its reset |
internal_error | 500 | yes | An unexpected failure; retry with backoff and quote the request id to support |
service_unavailable | 503 | yes | A service the request needs is unavailable; wait Retry-After seconds |
For a retryable error, wait for Retry-After when it’s present, otherwise back off exponentially, doubling the wait each time, and give up after a few attempts.
Rate limits and quotas
Each organization has per-minute request limits — for the organization, for each key, and for each key on each operation — and a daily quota, all set by its plan. API keys and AI client connections of one organization share the organization’s limits, so no single key can use all of them.
Every successful response, and every 429, tells you where you stand:
| Header | Example | Meaning |
|---|---|---|
RateLimit | "operation-minute";r=0;t=50 | The limit closest to running out: r requests or units remain, and it resets in t seconds |
RateLimit-Policy | "org-minute";q=60;w=60, … | Every limit the request counted against: q allowed per w seconds |
Retry-After | 50 | On 429 and 503: seconds to wait before retrying |
The daily quota counts cost units rather than requests. A single resource costs 1 unit and a list 1 unit per 25 items requested, so a list with limit=100 costs 4. Store analytics costs 200 times that, because each page reads a large table — cache what you read and request only the date range you need.
An action costs 10 units per item, charged once when it is queued: a retry with the same Idempotency-Key costs nothing more.
A request the limiter itself refuses with 429 costs nothing and doesn’t extend your wait, but retrying before Retry-After only produces more 429s. A request the limiter admits counts even when it is refused afterwards — for example with 403 insufficient_scope or 404 not_found — so fix those instead of retrying them.
Versioning and deprecation
- Within v1, changes are additive only: new operations, new optional parameters, new response fields, new values in extensible enums. Nothing you rely on is removed or renamed, and no parameter becomes required.
- A breaking change is a new major version (
/v2). Before v1 operations are removed, they announce it withDeprecationandSunsetresponse headers at least 12 months ahead, with aLinkto the replacement where there is one. - The contract’s own version is
info.versionin the OpenAPI document (currently1.3.0); additive releases bump the minor version.
Changelog
- 1.3.0 —
GET /operations/{operationId}listsrecommendations:readamong its scopes; it already accepted it for a recommendation transition’s operation. - 1.2.0 — Recommendation workflow state:
POST /recommendations/{recommendationId}/transitions(scoperecommendations:write); recommendations carrystableKey,stateVersion,statusChangedAt,deferredUntilandresolution;statusaddsdeferredandresolved, and the list filter takesunresolved. - 1.1.0 — Actions: start audits (
POST /projects/{projectId}/audits,POST /audit-batches), write draft listings (POST /projects/{projectId}/revision-drafts), and follow them (GET /operations/{operationId}). New error codeconflict;idempotency_conflictis now returned. Revision text fields can carrysource: "api". - 1.0.0 — First release: organization, projects, audits, recommendations, scores, revisions, impact results and store analytics. Proceeds is declared but not served yet.
Support and incidents
- Service status. Apptonomy has no public status page yet. While a service the API depends on is down, requests answer
503 service_unavailablewithRetry-After; if that persists, contact support with arequestId. Security incidents and advisories are published on Security advisories. - Something not working as described: the in-app Support Center or support@apptonomy.ai, with the request’s
requestId. - A leaked key or a security issue: security@apptonomy.ai — see If a key leaks.
- How Apptonomy protects your data: Security, the subprocessor list and the DPA.