# MNW -- API Reference

Public JSON API endpoints. All write routes require authentication via session cookie or JWT.

Rate limits: write routes (burst 10, 2/sec per IP), export routes (burst 3, 1/sec per IP).

HTMX responses return HTML fragments; non-HTMX requests get JSON.

---

## Projects

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/projects | Create a new project |
| GET | /api/projects | List all projects for the authenticated user |
| PUT | /api/projects/{id} | Update a project |
| DELETE | /api/projects/{id} | Delete a project |

## Git Repos

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/repos | Create a bare git repo on disk |
| POST | /api/projects/{id}/repos | Link a repo to a project |
| DELETE | /api/projects/{id}/repos/{name} | Unlink a repo from a project |
| PUT | /api/repos/{id}/visibility | Update repo visibility |

## Items

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/projects/{id}/items | Create a new item |
| PUT | /api/items/{id} | Update an item |
| DELETE | /api/items/{id} | Delete an item |
| POST | /api/items/{id}/duplicate | Duplicate an item as a new draft |
| PUT | /api/items/{id}/move | Reorder an item within its project |

### Bulk Operations

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/items/bulk/publish | Publish multiple items |
| POST | /api/items/bulk/unpublish | Unpublish multiple items |
| POST | /api/items/bulk/delete | Delete multiple items |

### Tags

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/items/{id}/tags | Add a tag to an item |
| DELETE | /api/items/{id}/tags/{tag_id} | Remove a tag from an item |
| PUT | /api/items/{id}/primary-tag | Set the primary tag |
| GET | /api/tags/search | Typeahead tag search |
| GET | /api/items/{id}/tag-suggestions | Suggest tags for an item |

### Bundles

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/items/{id}/bundle/add | Add a child item to a bundle |
| DELETE | /api/items/{id}/bundle/{child_id} | Remove a child from a bundle |
| PUT | /api/items/{id}/bundle/{child_id}/listed | Toggle child visibility |

### Text Content

| Method | Path | Description |
|--------|------|-------------|
| PUT | /api/items/{id}/text | Save or update text body content |

### Chapters

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/items/{id}/chapters | List chapters for an item |
| POST | /api/items/{id}/chapters | Create a chapter marker |
| PUT | /api/chapters/{id} | Update a chapter |
| DELETE | /api/chapters/{id} | Delete a chapter |

### Versions

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/items/{id}/versions | List versions for an item |
| POST | /api/items/{id}/versions | Create a new version |

## Blog

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/projects/{id}/blog | Create a blog post |
| GET | /api/projects/{id}/blog | List blog posts for a project |
| GET | /api/blog/{id} | Get a blog post (includes markdown body) |
| PUT | /api/blog/{id} | Update a blog post |
| DELETE | /api/blog/{id} | Delete a blog post |

## Collections

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/collections | Create a collection |
| PUT | /api/collections/{id} | Update a collection |
| DELETE | /api/collections/{id} | Delete a collection |
| POST | /api/collections/{id}/items/{item_id} | Add an item to a collection |
| DELETE | /api/collections/{id}/items/{item_id} | Remove an item from a collection |
| PUT | /api/collections/{id}/items/reorder | Reorder items |
| GET | /api/collections/for-item/{item_id} | Collections containing an item |

## License Keys

### Creator Endpoints (auth required)

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/items/{id}/license-settings | Configure license key settings |
| GET | /api/items/{id}/keys | List keys for an item |
| POST | /api/items/{id}/keys | Generate a new key |
| POST | /api/keys/{id}/revoke | Revoke a key |

### Public Endpoints (rate-limited, stable API contract)

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/keys/validate | Validate and optionally activate a key |
| POST | /api/keys/deactivate | Release an activation slot |
| GET | /api/keys/{code}/status | Check key status |

## Promo Codes

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/promo-codes | Create a promo code |
| GET | /api/promo-codes | List promo codes |
| DELETE | /api/promo-codes/{id} | Delete a promo code |
| POST | /api/promo-codes/claim | Claim a free_access promo code (buyer endpoint) |

## Subscription Tiers

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/projects/{id}/tiers | Create a subscription tier |
| GET | /api/projects/{id}/tiers | List tiers for a project |
| PUT | /api/tiers/{id} | Update a tier |
| DELETE | /api/tiers/{id} | Delete a tier |

## Follows

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/follow/{type}/{id} | Follow a user or project |
| DELETE | /api/follow/{type}/{id} | Unfollow a user or project |

## Custom Links

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/links | Create a profile link |
| PUT | /api/links/{id} | Update a link |
| DELETE | /api/links/{id} | Delete a link |
| PUT | /api/links/reorder | Reorder all links |

## Labels

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/labels | List all available labels |
| GET | /api/projects/{id}/labels | Get labels for a project |
| POST | /api/projects/{id}/labels | Add a label to a project |
| DELETE | /api/projects/{id}/labels/{label_id} | Remove a label from a project |

## Categories

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/categories | Create a category |
| GET | /api/categories/search | Search categories (typeahead) |

## Custom Domains

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/domains | Add a custom domain |
| POST | /api/domains/verify | Trigger DNS TXT verification |
| DELETE | /api/domains/{id} | Remove a custom domain |

## Content Insertions

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/users/me/insertions/presign | Get presigned upload URL |
| POST | /api/users/me/insertions/confirm | Confirm upload |
| GET | /api/users/me/insertions | List insertions |
| PUT | /api/insertions/{id} | Rename an insertion |
| DELETE | /api/insertions/{id} | Delete an insertion |
| POST | /api/items/{id}/insertions | Place an insertion in an item |
| DELETE | /api/item-insertions/{id} | Remove a placement |
| GET | /api/items/{id}/insertions | List placements for an item |

## Exports

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/export/projects | Export projects + items as JSON |
| POST | /api/export/sales | Export sales as CSV |
| POST | /api/export/purchases | Export purchases as CSV |
| POST | /api/export/followers | Export followers as CSV |
| POST | /api/export/content | Export content files as ZIP |

## User Account

| Method | Path | Description |
|--------|------|-------------|
| PUT | /api/users/me | Update display name and bio |
| PUT | /api/users/me/password | Change password |
| PUT | /api/users/me/preferences | Update notification preferences |
| PUT | /api/users/me/stripe-tax | Toggle Stripe tax collection |
| DELETE | /api/users/me | Delete account |
| DELETE | /api/users/me/stripe | Disconnect Stripe Connect |
| POST | /api/users/me/appeal | Submit suspension appeal |
| POST | /api/resend-verification | Resend verification email |
| POST | /api/account/request-deletion | Request account deletion with data export |

### Sessions

| Method | Path | Description |
|--------|------|-------------|
| DELETE | /api/users/me/sessions/{id} | Revoke a session |
| DELETE | /api/users/me/sessions | Revoke all other sessions |

### SSH Keys

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/users/me/ssh-keys | List SSH keys |
| POST | /api/users/me/ssh-keys | Add an SSH key |
| DELETE | /api/users/me/ssh-keys/{id} | Delete an SSH key |

### TOTP (2FA)

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/users/me/totp/setup | Generate TOTP secret and QR code |
| POST | /api/users/me/totp/confirm | Verify first code and enable 2FA |
| POST | /api/users/me/totp/disable | Disable 2FA |
| POST | /api/users/me/totp/backup-codes | Regenerate backup codes |
| GET | /api/users/me/totp/status | Get 2FA status |

### Passkeys (WebAuthn)

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/users/me/passkeys/register/start | Start passkey registration |
| POST | /api/users/me/passkeys/register/finish | Finish passkey registration |
| GET | /api/users/me/passkeys | List passkeys |
| PUT | /api/users/me/passkeys/{id} | Rename a passkey |
| DELETE | /api/users/me/passkeys/{id} | Delete a passkey |

## Library

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/library/add/{item_id} | Add to library |
| DELETE | /api/library/remove/{item_id} | Remove from library |

## Miscellaneous

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/reports | Submit a content report |
| POST | /api/broadcast | Send broadcast to followers |
| POST | /api/waitlist/apply | Join the platform waitlist |
| POST | /api/invites/create | Create an invite code |
| POST | /api/validate/project-slug | Check project slug availability |
| POST | /api/validate/collection-slug | Check collection slug availability |
| POST | /api/validate/blog-slug | Check blog slug availability |
| POST | /api/email-signup | Subscribe to newsletter (public, no auth) |
| GET | /api/restart-status | Check pending service restart (public, no auth) |

---

## Internal API

Service-to-service endpoints under `/api/internal/` are authenticated via `ServiceAuth` bearer token. Used by mnw-cli for creator operations, git authorization, and file uploads. Not listed here — see `src/routes/api/internal.rs` for the full surface.

## SyncKit API

SyncKit endpoints under `/api/synckit/` handle cloud sync, device management, and blob operations. Authenticated via SyncKit JWT. See `src/routes/synckit.rs`.

## OTA API

OTA update endpoints under `/api/ota/` serve release metadata and presigned download URLs. See `src/routes/ota.rs`.