---
title: API Resources
description: What the Apptonomy Public API reads — every resource, the scope each read needs, its parameters and the fields it returns — and the checks every request passes.
---

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](/docs/api/keys); [Getting Started](/docs/api/getting-started) walks through the first one, and [Conventions](/docs/api/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](/docs/api/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](/docs/api/keys#what-a-key-can-read).
3. **The organization's switches.** An Owner or Manager can turn API keys off for the whole organization (see [If a key leaks](/docs/api/keys#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`.

### Release notes

| Request | Scope | Parameters | What it returns |
|---|---|---|---|
| `GET /release-notes` | none | optional: `limit`, `cursor`, `deployedAfter`, `deployedBefore` | Apptonomy'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.
