App API
In this page you will learn how the App API works as a whole. Each operation is described in the API 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 |
Authenticate
Send the installation token of your OAuth install in every request:
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 answers404.
GET /installation tells you what you were granted.
Pagination
Collections answer a page and a cursor:
{
"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 problems, application/problem+json, and each type is the address of the error's page: see Errors. Match on type, not on the text:
{
"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 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.