API Resources
Everything the Public API reads, by the resource it returns. Every request is a GET to https://api.apptonomy.ai/v1 with an API key; Getting Started walks through the first one, and Conventions covers the response envelope, pagination, provenance and errors these share.
Plans, scopes and switches
Every request must pass all three of these checks:
- The plan. API keys need a plan that includes API access (Enterprise). Without it:
403 entitlement_required. Store analytics also needs a plan with store analytics. - The key’s scopes. Each read needs one read scope (table below), and each action its write scope (Actions). A write scope never reads: a key that starts audits needs
audits:readtoo to follow them. Without the scope:403 insufficient_scope. The scopes are listed on API Keys. - The organization’s switches. An Owner or Manager can turn API keys off for the whole organization (see If a key leaks); a request then answers
403 forbidden, and the message says which switch refused it.
sensitive:read adds personal fields (user ids such as triggeredByUserId) to anything else the key can read. Without it those fields are left out, and meta.warnings carries a fields_omitted entry naming each field and the scope that would return it.
Resources
Each read, by the resource it returns. Parameters list the required ones first, then the optional ones after the semicolon.
Organizations
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /organization | organization:read | none | The credential’s organization. |
Organization fields: id, name, slug, timezone, iconUrl, createdAt, updatedAt.
Projects
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects | projects:read | optional: limit, cursor | The organization’s projects. |
GET /projects/{projectId} | projects:read | projectId | One project. |
Project fields: id, organizationId, name, iconUrl, targetLocales, apps, auditSchedule, firstAuditCompletedAt.
Audits
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects/{projectId}/audits | audits:read | projectId; limit, cursor, status (queued, running, completed, failed), startedAfter | A project’s audit runs, newest first. |
GET /audits/{auditId} | audits:read | auditId | One audit run. |
Audit fields: id, projectId, status, storefronts, startedAt, completedAt, overallScore, triggeredByUserId.
Recommendations
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects/{projectId}/recommendations | recommendations:read | projectId; limit, cursor, auditId, status (open, accepted, completed, dismissed, deferred, resolved, unresolved), priority (high, medium, low) | A project’s recommendations. |
GET /recommendations/{recommendationId} | recommendations:read | recommendationId | One recommendation, with provenance. |
Recommendation fields: id, auditId, projectId, category, title, summary, rationale, priority, status, evidence, createdAt, dismissedByUserId, stableKey, stateVersion, statusChangedAt, deferredUntil, resolution.
Scores
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects/{projectId}/scores | scores:read | projectId; limit, cursor, computedAfter, computedBefore | A project’s score history, newest first. |
GET /scores/{scoreId} | scores:read | scoreId | One score, with provenance. |
Score fields: id, auditId, projectId, overall, components, method, computedAt.
Revisions
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects/{projectId}/revisions | revisions:read | projectId; limit, cursor, store (app_store, google_play), status (draft, published, archived) | A project’s listing revisions. |
GET /revisions/{revisionId} | revisions:read | revisionId | One revision. |
Revision fields: id, projectId, store, revisionNumber, status, appVersion, appTitle, subtitle, description, shortDescription, keywords, promotionalText, whatsNew, icon, publishedAt, publishedByUserId, createdAt, updatedAt.
Impact results
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects/{projectId}/impact-results | impact:read | projectId; limit, cursor, revisionId | A project’s measured revision impact results. |
GET /impact-results/{impactResultId} | impact:read | impactResultId | One impact result, with provenance. |
ImpactResult fields: id, projectId, revisionId, metric, window, baseline, observed, delta, confidence, computedAt.
Store analytics
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects/{projectId}/store-analytics | analytics:read | projectId, from, to; limit, cursor, store (app_store, google_play), storefront | Daily store-console analytics. Needs the store-analytics plan feature. |
StoreAnalyticsDay fields: store, storefront, date, impressions, productPageViews, downloads, redownloads, conversionRate, uninstalls, crashes.
Proceeds
| Request | Scope | Parameters | What it returns |
|---|---|---|---|
GET /projects/{projectId}/proceeds | revenue:read | projectId, from, to; limit, cursor, store (app_store, google_play), storefront | Daily proceeds. Needs revenue:read and the store-analytics plan feature. |
ProceedsDay fields: store, storefront, date, sku, currency, proceeds, revenue, units, refunds.
Proceeds is declared in the contract but not served yet: it answers 403 operation_not_enabled.
A revision carries the listing text of its primary locale — title, subtitle, description, keywords, promotional text, what’s new — and its icon, but no screenshots.
Dates for store analytics and proceeds are YYYY-MM-DD, inclusive, at most 366 days apart; storefront is a two-letter country code.
An unknown parameter, a repeated one, or a malformed value answers 400 invalid_request, and error.details names each parameter that was wrong.