API Actions

7 min readLast updated View as MarkdownAgent setup

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

RequestScopeParametersBodyWhat it does
POST /projects/{projectId}/auditsaudits:writeprojectId, Idempotency-Keyoptional: store (app_store, google_play)Start an audit of one project.
POST /audit-batchesaudits:writeIdempotency-KeyitemsStart audits of several projects.

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

Revisions

RequestScopeParametersBodyWhat it does
POST /projects/{projectId}/revision-draftsrevisions:writeprojectId, Idempotency-Keystore (app_store, google_play), fields; recommendationId, baseRevisionWrite text into a store’s working draft.

Returns an Operation, fields above.

Recommendations

RequestScopeParametersBodyWhat it does
POST /recommendations/{recommendationId}/transitionsrecommendations:writerecommendationId, Idempotency-Keyto (open, accepted, deferred, resolved, dismissed), expectedVersion; reason, deferredUntil, resolution (implemented, no_longer_applies), draftRevisionIdChange a recommendation’s workflow state.

Returns an Operation, fields above.

Operations

RequestScopeParametersBodyWhat it does
GET /operations/{operationId}audits:read or revisions:read or recommendations:readoperationIdnoneThe 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}/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:

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

{
  "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.