API Resources

4 min readLast updated View as MarkdownAgent setup

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:

  1. 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.
  2. 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:read too to follow them. Without the scope: 403 insufficient_scope. The scopes are listed on API Keys.
  3. 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

RequestScopeParametersWhat it returns
GET /organizationorganization:readnoneThe credential’s organization.

Organization fields: id, name, slug, timezone, iconUrl, createdAt, updatedAt.

Projects

RequestScopeParametersWhat it returns
GET /projectsprojects:readoptional: limit, cursorThe organization’s projects.
GET /projects/{projectId}projects:readprojectIdOne project.

Project fields: id, organizationId, name, iconUrl, targetLocales, apps, auditSchedule, firstAuditCompletedAt.

Audits

RequestScopeParametersWhat it returns
GET /projects/{projectId}/auditsaudits:readprojectId; limit, cursor, status (queued, running, completed, failed), startedAfterA project’s audit runs, newest first.
GET /audits/{auditId}audits:readauditIdOne audit run.

Audit fields: id, projectId, status, storefronts, startedAt, completedAt, overallScore, triggeredByUserId.

Recommendations

RequestScopeParametersWhat it returns
GET /projects/{projectId}/recommendationsrecommendations:readprojectId; limit, cursor, auditId, status (open, accepted, completed, dismissed, deferred, resolved, unresolved), priority (high, medium, low)A project’s recommendations.
GET /recommendations/{recommendationId}recommendations:readrecommendationIdOne recommendation, with provenance.

Recommendation fields: id, auditId, projectId, category, title, summary, rationale, priority, status, evidence, createdAt, dismissedByUserId, stableKey, stateVersion, statusChangedAt, deferredUntil, resolution.

Scores

RequestScopeParametersWhat it returns
GET /projects/{projectId}/scoresscores:readprojectId; limit, cursor, computedAfter, computedBeforeA project’s score history, newest first.
GET /scores/{scoreId}scores:readscoreIdOne score, with provenance.

Score fields: id, auditId, projectId, overall, components, method, computedAt.

Revisions

RequestScopeParametersWhat it returns
GET /projects/{projectId}/revisionsrevisions:readprojectId; limit, cursor, store (app_store, google_play), status (draft, published, archived)A project’s listing revisions.
GET /revisions/{revisionId}revisions:readrevisionIdOne revision.

Revision fields: id, projectId, store, revisionNumber, status, appVersion, appTitle, subtitle, description, shortDescription, keywords, promotionalText, whatsNew, icon, publishedAt, publishedByUserId, createdAt, updatedAt.

Impact results

RequestScopeParametersWhat it returns
GET /projects/{projectId}/impact-resultsimpact:readprojectId; limit, cursor, revisionIdA project’s measured revision impact results.
GET /impact-results/{impactResultId}impact:readimpactResultIdOne impact result, with provenance.

ImpactResult fields: id, projectId, revisionId, metric, window, baseline, observed, delta, confidence, computedAt.

Store analytics

RequestScopeParametersWhat it returns
GET /projects/{projectId}/store-analyticsanalytics:readprojectId, from, to; limit, cursor, store (app_store, google_play), storefrontDaily store-console analytics. Needs the store-analytics plan feature.

StoreAnalyticsDay fields: store, storefront, date, impressions, productPageViews, downloads, redownloads, conversionRate, uninstalls, crashes.

Proceeds

RequestScopeParametersWhat it returns
GET /projects/{projectId}/proceedsrevenue:readprojectId, from, to; limit, cursor, store (app_store, google_play), storefrontDaily proceeds. Needs revenue:read and the store-analytics plan feature.

ProceedsDay fields: store, storefront, date, sku, currency, proceeds, revenue, units, refunds.

Release notes

RequestScopeParametersWhat it returns
GET /release-notesnoneoptional: limit, cursor, deployedAfter, deployedBeforeApptonomy’s release notes, one object per production push, newest first: the user-facing changes each push shipped. Any active key reads them; no scope is needed.

ReleaseNote fields: id, version, deployedAt, date, items, blogLinks.

Proceeds is declared in the contract but not served yet: it answers 403 operation_not_enabled.

Release notes describe Apptonomy itself, not your organization’s data: each object is one production release of Apptonomy, newest first, with its version, deployedAt, date and the user-facing changes it shipped (items, each with a category of new_feature, fix or improvement and a title). They are the same notes as the website’s release notes page, and every key can read them.

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.