API Actions
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:
{
"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}/auditswith an optional body{ "store": "app_store" }or"google_play". Withoutstore, Apptonomy audits the project’s App Store app, or its Google Play app if it has no App Store app. - Several projects:
POST /audit-batcheswith{ "items": [{ "projectId": "…", "store": "…" }, …] }, each project at most once. Every item is checked before anything starts: if one is refused, the whole batch is refused anderror.detailsnames each refused item by its index (items[2].store). A project your key can’t see refuses the batch as404 not_foundwithout 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) or429 rate_limited(concurrency_limit). - Already running. A project whose app already has an audit running answers
409 conflictwithaudit_in_progress, naming the running audit, and nothing is queued. If one starts between your request and the audit, the item endsskippedwithaudit_in_progressand 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_exceededwithaudit_capandRetry-After. A plan without scheduled audits answers403 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;
triggeredByUserIdstaysnullbecause no person started it.
Writing a draft listing
POST /projects/{projectId}/revision-drafts:
{
"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 PlayappTitle(30),shortDescription(80),description(4,000),whatsNew(500). Another field answers400 invalid_requestwithunsupported_field, a longer valuetoo_long. recommendationId(optional) names the recommendation the text implements. It must be one of this project’s recommendations withstatus: accepted— accept it in Apptonomy or with a transition first; otherwise409 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 answers409 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 endsfailedwithdraft_changed.- The write happens before the response, so the operation is usually already
completed: the item’sresultResourceIdis the draft’s revision id. Text that was already there ends the itemskippedwithno_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:
{
"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;deferredUntilis required, in the future and at most a year ahead — after it passes the recommendation reads asopenagain),resolved(done;resolutionisimplemented, the default, orno_longer_applies) anddismissed(you won’t act on it). Fromopen,acceptedordeferreda recommendation can move to any other state; fromresolvedordismissedonly back toopen. Anything else answers409 conflict(invalid_transition) and the message lists where it can go. expectedVersionis the recommendation’sstateVersionas you read it (0before its first change). If it has changed since — someone moved it in Apptonomy or through the API — the request answers409 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 endsfailedwithstate_changed.- Asking for the state it’s already in writes nothing: the item ends
skippedwithno_change. A newdeferredUntilon a deferred recommendation is a change. reason(optional, up to 500 characters) anddraftRevisionId(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 hasstableKey: nulland answers409 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’sresultResourceId. Read the recommendation again for its newstatus,stateVersion,statusChangedAt,deferredUntilandresolution. - State set in Apptonomy counts. Dismissing or marking a recommendation done in the app shows up here, and the most recent change wins. A
completedstatus is a recommendation marked done in the app on an audit without astableKey. - Everything still open across your organization: list each project’s recommendations with
status=unresolved(open, accepted or deferred). Rows with the samestableKeyare 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.