---
title: API Actions
description: What the Apptonomy Public API can start or write — audits, draft listings and recommendation workflow state — with idempotency, operations and each action's rules.
---

What your code can ask Apptonomy to do. None publishes anything: an audit reads your listing, a draft waits in Apptonomy for a person to review and publish it, and a recommendation's state records your team's decision about it.

Parameters and body fields list the required ones first, then the optional ones after the semicolon.

### Audits

| Request | Scope | Parameters | Body | What it does |
|---|---|---|---|---|
| `POST /projects/{projectId}/audits` | `audits:write` | `projectId`, `Idempotency-Key` | optional: `store` (`app_store`, `google_play`) | Start an audit of one project. |
| `POST /audit-batches` | `audits:write` | `Idempotency-Key` | `items` | Start audits of several projects. |

**Operation** fields: `id`, `type`, `state`, `taskState`, `progress`, `items`, `resultResourceIds`, `error`, `retry`, `cancelRequested`, `createdAt`, `updatedAt`, `startedAt`, `endedAt`.

### Revisions

| Request | Scope | Parameters | Body | What it does |
|---|---|---|---|---|
| `POST /projects/{projectId}/revision-drafts` | `revisions:write` | `projectId`, `Idempotency-Key` | `store` (`app_store`, `google_play`), `fields`; `recommendationId`, `baseRevision` | Write text into a store's working draft. |

Returns an **Operation**, fields above.

### Recommendations

| Request | Scope | Parameters | Body | What it does |
|---|---|---|---|---|
| `POST /recommendations/{recommendationId}/transitions` | `recommendations:write` | `recommendationId`, `Idempotency-Key` | `to` (`open`, `accepted`, `deferred`, `resolved`, `dismissed`), `expectedVersion`; `reason`, `deferredUntil`, `resolution` (`implemented`, `no_longer_applies`), `draftRevisionId` | Change a recommendation's workflow state. |

Returns an **Operation**, fields above.

### Operations

| Request | Scope | Parameters | Body | What it does |
|---|---|---|---|---|
| `GET /operations/{operationId}` | `audits:read` or `revisions:read` or `recommendations:read` | `operationId` | none | The status of an operation an action queued. |

Returns an **Operation**, fields above.

### Idempotency-Key

Every action needs an `Idempotency-Key` header: a value you choose, 1 to 255 visible characters, new for each new request. If a request times out or you aren't sure it arrived, send it again with the **same key and the same body**: you get back the same operation, and nothing is started or written twice. The same key with a different body answers `409 idempotency_conflict`. A missing key answers `400 invalid_request`.

### Operations

An action answers `202 Accepted` with the **operation** it queued, and a `Location` header pointing at it:

```json
{
  "data": {
    "id": "op_…",
    "type": "audit.start",
    "state": "submitted",
    "progress": 0,
    "items": [{ "targetId": "proj_…", "projectId": "proj_…", "state": "pending", "resultResourceId": null, "errorCode": null }],
    "resultResourceIds": [],
    "error": null,
    "retry": "none",
    "…": "…"
  },
  "meta": { "requestId": "req_…", "apiVersion": "v1", "freshness": null, "warnings": [] }
}
```

Read it with `GET /operations/{operationId}` until `state` is `completed`, `failed` or `cancelled`. Each item says how it ended (`completed`, `skipped` or `failed`, with an `errorCode`) and `resultResourceId` names what it produced. `resultResourceIds` lists everything the operation produced.

**`completed` means each item reached its end, not that an audit has finished.** For an audit start, the item's `resultResourceId` is the audit's id: follow the audit itself with `GET /audits/{auditId}` until its `status` is `completed` (it runs for several minutes).

When an operation `failed`, `retry` says what to do: `retry_with_new_key` (the failure wasn't caused by your request; send it again with a new `Idempotency-Key`) or `do_not_retry` (the key, the organization's switches or its plan stopped it; fix that first). If the key is revoked while an operation runs, it stops at its next step: what it already started stays started and is listed.

### Starting audits

- **One project:** `POST /projects/{projectId}/audits` with an optional body `{ "store": "app_store" }` or `"google_play"`. Without `store`, Apptonomy audits the project's App Store app, or its Google Play app if it has no App Store app.
- **Several projects:** `POST /audit-batches` with `{ "items": [{ "projectId": "…", "store": "…" }, …] }`, each project at most once. Every item is checked before anything starts: if one is refused, the whole batch is refused and `error.details` names each refused item by its index (`items[2].store`). A project your key can't see refuses the batch as `404 not_found` without saying which.
- **How many at once.** A batch holds up to 5 items on Free, 10 on Basic, 25 on Pro, 50 on Elite and 100 on Enterprise, and an organization can have up to 1, 2, 5, 10 or 25 operations running at a time. Over either limit: `400 invalid_request` (`batch_too_large`) or `429 rate_limited` (`concurrency_limit`).
- **Already running.** A project whose app already has an audit running answers `409 conflict` with `audit_in_progress`, naming the running audit, and nothing is queued. If one starts between your request and the audit, the item ends `skipped` with `audit_in_progress` and that audit's id.
- **How often.** The API starts an audit of a project at most once per your plan's audit cadence — once a day on a daily schedule, then every 7, 14 or 28 days on a weekly, every-two-weeks or monthly one. Sooner answers `429 quota_exceeded` with `audit_cap` and `Retry-After`. A plan without scheduled audits answers `403 entitlement_required`: start its audits in the app. Audits started in the app or on schedule don't count against this.
- **Who it runs as.** An audit started by a key runs as the project's owner; `triggeredByUserId` stays `null` because no person started it.

### Writing a draft listing

`POST /projects/{projectId}/revision-drafts`:

```json
{
  "store": "app_store",
  "fields": { "subtitle": "Kids geography quizzes" },
  "recommendationId": "…",
  "baseRevision": { "id": "…", "updatedAt": "2026-11-17T11:00:00.000Z" }
}
```

- The text goes into the project's **working draft** for that store — the one you edit in Apptonomy — which is created if there isn't one. A project has one working draft per store; the API never makes a second. Read it with `GET /projects/{projectId}/revisions?status=draft`.
- **Fields** are each store's own, within the store's limits: App Store `appTitle` (30), `subtitle` (30), `keywords` (100), `promotionalText` (170), `description` (4,000), `whatsNew` (4,000); Google Play `appTitle` (30), `shortDescription` (80), `description` (4,000), `whatsNew` (500). Another field answers `400 invalid_request` with `unsupported_field`, a longer value `too_long`.
- **`recommendationId`** (optional) names the recommendation the text implements. It must be one of this project's recommendations with `status: accepted` — accept it in Apptonomy or with a [transition](#changing-a-recommendations-state) first; otherwise `409 conflict` (`recommendation_not_accepted`). It's recorded on the draft with the operation and your key.
- **`baseRevision`** (optional) is the draft as you last read it. If someone changed the draft since, the request answers `409 conflict` (`draft_changed`) and nothing is queued: read it again and decide. With or without it, a change made while your write is in flight is never overwritten — the operation's item ends `failed` with `draft_changed`.
- The write happens before the response, so the operation is usually already `completed`: the item's `resultResourceId` is the draft's revision id. Text that was already there ends the item `skipped` with `no_change`.
- Fields written this way show `source: "api"` on the revision. A person reviews and publishes the draft in Apptonomy, as any other draft.

### Changing a recommendation's state

A recommendation can come up in audit after audit. Each one it appears in is an observation with its own `id`; observations of the same recommendation share a `stableKey`, and they share one workflow state. Change it with `POST /recommendations/{recommendationId}/transitions`, naming any of its observations:

```json
{
  "to": "deferred",
  "expectedVersion": 2,
  "deferredUntil": "2027-01-15T00:00:00.000Z",
  "reason": "After the January release."
}
```

- **States.** `open` (not decided), `accepted` (you'll act on it), `deferred` (decide later; `deferredUntil` is required, in the future and at most a year ahead — after it passes the recommendation reads as `open` again), `resolved` (done; `resolution` is `implemented`, the default, or `no_longer_applies`) and `dismissed` (you won't act on it). From `open`, `accepted` or `deferred` a recommendation can move to any other state; from `resolved` or `dismissed` only back to `open`. Anything else answers `409 conflict` (`invalid_transition`) and the message lists where it can go.
- **`expectedVersion`** is the recommendation's `stateVersion` as you read it (`0` before its first change). If it has changed since — someone moved it in Apptonomy or through the API — the request answers `409 conflict` (`state_changed`) and nothing is written: read it again and decide. If two requests at the same version race, one is written and the other's item ends `failed` with `state_changed`.
- **Asking for the state it's already in** writes nothing: the item ends `skipped` with `no_change`. A new `deferredUntil` on a deferred recommendation is a change.
- **`reason`** (optional, up to 500 characters) and **`draftRevisionId`** (optional, a revision of the same project that carries the work) are recorded with the change, together with your key, the time and the observation you named.
- **No `stableKey`.** A recommendation from an audit that ran before stable keys existed has `stableKey: null` and answers `409 conflict` (`no_stable_key`); change the state of the same recommendation in a newer audit.
- The change is written before the response, so the operation is usually already `completed`, with the recommendation's id as the item's `resultResourceId`. Read the recommendation again for its new `status`, `stateVersion`, `statusChangedAt`, `deferredUntil` and `resolution`.
- **State set in Apptonomy counts.** Dismissing or marking a recommendation done in the app shows up here, and the most recent change wins. A `completed` status is a recommendation marked done in the app on an audit without a `stableKey`.
- **Everything still open across your organization:** list each project's recommendations with `status=unresolved` (open, accepted or deferred). Rows with the same `stableKey` are one recommendation seen by several audits; the newest is its latest observation. A recommendation a newer audit no longer reports stays as it was until you change it.
