Split API docs into per-resource sections under docs/api/

docs/api/README.md

@@ -0,0 +1,148 @@
+# Fizzy API
+
+Fizzy has an API that allows you to integrate your application with it or to create
+a bot to perform various actions for you.
+
+## API Endpoints
+
+- [Authentication](sections/authentication.md)
+- [Identity](sections/identity.md)
+- [Account](sections/account.md)
+- [Boards](sections/boards.md)
+- [Columns](sections/columns.md)
+- [Cards](sections/cards.md)
+- [Pins](sections/pins.md)
+- [Steps](sections/steps.md)
+- [Comments](sections/comments.md)
+- [Reactions](sections/reactions.md)
+- [Tags](sections/tags.md)
+- [Users](sections/users.md)
+- [Notifications](sections/notifications.md)
+- [Rich Text](sections/rich_text.md)
+- [Webhooks](sections/webhooks.md)
+
+## Authentication
+
+There are two ways to authenticate with the Fizzy API:
+
+1. **Personal access tokens** - Long-lived tokens for scripts and integrations
+2. **Magic link authentication** - Session-based authentication for native apps
+
+Read the [authentication guide](sections/authentication.md) to get started.
+
+## Caching
+
+Most endpoints return [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag) and [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) headers. You can use these to avoid re-downloading unchanged data.
+
+### Using ETags
+
+When you make a request, the response includes an `ETag` header:
+
+```
+HTTP/1.1 200 OK
+ETag: "abc123"
+Cache-Control: max-age=0, private, must-revalidate
+```
+
+On subsequent requests, include the ETag value in the `If-None-Match` header:
+
+```
+GET /1234567/cards/42.json
+If-None-Match: "abc123"
+```
+
+If the resource hasn't changed, you'll receive a `304 Not Modified` response with no body, saving bandwidth and processing time:
+
+```
+HTTP/1.1 304 Not Modified
+ETag: "abc123"
+```
+
+If the resource has changed, you'll receive the full response with a new ETag.
+
+__Example in Ruby:__
+
+```ruby
+# Store the ETag from the response
+etag = response.headers["ETag"]
+
+# On next request, send it back
+headers = { "If-None-Match" => etag }
+response = client.get("/1234567/cards/42.json", headers: headers)
+
+if response.status == 304
+  # Nothing to do, the card hasn't changed
+else
+  # The card has changed, process the new data
+end
+```
+
+## Error Responses
+
+When a request fails, the API response will communicate the source of the problem through the HTTP status code.
+
+| Status Code | Description |
+|-------------|-------------|
+| `400 Bad Request` | The request was malformed or missing required parameters |
+| `401 Unauthorized` | Authentication failed or access token is invalid |
+| `403 Forbidden` | You don't have permission to perform this action |
+| `404 Not Found` | The requested resource doesn't exist or you don't have access to it |
+| `422 Unprocessable Entity` | Validation failed (see error response format above) |
+| `500 Internal Server Error` | An unexpected error occurred on the server |
+
+If a request contains invalid data for fields, such as entering a string into a number field, in most cases the API will respond with a `500 Internal Server Error`. Clients are expected to perform some validation on their end before making a request.
+
+A validation error will produce a `422 Unprocessable Entity` response, which will sometimes be accompanied by details about the error:
+
+```json
+{
+  "avatar": ["must be a JPEG, PNG, GIF, or WebP image"]
+}
+```
+
+## Pagination
+
+All endpoints that return a list of items are paginated. The page size can vary from endpoint to endpoint,
+and we use a dynamic page size where initial pages return fewer results than later pages.
+
+If there are more results to fetch, the response will include a `Link` header with a `rel="next"` link to the next page of results:
+
+```bash
+curl -H "Authorization: Bearer put-your-access-token-here" -H "Accept: application/json" -v http://fizzy.localhost:3006/686465299/cards
+# ...
+< link: <http://fizzy.localhost:3006/686465299/cards?page=2>; rel="next"
+# ...
+```
+
+## List parameters
+
+When an endpoint accepts a list of values as a parameter, you can provide multiple values by repeating the parameter name:
+
+```
+?tag_ids[]=tag1&tag_ids[]=tag2&tag_ids[]=tag3
+```
+
+List parameters always end with `[]`.
+
+## File Uploads
+
+Some endpoints accept file uploads. To upload a file, send a `multipart/form-data` request instead of JSON.
+You can combine file uploads with other parameters in the same request.
+
+__Example using curl:__
+
+```bash
+curl -X PUT \
+  -H "Authorization: Bearer put-your-access-token-here" \
+  -F "user[name]=David H. Hansson" \
+  -F "user[avatar]=@/path/to/avatar.jpg" \
+  http://fizzy.localhost:3006/686465299/users/03f5v9zjw7pz8717a4no1h8a7
+```
+
+## Rich Text Fields
+
+Some fields accept rich text content. These fields accept HTML input, which will be sanitized to remove unsafe tags and attributes.
+
+See the [rich text guide](sections/rich_text.md) for more information, including how to attach files to rich text fields using the direct upload flow.
+
+

docs/api/sections/account.md

@@ -0,0 +1,65 @@
+# Account
+
+## `GET /account/settings`
+
+Returns the current account.
+
+__Response:__
+
+```json
+{
+  "id": "03f5v9zjvypwh0t0e2rfh0h7k",
+  "name": "37signals",
+  "cards_count": 5,
+  "created_at": "2025-12-05T19:36:35.401Z",
+  "auto_postpone_period_in_days": 30
+}
+```
+
+The `auto_postpone_period_in_days` is the account-level default in days (e.g. `30`). Cards are automatically moved to "Not Now" after this period of inactivity. Each board can override this with its own value.
+
+## `PUT /account/entropy`
+
+Updates the account-level default auto close period. Requires admin role.
+
+__Request:__
+
+```json
+{
+  "entropy": {
+    "auto_postpone_period_in_days": 30
+  }
+}
+```
+
+__Response:__
+
+Returns the account object:
+
+```json
+{
+  "id": "03f5v9zjvypwh0t0e2rfh0h7k",
+  "name": "37signals",
+  "cards_count": 5,
+  "created_at": "2025-12-05T19:36:35.401Z",
+  "auto_postpone_period_in_days": 30
+}
+```
+
+## `PUT /:account_slug/boards/:board_id/entropy`
+
+Updates the auto close period for a specific board. Requires board admin permission.
+
+__Request:__
+
+```json
+{
+  "board": {
+    "auto_postpone_period_in_days": 90
+  }
+}
+```
+
+__Response:__
+
+Returns the board object.

docs/api/sections/authentication.md

@@ -0,0 +1,172 @@
+# Authentication
+
+There are two ways to authenticate with the Fizzy API:
+
+1. **Personal access tokens** - Long-lived tokens for scripts and integrations
+2. **Magic link authentication** - Session-based authentication for native apps
+
+## Personal Access Tokens
+
+To use the API you'll need an access token. To get one, go to your profile, then,
+in the API section, click on "Personal access tokens" and then click on
+"Generate new access token".
+
+Give it a description and pick what kind of permission you want the access token to have:
+- `Read`: allows reading data from your account
+- `Read + Write`: allows reading and writing data to your account on your behalf
+
+Then click on "Generate access token".
+
+<details>
+  <summary>Access token generation guide with screenshots</summary>
+
+  | Step | Description | Screenshot |
+  |:----:|-------------|:----------:|
+  | 1 | Go to your profile | <img width="400" alt="Profile page with API section" src="https://github.com/user-attachments/assets/49e7e12b-2952-4220-84fd-cef99b13bc04" /> |
+  | 2 | In the API section click on "Personal access token" | <img width="400" alt="Personal access tokens page" src="https://github.com/user-attachments/assets/2f026ea0-416f-4fbe-a097-61313f24f180" /> |
+  | 3 | Click on "Generate a new access token" | <img width="400" alt="Generate new access token dialog" src="https://github.com/user-attachments/assets/d766f047-8628-416d-8e21-b89522f6c0d9" /> |
+  | 4 | Give it a description and assign it a permission | <img width="400" alt="Access token created" src="https://github.com/user-attachments/assets/49b8e350-d152-4946-8aad-e13260b983fd" /> |
+</details>
+
+> [!IMPORTANT]
+> __An access token is like a password, keep it secret and do not share it with anyone.__
+> Any person or application that has your access token can perform actions on your behalf.
+
+To authenticate a request using your access token, include it in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer put-your-access-token-here" -H "Accept: application/json" https://app.fizzy.do/my/identity
+```
+
+## Magic Link Authentication
+
+For native apps, you can authenticate users via magic links. This is a two-step process:
+
+### 1. Request a magic link
+
+Send the user's email address to request a magic link be sent to them:
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d '{"email_address": "user@example.com"}' \
+  https://app.fizzy.do/session
+```
+
+__Response:__
+
+```
+HTTP/1.1 201 Created
+Set-Cookie: pending_authentication_token=...; HttpOnly; SameSite=Lax
+```
+
+```json
+{
+  "pending_authentication_token": "eyJfcmFpbHMi..."
+}
+```
+
+The response includes a `pending_authentication_token` both in the JSON body and as a cookie.
+Native apps should store this token and include it as a cookie when submitting the magic link code.
+
+__Error responses:__
+
+| Status Code | Description |
+|--------|-------------|
+| `422 Unprocessable entity` | Invalid email address, if sign ups are enabled and the value isn't a valid email address |
+| `429 Too Many Requests` | Rate limit exceeded |
+
+### 2. Submit the magic link code
+
+Once the user receives the magic link email, they'll have a 6-character code. Submit it to complete authentication:
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -H "Cookie: pending_authentication_token=eyJfcmFpbHMi..." \
+  -d '{"code": "ABC123"}' \
+  https://app.fizzy.do/session/magic_link
+```
+
+__Response:__
+
+```json
+{
+  "session_token": "eyJfcmFpbHMi..."
+}
+```
+
+The `session_token` can be used to authenticate subsequent requests by including it as a cookie:
+
+```bash
+curl -H "Cookie: session_token=eyJfcmFpbHMi..." \
+  -H "Accept: application/json" \
+  https://app.fizzy.do/my/identity
+```
+
+__Error responses:__
+
+| Status Code | Description |
+|--------|-------------|
+| `401 Unauthorized` | Invalid `pending_authentication_token` or `code` |
+| `429 Too Many Requests` | Rate limit exceeded |
+
+
+### Delete server-side session (_log out_)
+
+To log out and destroy the server-side session:
+
+```bash
+curl -X DELETE \
+  -H "Accept: application/json" \
+  -H "Cookie: session_token=eyJfcmFpbHMi..." \
+  https://app.fizzy.do/session
+```
+
+__Response:__
+
+Returns `204 No Content` on success.
+
+### Create an access token via the API
+
+You can programmatically create a personal access token using either a session cookie or an existing Bearer token:
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -H "Cookie: session_token=eyJfcmFpbHMi..." \
+  -d '{"access_token": {"description": "Fizzy CLI", "permission": "write"}}' \
+  https://app.fizzy.do/1234567/my/access_tokens
+```
+
+Or with a Bearer token (must have `write` permission):
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -H "Authorization: Bearer put-your-access-token-here" \
+  -d '{"access_token": {"description": "Fizzy CLI", "permission": "write"}}' \
+  https://app.fizzy.do/1234567/my/access_tokens
+```
+
+The `permission` field accepts `read` or `write`.
+
+__Response:__
+
+```
+HTTP/1.1 201 Created
+```
+
+```json
+{
+  "token": "4f9Q6d2wXr8Kp1Ls0Vz3BnTa",
+  "description": "Fizzy CLI",
+  "permission": "write"
+}
+```
+
+Store the `token` value securely — it won't be retrievable again. Use it as a Bearer token for subsequent API requests.