# Streepaf

> Shareable checklists that anyone can cross items off, with no account and no sign-up. A list is addressed by a secret link; whoever holds the link holds the access.

Streepaf is built to be driven by software as much as by people. Everything the
website does is available over this JSON API and over MCP.

## Authentication

There are no accounts and no API keys. Every list has three tokens, and the
prefix tells you what it can do:

- `vw_…` — read the list and subscribe to its live updates.
- `ed_…` — everything above, plus adding, editing, checking, reordering and deleting items.
- `ad_…` — everything above, plus deleting the list and rotating its links.

Pass a token either in the path (`/api/lists/ed_…`) or as `Authorization: Bearer ed_…`
alongside any token in the path. The edit and admin tokens are stored hashed and
are returned **only** in the response that creates the list, so save them at that
moment. An unknown token is a 404; a valid token without the needed capability is
a 403 that names the token you need.

Treat these links like passwords: anyone you send an `ed_` link to can edit the list.

## Quick start

Create a list with a few items:

```bash
curl -sX POST https://streepaf.nl/api/lists \
  -H 'content-type: application/json' \
  -d '{"title":"Boodschappen","emoji":"🛒","items":[{"text":"Melk"},{"text":"Brood"}]}'
```

Add an item to it:

```bash
curl -sX POST https://streepaf.nl/api/lists/ed_YOUR_TOKEN/items \
  -H 'content-type: application/json' \
  -d '{"items":[{"text":"Kaas","quantity":"500 g"}]}'
```

Cross one off, and watch the list change live:

```bash
curl -sX POST https://streepaf.nl/api/lists/ed_YOUR_TOKEN/items/ITEM_ID/check -d '{}'
curl -N https://streepaf.nl/api/lists/vw_YOUR_TOKEN/events
```

## Concepts

- **Items and sections.** A list is one ordered array. A row with `kind: "section"` is a heading; the items under it belong to it until the next heading. Sections cannot be checked.
- **Ordering.** You never send a position. Say `afterId` (an id, or `null` for the top) or `beforeId` when adding or moving, or `PUT /items/order` with every id in the order you want.
- **Versions.** Each list has a `version` that increases on every change. It is the `ETag`, it is the `id` of every live event, and you can send it as `If-Match` to make a write conditional.
- **Live updates.** `GET /api/lists/{token}/events` is a Server-Sent Events stream: `snapshot` on connect, then `list.updated`, `item.created`, `item.updated`, `item.deleted` and `list.deleted`. Reconnect with `Last-Event-ID` and you get a fresh snapshot if you missed anything.
- **Retries.** Send `Idempotency-Key` on a write and a repeat of the same request returns the original response instead of duplicating work.
- **Limits.** 500 items per list, 100 per add call, 500 characters per item, 200 per title.
- **Retention.** A list that nobody opens or changes for 365 days is deleted. Reading it counts as activity, so an active list never expires.
- **Errors.** Failures are `application/problem+json` (RFC 9457) with `title`, `status` and `detail`, plus `errors[]` for validation.

## Endpoints

- `DELETE /api/lists/{token}/items/{itemId}` — Delete an item
- `DELETE /api/lists/{token}` — Delete a list permanently
- `GET /api/lists/{token}/export` — Export a list as markdown, plain text or JSON
- `GET /api/lists/{token}/items/{itemId}` — Read one item
- `GET /api/lists/{token}` — Read a list
- `GET /api/templates/{id}` — Read one template, including its items
- `GET /api/templates` — List the built-in starting points
- `PATCH /api/lists/{token}/items/{itemId}` — Change an item
- `PATCH /api/lists/{token}` — Rename a list or change its description or emoji
- `POST /api/lists/{token}/clear-completed` — Delete every crossed-off item
- `POST /api/lists/{token}/duplicate` — Copy a list into a new one
- `POST /api/lists/{token}/items/check` — Check or uncheck many items at once
- `POST /api/lists/{token}/items/delete` — Delete many items at once
- `POST /api/lists/{token}/items/{itemId}/check` — Cross off an item
- `POST /api/lists/{token}/items/{itemId}/move` — Move an item
- `POST /api/lists/{token}/items/{itemId}/uncheck` — Restore an item
- `POST /api/lists/{token}/items` — Add one or more items
- `POST /api/lists/{token}/rotate` — Issue fresh view or edit links
- `POST /api/lists/{token}/uncheck-all` — Restore every item, keeping the list
- `POST /api/lists` — Create a list
- `PUT /api/lists/{token}/items/order` — Set the order of the whole list

The full machine-readable description is at https://streepaf.nl/openapi.json, rendered at https://streepaf.nl/docs.

## MCP

Streepaf speaks the Model Context Protocol over Streamable HTTP at
`https://streepaf.nl/mcp`. Add it to Claude Code with:

```bash
claude mcp add --transport http streepaf https://streepaf.nl/mcp
```

Tools: `create_list`, `get_list`, `update_list`, `add_items`, `add_text`, `update_item`, `check_items`, `uncheck_items`, `delete_items`, `move_item`, `reorder_items`, `clear_completed`, `uncheck_all`, `duplicate_list`, `export_list`, `delete_list`, `rotate_tokens`, `list_templates`.

Every tool except `create_list` and `list_templates` takes a `token` argument,
because an agent usually works with several lists at once. When you create a
list, give all three links back to the person you are helping.

## Links

- https://streepaf.nl/openapi.json — OpenAPI 3.1 description
- https://streepaf.nl/docs — API reference
- https://streepaf.nl/mcp — MCP endpoint