API Conventions

8 min readLast updated View as MarkdownAgent setup

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 conversionRate are fractions between 0 and 1, never percent.
  • Every field is always present, and null when 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 id and 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 limit items while hasMore is still true. Keep following the cursor until hasMore is false.

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:

FieldMeaning
asOfWhen the data was last refreshed
consistencystrong or eventual
staletrue when the data is older than its normal refresh cycle
nextUpdateExpectedAtWhen 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:

WarningMeaning
partial_resultPart of the answer isn’t final: an audit still running, or a store whose data stops before to
stale_dataThe data is older than its refresh cycle
fields_omittedFields 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 kindMeaning
measuredRead directly from a source, such as the store listing or store analytics
derivedCalculated from measured values
interpretationA judgment drawn from the evidence by Apptonomy’s AI analysis, with the evidence it rests on
unavailableThe 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.

CodeStatusRetry?Meaning
invalid_request400noA parameter is missing, malformed or out of range; details names each one
invalid_cursor400noThe cursor is malformed, expired, or was issued for a different query
unauthenticated401noNo credential, or a malformed one, was sent
invalid_credential401noThe key is unknown, revoked or expired
forbidden403noThe organization turned API keys off, or Apptonomy has paused programmatic access; the message says which
insufficient_scope403noThe key lacks the scope this operation needs
entitlement_required403noThe organization’s plan doesn’t include this
organization_suspended403noThe organization is suspended
operation_not_enabled403noThe operation isn’t available yet
not_found404noThe resource doesn’t exist, or isn’t in your organization
method_not_allowed405noThe path doesn’t take this method; Allow lists the ones it does
not_acceptable406noThe Accept header excludes application/json
idempotency_conflict409noThe Idempotency-Key was already used with a different request
conflict409noAn 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_limited429yesA per-minute limit was exceeded; wait Retry-After seconds
quota_exceeded429yesThe organization’s daily quota is spent; Retry-After is the time to its reset
internal_error500yesAn unexpected failure; retry with backoff and quote the request id to support
service_unavailable503yesA 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:

HeaderExampleMeaning
RateLimit"operation-minute";r=0;t=50The 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-After50On 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 with Deprecation and Sunset response headers at least 12 months ahead, with a Link to the replacement where there is one.
  • The contract’s own version is info.version in the OpenAPI document (currently 1.3.0); additive releases bump the minor version.

Changelog

  • 1.3.0 — GET /operations/{operationId} lists recommendations:read among its scopes; it already accepted it for a recommendation transition’s operation.
  • 1.2.0 — Recommendation workflow state: POST /recommendations/{recommendationId}/transitions (scope recommendations:write); recommendations carry stableKey, stateVersion, statusChangedAt, deferredUntil and resolution; status adds deferred and resolved, and the list filter takes unresolved.
  • 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 code conflict; idempotency_conflict is now returned. Revision text fields can carry source: "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_unavailable with Retry-After; if that persists, contact support with a requestId. 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.