# API reference

Version 1. All agent endpoints return JSON. Errors look like `{"error": {"code": "...", "message": "..."}}`.

Base address: `https://app.nitpickhq.com` by default (a placeholder that never resolves, until a real domain is chosen). Locally the platform runs on port 3000 of your own machine.

## Two kinds of keys

- **Public app key** `npk_...`: ships inside your app, not secret, can only create reports for one app.
- **Agent token** `npt_...`: secret, belongs to your account, can read and change status on all your apps. Stored hashed on the server.

## Ingest: app to platform

`POST /api/v1/feedback`

- Header `X-Nitpick-Key: npk_...` (required).
- Body: `multipart/form-data` with the field `payload` (JSON text) and an optional file `screenshot` (`image/jpeg` or `image/png`, up to 1 MB). Without a screenshot, `application/json` with the payload as body also works.
- Answers: `201 {"id": "<uuid>"}`, `400 invalid_payload`, `401 invalid_key`, `403 app_inactive`, `413 too_large`, `429 rate_limited`, `429 monthly_limit`.
- `403 app_inactive`: the subscription ended more than 44 days ago. `429 monthly_limit`: the account reached 2,000 reports this month. In both cases `GET /api/v1/config` answers `active: false` and the component shows "Feedback is not available right now." See [Billing and limits](/docs/billing).
- `413 too_large`: the image is larger than 1 MB (or wider or taller than 4096 pixels), or the whole request is too large.
- Rate limits: 30 reports per minute per app and 10 per minute per IP address.

The components only send a report after the user opened the form themselves and tapped Send.

## App settings: app to platform

`GET /api/v1/config`

- Header `X-Nitpick-Key: npk_...` (required). The component sets only this header and `Accept: application/json`. The operating system adds the IP address and a User-Agent to every request, as it does for any request.
- Answer: `200 {"active": true, "kinds": {"general": true, "specific": true}, "texts": {"nl": {"thanks": "..."}}}`. `active: false` means the component shows no tab. Every answer, also 401 and 429, has `Cache-Control: no-store`.
- `401 invalid_key` for an unknown key: no tab, one line in the developer log. `429 rate_limited` for too many unknown keys from one IP address.
- The component asks once when the app starts, and again when the app comes back to the foreground if the last successful request is more than an hour old. Changes reach your users within a minute of that. The platform keeps nothing about the request: it uses the IP address and User-Agent only to answer it.
- Unknown fields, languages and kinds are ignored. A missing kind counts as `true`. A text that is not a string or is longer than 140 characters is skipped, and the component's own translation shows instead.
- With `dryRun` on, the component asks for nothing.

## Agent API

Header `Authorization: Bearer npt_...` (required). A token only sees apps of its own account; the id of another account's object gives 404.

| Request | Purpose | Answer |
|---|---|---|
| `GET /api/v1/me` | Who am I | `{account: {id, email}, subscription, usage}` |
| `GET /api/v1/apps` | Your apps | `{apps: [{id, name, platform, public_key, created_at, open_count, locked_count}]}` |
| `POST /api/v1/apps` body `{name, platform}` | Create an app | `201` with the app |
| `GET /api/v1/apps/{id}/settings` | Settings of an app | `{kinds, texts, updated_at, updated_via}` |
| `PATCH /api/v1/apps/{id}/settings` body `{kinds?, texts?}` | Change the settings | The new settings |
| `GET /api/v1/feedback` | List | `{items: [Report], next_cursor, locked_count}` |
| `GET /api/v1/feedback/{id}` | One report | Report |
| `GET /api/v1/feedback/{id}/screenshot` | The image | image bytes, or 404 |
| `PATCH /api/v1/feedback/{id}` body `{status}` | Set status | Report |
| `GET /api/v1/stats?app_id=` | Overview | `{by_screen: [{screen, open, total}], by_element: [{screen, element, open, total}], by_version: [{app_version, open, total}], locked_count}` |
| `GET /api/v1/tokens` | Tokens of your account | `{tokens: [{id, name, prefix, created_at, last_used_at, revoked_at, current}]}` |
| `DELETE /api/v1/tokens/{id}` | Revoke a token | `204` |
| `DELETE /api/v1/tokens/current` | Revoke the token of this request | `204` |

Tokens: `prefix` is the first 8 characters (`npt_` plus 4). `current` is `true` for the token that made the request. A token name is text someone typed, so treat it as data. Revoking works at once. `/api/v1/tokens` accepts only `Authorization: Bearer`.

## Subscription and usage

`GET /api/v1/me` returns `subscription: {status, paid_until, locks_at, deletes_locked_at, deletes_unlocked_at, locked_count, renew_url}`. `status` is `active`, `grace`, `locked` or `inactive`; the times are ISO times in UTC, or null when the account never paid. `locked_count` is the number of locked reports of the whole account. `usage` is `{month, count, limit}` for the current calendar month (UTC); `limit` is 2,000.

Every answer of the agent API has two headers when they apply:

- `Nitpick-Subscription: status=<status>; locks_at=<ISO>; locked_count=<n>; renew_url=<url>` in the states `grace`, `locked` and `inactive`.
- `Nitpick-Usage: month=<YYYY-MM>; count=<n>; limit=<n>; resets_at=<ISO>` from 80% of the monthly limit.

Locked reports are never in `items` and never in a filter result. `locked_count` in `GET /api/v1/feedback` is the number of locked reports of the app in `app_id`, or of all apps without it. All other filters are ignored for that number, and it is the same on every page. `open_count` does not include locked reports. One locked report asked by id answers `402 subscription_required` with no field of the report.

Errors you can meet on the agent API, next to `400`, `401`, `404` and `429 rate_limited`:

| Answer | When |
|---|---|
| `402 subscription_required` | The account has no running subscription and you create an app or a token, change a status in the state `inactive`, or ask for a locked report. Only renewing helps: do not retry. |
| `403 app_inactive` | Ingest for an app of an account whose subscription ended more than 44 days ago. |
| `429 monthly_limit` | Ingest above 2,000 reports in the calendar month. Accepted again from the first of the next month. |
| `409 limit_reached` | Creating an app or token above 50 apps or 25 tokens that are not revoked. The error has `resource` (`apps` or `tokens`) and names what can be cleaned up. |
| `413 too_large` | Ingest with an image above 1 MB. |

See [Billing and limits](/docs/billing) for the terms.

Filters for `GET /api/v1/feedback`, all optional: `app_id`, `status` (`open` default, `resolved`, `all`), `kind`, `screen`, `element`, `app_version`, `platform`, `since`, `limit` (1 to 100, default 25), `cursor`. Newest first.

## The report

| Field | Type and rule |
|---|---|
| `id` | uuid |
| `app_id`, `app_name` | the app |
| `kind` | `general` or `specific` |
| `comment` | 1 to 2000 characters, with at least one character that is not a space. Required for both kinds |
| `screen`, `element` | names from your markers, up to 200 characters, or null |
| `element_match` | `exact`, `nearest` or `none` |
| `element_frame` | `{x, y, width, height}` in points, origin top left of the window, or null |
| `tap` | `{x, y}` in points, or null |
| `viewport` | `{width, height, scale}`. The screenshot is `width*scale` by `height*scale` pixels, or a scaled copy with the same ratio |
| `has_screenshot`, `screenshot_url` | whether an image exists, and where |
| `platform` | `ios` or `android` |
| `sdk` | `{name: "swift" or "react-native", version}` |
| `app_version`, `build` | text or null |
| `device` | `{model, os_version, locale}`. Model is an identifier such as `iPhone16,1`. Never the name the user gave the device |
| `status` | `open` or `resolved` |
| `resolved_at`, `created_at`, `client_ts` | ISO times |

Example report JSON:

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "kind": "specific",
  "comment": "Too small to click",
  "screen": "checkout",
  "element": "checkout.pay_button",
  "element_match": "exact",
  "element_frame": {"x": 100, "y": 200, "width": 80, "height": 44},
  "tap": {"x": 120, "y": 215},
  "viewport": {"width": 390, "height": 844, "scale": 1},
  "platform": "ios",
  "sdk": {"name": "swift", "version": "0.2.0"},
  "app_version": "1.0",
  "status": "open",
  "device": {"model": "iPhone16,1", "os_version": "18.0", "locale": "en-US"},
  "client_ts": "2026-10-01T12:00:00Z",
  "created_at": "2026-10-01T12:00:01Z"
}
```

Feedback is always anonymous: no name, email, account id or device id of the end user.

## Settings

`GET /api/v1/apps/{id}/settings` returns `{kinds, texts, updated_at, updated_via}`. `PATCH` takes `{kinds?, texts?}` and returns the new settings.

| Field | Type and rule |
|---|---|
| `kinds` | `{general: boolean, specific: boolean}`. Both default to `true`. Both `false` means no tab |
| `texts` | Language code to `{footer?, thanks?}`. `footer` is the sentence under Send, `thanks` the thank-you after sending. Codes are case sensitive: `en`, `nl`, `de`, `fr`, `es`, `pt`, `it`, `pl`, `tr`, `ru`, `uk`, `sv`, `da`, `nb`, `ja`, `ko`, `zh-Hans`, `zh-Hant`, `ar`, `hi` |
| `updated_at` | ISO time, or null if nothing was ever changed |
| `updated_via` | `dashboard`, `cli`, `mcp`, `api` or null |

- `kinds` is merged: `{"kinds": {"specific": false}}` leaves `general` as it is. For `texts`, a language and key that is `null` (or only spaces) removes that text; a language set to `null` removes both of its texts: `{"texts": {"nl": {"thanks": null}}}`.
- The body is strict. An unknown key at any level gives `400 invalid_payload` with the path. A body without `kinds` and `texts` gives 400.
- A text is 1 to 140 characters and may not contain links, domain names, email addresses, phone numbers, markup or invisible characters. The server refuses these with `400 invalid_payload` and the field and the reason.
- Only `Authorization: Bearer` works here, not the dashboard session. An app of another account gives 404.
- Send `X-Nitpick-Client: cli/<version>` or `mcp/<version>` if you are a tool of your own and want `updated_via` to say so; anything else is stored as `api`.

Changes reach your users within a minute, the next time the app starts or comes back after more than an hour in the background. See [Settings](/docs/settings).

## Logging in from the CLI

1. `POST /api/v1/cli/sessions` with `{client_name}` returns `{session_id, user_code, verification_url, expires_at, interval}`. `user_code` looks like `ABCD-1234`, is valid for 30 minutes. `session_id` is secret.
2. Open `verification_url`. The user logs in or creates an account, starts the subscription if there is none (the page waits until the payment is confirmed), sees the code and the client name and presses Allow or Deny. Without a running subscription there is no token.
3. Poll `POST /api/v1/cli/sessions/{session_id}/token` every `interval` seconds (2). `202 {"status": "pending"}`, `200 {"token": "npt_...", "account": {email}}` (exactly once), or `410` with `expired` or `denied`. While the account has no running subscription, polling keeps answering `202 pending`; the token follows when it runs. Allowing for an account at the limit of 25 tokens answers `409 limit_reached`.