# Postman collection

43 requests covering every endpoint the API exposes.

## Import

1. Postman → **Import** → both files in this folder.
2. Select the **AI Radar — local** environment, top right.
3. Fill in two values from `apps/api/.env`:
   - `publish_key` ← `PUBLISH_API_KEY`
   - `admin_password` ← `ADMIN_PASSWORD`
4. Run **Health** first. If the database is down, everything else fails
   in confusing ways.

## Three credentials, deliberately separate

| Auth | Used by | Travels as |
|---|---|---|
| Publish key | An external agent submitting stories | `Authorization: Bearer` |
| Admin password | You, in the operator console | HttpOnly cookie `ai_radar_admin` |
| Reader session | A signed-in reader | Cookie `ar_session`, or Bearer on the app |

Leaking one must not hand over the others, which is why the publish key
grants submission and nothing else — it cannot read the audience, change
sources, or trigger a pipeline run.

Postman stores cookies automatically, so running **Admin → Login** once
makes every other admin request work. For reader endpoints, run
**Accounts → Login (app)**; it captures the token into `session_token`
for you.

## Things worth knowing

**Rejections are `200 OK` with `ok: false`.** Not a 4xx. A scheduled task
treating a duplicate as a transport failure would retry it forever.
`ok: false` is a final answer.

**The sample stories version themselves per run.** Each run submits
"Claude Opus 41.23" or similar, so re-running does not trip duplicate
detection. It has to be a real version number rather than any unique
string: dedup compares extracted entities, and an unrecognised token
extracts no version at all, so the check falls through to title
similarity and correctly calls it the same event.

**Submissions default to `held`.** They land in the admin queue rather
than on the site. Send `"status": "published"` only when you mean it —
that goes live immediately and fires alerts.

## Running it headless

```bash
npx newman run docs/postman/AI-Radar.postman_collection.json \
  -e docs/postman/AI-Radar-local.postman_environment.json
```

Fill the environment file's key fields first, or copy it somewhere
outside the repo and fill that — the committed copy deliberately has
them empty.

Verified: all 43 requests resolve against a live API, and three
consecutive full runs pass with no failures.