# App API

> The API an installed app calls: authentication, organizations, pagination, errors and the rate limit.

Source: https://developers-staging.foodpilot.tech/build/app-api

In this page you will learn how the App API works as a whole. Each operation is described in the [API reference](/reference).

## One surface, read-only

The App API lives under `/api/app/v1` on the API host of the platform your app is installed on. It is the only API an installation token can call: every other route answers `403` with the problem `forbidden-for-apps`, whatever the scopes. Version 1 has no write operation.

| Resource | Operations | Scope |
|---|---|---|
| Installation | `GET /installation` | none |
| Organizations | `GET /organizations`, `GET /organizations/{id}` | `read_organizations` |
| Products | `GET /products`, `GET /products/{id}`, `GET /products/{id}/scores` | `read_products` |
| Ingredients | `GET /ingredients`, `GET /ingredients/{id}`, `GET /ingredients/{id}/scores` | `read_ingredients` |
| Packagings | `GET /packagings`, `GET /packagings/{id}`, `GET /packagings/{id}/scores` | `read_packagings` |
| Questionnaires | `GET /questionnaires?entityType=&entityId=`, `GET /questionnaires/{id}` | `read_questionnaires` and the entity's read scope |
| Billing | `GET /billing/plans`, subscriptions and charges | none, see [Billing](/build/billing) |

## Authenticate

Send the installation token of your [OAuth install](/build/authentication) in every request:

```http
GET /api/app/v1/products/345 HTTP/1.1
Host: {tenant}-api.example.com
Authorization: Bearer <access_token>
```

The token lasts an hour. Refresh it before it expires, or after a `401`. The format of every answer is JSON: there is no other.

## Organizations

An installation covers the organizations an administrator granted and their descendants. Everything the API returns is limited to them:

- a collection lists only entities of covered organizations;
- an item outside them answers `404`, the same answer as an item that does not exist;
- a filter (`organizationId`, `entityId`) that names something outside them answers `404`.

`GET /installation` tells you what you were granted.

## Pagination

Collections answer a page and a cursor:

```json
{
  "items": [{ "id": 345, "organizationId": 12, "name": "Granola", "...": "..." }],
  "nextCursor": "eyJsYXN0SWQiOjM0NX0.9fGQ"
}
```

| Parameter | Meaning |
|---|---|
| `limit` | The page size, 50 by default and 100 at most |
| `after` | The `nextCursor` of the previous page |
| `updatedSince` | Only entities updated at or after this date (RFC 3339), on the collections that have one |

Items come in ascending `id` order. When `nextCursor` is `null`, you have read everything. A cursor is opaque and signed: pass it back unchanged, with the same filters, to the same resource, from the same installation. Anything else answers `400` with the problem `invalid-cursor`: start again without `after`. A cursor never widens what you can read: the organizations and the filters are applied again on every request.

To keep a copy up to date, read once from the start, then read again with `updatedSince` set to the time you began the previous read.

## Errors

Errors are [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) problems, `application/problem+json`, and each `type` is the address of the error's page: see [Errors](/errors). Match on `type`, not on the text:

```json
{
  "type": "https://dev.positive-app.fr/errors/scope-missing",
  "title": "Scope missing",
  "status": 403,
  "detail": "The installation was not granted the scope \"read_products\"."
}
```

| Status | `type` ends with | Meaning |
|---|---|---|
| 400 | `invalid-cursor` | The cursor is not valid for this installation, resource and filters |
| 400 | `invalid-parameter` | A parameter is malformed |
| 401 | | The token is missing, expired, or the installation was uninstalled or suspended |
| 403 | `scope-missing` | The scope was not granted |
| 403 | `forbidden-for-apps` | The route is not part of the App API |
| 404 | `not-found` | Not found, or outside the covered organizations |
| 429 | `rate-limited` | Too many requests: wait `Retry-After` seconds |

## Rate limit

An installation may make 600 requests per minute across the whole App API (the billing operations also have their own, stricter limit). Every answer carries:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | The budget: 600 |
| `X-RateLimit-Remaining` | What is left in the window |
| `X-RateLimit-Reset` | The Unix time when the budget is whole again |

A request over the budget answers `429` with `Retry-After`, in seconds. Prefer [webhooks](/build/webhooks) to polling.

## Formats

Dates and times are RFC 3339 strings. Identifiers are integers, except the installation (a UUID) and the billing objects (strings). A field that may be absent is `null`, never missing. New fields can be added to any object in version 1: ignore the ones you do not know.
