---
title: API Conventions
description: How the Apptonomy Public API behaves across every request — the OpenAPI document, identifiers and times, responses, pagination, freshness, provenance, errors, rate limits, versioning and the changelog.
---

## 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:

```json
{
  "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:

```json
{
  "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:

| 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:

```json
{
  "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 `429`s. 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](/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](/docs/api/keys#if-a-key-leaks).
- How Apptonomy protects your data: [Security](/security), the [subprocessor list](/subprocessors) and the [DPA](/dpa).
