# REST API

Read and work the feedback queue over HTTPS — bearer-authenticated with an itr_ API key, scoped to your organization.

All endpoints live under `https://iterateto.com/api/v1` and are scoped to your API key's organization. Authenticate with a bearer token:

```http
Authorization: Bearer itr_your_secret_key
```

Errors come back as `{ error: { code, message } }` with status 401, 403, 404, or 422.

> **Warning:** Keys are rate-limited to 300 requests/minute per key. Exceeding the limit currently surfaces as `401` ("Missing or invalid API key") rather than 429 — if a valid key suddenly starts getting 401s during a burst, back off and retry after a minute.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/projects` | List the projects in your organization. |
| GET | `/api/v1/feedback` | List / filter feedback. Query: `projectId`, `status`, `kind`, `q`, `tag`, `limit` (≤ 50, default 20), `cursor`. Cursor-paginated, newest first. |
| GET | `/api/v1/feedback/{id}` | Full document incl. page context, targets, notes, screenshot URLs. |
| PATCH | `/api/v1/feedback/{id}` | Body `{ status?, priority?, tags?, assigneeId? }`. |
| DELETE | `/api/v1/feedback/{id}` | Erase a single feedback item and its screenshots. |
| POST | `/api/v1/feedback/{id}/notes` | Add an internal note. Body `{ body }` (1–4000 chars). |
| GET | `/api/v1/feedback/export` | Stream a full export. Query: `projectId?`, `format=csv|json` (default csv). |
| POST | `/api/v1/erasure` | Erase a data subject's feedback by `email` and/or `identify_id`, optionally scoped to `project_id`. Returns `{ matched, deleted }`. |
| GET | `/api/v1/screenshots/{fileId}` | Image stream (organization-checked). |

## List feedback

```bash
curl -H "Authorization: Bearer itr_your_secret_key" \
  "https://iterateto.com/api/v1/feedback?status=new&limit=20"
```

## Update an item

```bash
curl -X PATCH \
  -H "Authorization: Bearer itr_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress","priority":"high","tags":["checkout"]}' \
  "https://iterateto.com/api/v1/feedback/FEEDBACK_ID"
```

Valid values: `status` is one of `new · in_progress · resolved · archived · spam`; `priority` is `low · medium · high` or `null`; `assigneeId` is a member's user id or `null`.

## Export

`GET /api/v1/feedback/export` streams your whole queue as CSV (default) or JSON, with a `Content-Disposition` attachment header.

```bash
curl -H "Authorization: Bearer itr_your_secret_key" \
  "https://iterateto.com/api/v1/feedback/export?format=csv" -o feedback.csv
```

## Erasure (GDPR)

`POST /api/v1/erasure` deletes every feedback item from one data subject, identified by contact `email` and/or the host-supplied `identify_id`. Provide at least one; narrow to a single project with `project_id`.

```bash
curl -X POST \
  -H "Authorization: Bearer itr_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com"}' \
  "https://iterateto.com/api/v1/erasure"
```

## Screenshots

In `GET /api/v1/feedback/{id}` responses, each entry in `screenshots` carries two image URLs: `url` is the annotated preview (always present), and `baseUrl` is the clean capture — annotations removed, redactions destructively baked in — or `null` when it would be identical to the preview. Both are redaction-safe.