# Versions & changelog

The API version is part of the path: `/api/v1`. Within v1:

- We **add** things (new endpoints, new fields, new error codes, new event types) without warning. Ignore fields you do not know.
- We **never** remove or rename a field, change its type or change what a status word means within v1.
- A breaking change gets a new version (`/api/v2`), announced by email at least 90 days before v1 changes.

The current schema version is `2026-11-05` (in `openapi.json` and in every webhook as `apiVersion`).

## Changelog

**2026-11-05**
- New: test keys (`mm_test_…`) with made-up results; `GET /account`; `GET /jobs`, `POST /jobs/{id}/cancel`, `GET /lists`, `GET /lists/{id}/rows` (JSON pages or CSV), `DELETE /lists/{id}`, `POST /webhooks/test`; `wait` on POSTs; `Idempotency-Key` on every POST; `X-RateLimit-*` headers; cursor pages; `role: "best"` on search.
- New fields on every result: `result`, `resultCode`, `resultMeaning` and the status words (`emailStatusText`, `findStatusText`, `emailTypeText`) – the same words as the app.
- Changed: errors are now `{ "error": { "code", "message", "docs_url" } }` (before: `{ "error": "text" }`).
- Changed: webhooks are signed as `X-Moleman-Signature: t=…,v1=…` over `<t>.<body>` with your account signing secret (before: `sha256=…` over the body, only with `webhookSecret`), and retried 8 times.
- Changed: find-contacts and verify results no longer carry company-register fields (they stay in deep-search).
- Changed: `GET /jobs/{id}` returns the job's own rows (before: the whole list), up to 1,000 per page.

**2026-10-31**
- First version: search, find-contacts, verify, deep-search, jobs, lists, webhooks.