# Mello

A self-hosted Trello-compatible board server. This file describes how to use it.

## Conventions

- Every HTML page has a JSON twin at the same URL: send `Accept: application/json`
  or add `?format=json`. The HTML is a rendering of that JSON, not a separate story.
- Every view is a URL: filters, sort and the open card live in the query string.
- The API lives under /1/ and speaks Trello's dialect. `GET /1/server` describes it,
  including which capabilities this server has, and lists every path it answers.
- Authentication is a bearer token: `Authorization: Bearer <token>`. Get one with
  `POST /1/tokens` ({username, password}), or from the Account page.
- Cards are addressable by id or by key: /1/cards/WEB-12 is the same card as
  /1/cards/<24 hex characters>. Boards likewise: /1/boards/WEB.
- Live changes: subscribe over the WebSocket at /1/Session/socket?token=…, or poll
  `GET /1/boards/{id}/events?since={ix}`, which returns exactly what you missed.

## Pages

- GET /s/:token — a read-only view of whatever the link was made for
- GET /s/:token/badge.svg — the status badge as an SVG, embeddable in a README
- GET /s/:token/badge.json — the same numbers as JSON, in shields' endpoint shape
- GET / — the flat table when you are signed in; the extension and how to install it when you are not
- GET /download/extension.zip — the browser extension, packaged from the files this server runs beside
- GET /download/tz.zip — the tz command-line client, with the two shared files it imports
- GET /docs — the documents that ship with this server
- GET /docs/:name — one of the documents that ship with this server, rendered
- GET /export.csv — every card the table would show, as CSV — takes the same filters as /
- GET /export.yaml — every card the table would show, as YAML — takes the same filters as /
- GET /boards — your boards, and the form that makes another
- GET /recent — what changed on every board you can see, lately — 48 hours by default, ?hours=24|48|168|720 — as sentences with the card and the board linked
- GET /b/:key — one board as columns of lists, with a form to add a card to each
- GET /c/:key — one card in full: fields, description, checklists, comments and history — a doc card renders as a page (?as=card for the card view). A browser that runs scripts is handed to /app; ?plain=1 stays here
- GET /c/:key/history — every version this card's text has had, what each edit changed, and a way back (?v=<version>)
- GET /c/:key/edit — the full-page Markdown editor over a card's text (works without JavaScript; WYSIWYG on top)
- GET /me — your notifications, your password, and your API tokens
- GET /admin — people, invite links and groups (server admins only)
- GET /loginz — the sign-in form, and the command-line client
- POST /loginz — sign in; sets a session cookie carrying an ordinary token
- POST /logout — sign out, and revoke the session token as you go
- GET /theme — cycle the palette: light, medium, dark
- GET /invite/:token — an invite link: what it grants, and the form that turns it into an account
- POST /invite/:token — accept an invite: pick a username, set a password, and you are in
- POST /boards — create a board
- POST /b/:key/cards — add a card to a list
- POST /b/:key/lists — add a list to a board
- POST /b/:key/invites — mint an invite link to this board
- POST /b/:key/workflow — set the order this board's lists are meant to happen in
- POST /b/:key/keys — show or hide this board's card keys in the table (board admins only)
- POST /b/:key/groups — give a board to a group
- POST /b/:key/groups/:id/remove — take a board back from a group
- POST /b/:key/sharelinks — publish a read-only link, or a badge, for this board
- POST /b/:key/sharelinks/:id/revoke — revoke a share link
- POST /b/:key/webhooks — add a webhook to this board, outbound or inbound
- POST /b/:key/webhooks/:id/delete — delete a webhook
- POST /c/:key — rename a card, set its due date, move it to another list, or turn it into a doc (type)
- POST /c/:key/desc — save a card's description (Markdown)
- POST /c/:key/edit — save the editor's text, or preview it without saving (button name 'preview')
- POST /c/:key/restore — put a card's text back to an earlier version, as a new edit
- POST /c/:key/members — set who is on a card and which labels it carries
- POST /c/:key/attachments — attach a file or a link to a card, from the card page's form
- POST /c/:key/attachments/:id/delete — delete an attachment from a card
- POST /c/:key/comments — comment on a card
- POST /c/:key/checklists — add a checklist to a card
- POST /c/:key/checkitems — add an item to a checklist
- POST /c/:key/checkitem — tick or untick a check item
- POST /c/:key/archive — archive a card, or take it back out
- POST /c/:key/move — move a card to another board (it takes that board's key)
- POST /me/password — change your password
- POST /me/tokens — mint an API token — full for your own clients, or scoped r/rw to boards you pick (shown once)
- POST /me/tokens/:id/revoke — revoke one of your tokens
- POST /me/notifications/read — mark every notification read
- POST /sharelinks/:id/revoke — revoke a share link from the profile or admin page
- POST /admin/invites — mint an invite link
- POST /admin/invites/:id/revoke — revoke an invite link
- POST /admin/users/:id/active — disable or re-enable an account
- POST /admin/groups — create a group
- GET /llms.txt — what this server is and how to drive it, for something that isn't a person
- GET /app — the dashboard — the very client the extension runs, served from here
- GET /app/:name — the dashboard's own files, the ones the extension is made of

## API

- GET /1/server — what this server is, what it can do, and every path it answers
- GET /1/members/me — the user this token belongs to
- GET /1/members — every account on this server (server admins only)
- GET /1/members/:id — one member by id
- POST /1/tokens — log in (username + password → full token), or mint a scoped token while authenticated
- GET /1/tokens — every token you hold, without the secrets
- DELETE /1/tokens/:id — revoke one of your tokens
- GET /1/boards/:id/tokens — the service tokens this board owns (board admins only)
- POST /1/boards/:id/tokens — mint a service token for a board — r or rw, owned by the board, shown once
- DELETE /1/boards/:id/tokens/:tokenId — revoke a board's service token, and retire the account behind it
- GET /1/organizations/:id/tokens — the service tokens this workspace owns (workspace admins only)
- POST /1/organizations/:id/tokens — mint a service token for a workspace — reaches every board in it, shown once
- DELETE /1/organizations/:id/tokens/:tokenId — revoke a workspace's service token, and retire the account behind it
- GET /1/members/me/boards — every board you can see, for the pickers
- GET /1/boards/:id — one board with its lists, cards, members and labels — by id or by key
- GET /1/boards/:id/actions — everything that happened on a board, newest first — comments and changes alike; ?since= an ISO date for the recent part
- GET /1/boards/:id/lists — the lists on a board
- POST /1/boards — create a board (it gets a key, six labels and three lists)
- PUT /1/boards/:id — rename a board, recolour it, close it, change its key, or move it between workspaces
- GET /1/boards/:id/groups — the groups this board is shared to (board admins only)
- PUT /1/boards/:id/groups — share a board to a whole group at once
- DELETE /1/boards/:id/groups/:groupId — take a board back from a group
- PUT /1/boards/:id/members — give someone a role on a board
- POST /1/lists — add a list to a board
- PUT /1/lists/:id — rename, move, archive or recolour a list
- POST /1/labels — add a label to a board
- PUT /1/labels/:id — rename or recolour a label
- DELETE /1/labels/:id — delete a label, and take it off every card that had it
- POST /1/organizations — create a workspace to group boards under
- GET /1/organizations/:id — one workspace
- GET /1/organizations — every workspace you can see, with your role and its open boards
- PUT /1/organizations/:id — rename a workspace (its admins only)
- DELETE /1/organizations/:id — delete an empty workspace (its admins only)
- GET /1/organizations/:id/members — who holds a seat in a workspace, and as what
- PUT /1/organizations/:id/members — give someone a seat in a workspace, and with it all its boards
- DELETE /1/organizations/:id/members/:username — take someone's seat in a workspace away
- GET /1/cards/:id — one card in full — by id or by key (FOO-12)
- POST /1/cards — create a card
- PUT /1/cards/:id — change a card: name, desc, due, dates, members, labels, list, board, archive, type (card|doc), pos (top|bottom|float) or ordinal (put it Nth in its list)
- DELETE /1/cards/:id — delete a card for good, attachments and all (board admins only)
- GET /1/cards/:id/actions — a card's comments and its change history, newest first
- POST /1/cards/:id/actions/comments — comment on a card
- GET /1/cards/:id/checklists — a card's checklists and their items
- POST /1/cards/:id/checklists — add a checklist to a card
- PUT /1/cards/:id/checkItem/:itemId — tick, rename, move, assign or date a check item
- DELETE /1/cards/:id/checkItem/:itemId — delete a check item
- GET /1/members/me/cards — every card assigned to you, everywhere
- GET /1/checklists/:id — one checklist and its items
- POST /1/checklists/:id/checkItems — add an item to a checklist
- PUT /1/checklists/:id — rename a checklist
- DELETE /1/checklists/:id — delete a checklist and everything on it
- GET /1/cards/:id/attachments — a card's attachments
- POST /1/cards/:id/attachments — attach a file (multipart form-data, or the raw bytes with ?name=) or a url
- GET /1/cards/:id/attachments/:aid — one attachment's details
- GET /1/cards/:id/attachments/:aid/download — the attachment's bytes, with the mime type it was stored under
- DELETE /1/cards/:id/attachments/:aid — delete an attachment, bytes and all
- GET /1/boards/:id/sharelinks — the share links on a board (board admins only)
- GET /1/sharelinks — every share link you have published — or, with ?scope=all, every one on the server
- POST /1/sharelinks — mint a share link for a board, list or card
- DELETE /1/sharelinks/:id — revoke a share link
- GET /1/boards/:id/webhooks — the webhooks on a board, in and out (board admins only)
- POST /1/webhooks — register a webhook — outbound (url, format, filter) or inbound (a token to post to)
- PUT /1/webhooks/:id — turn a webhook off or back on
- DELETE /1/webhooks/:id — delete a webhook
- POST /1/hooks/in/:token — file a card (or a comment) through an inbound hook's token
- PUT /1/mirror/boards/:sourceId — mirror a board in from elsewhere: PUT the board-detail payload, idempotently
- GET /1/mirror/boards — the boards on this server that are mirrors of somewhere else
- GET /1/mirror/boards/:sourceId/map — far-side card id → the id it has here, for finishing a move
- PUT /1/mirror/cards/:sourceId/extras — mirror a card's comments, checklists and attachments in, idempotently
- POST /1/mirror/boards/:sourceId/detach — adopt a mirrored board as this server's own (what makes a move a move)
- GET /1/actions/:id — one action — a comment, or one entry of the change history
- PUT /1/actions/:id — edit a comment you wrote
- PUT /1/actions/:id/text — edit a comment you wrote (Trello's spelling)
- DELETE /1/actions/:id — delete a comment you wrote
- GET /1/search — search every board you can see: due:week, @me, label:red, is:archived, -negation
- GET /1/batch — several GETs in one request, split before decoded so a sub-path may contain commas
- GET /1/members/me/notifications — what happened while you were away
- GET /1/members/me/notifications/unread — how many of those you haven't read
- PUT /1/notifications/:id — mark one notification read, or unread again
- POST /1/members/me/notifications/read — mark everything read
- GET /1/boards/:id/events — everything that changed on a board after an index — the socket's catch-up twin
- GET /1/invites — live invite links — all of them for a server admin, one subject's with ?board= or ?organization=
- POST /1/invites — mint an invite link — to this server, a board, or an organization
- DELETE /1/invites/:id — revoke an invite link
- GET /1/groups — every group on this server, with who is in it
- POST /1/groups — create a group (server admins only)
- PUT /1/groups/:id/members — put someone in a group (server admins only)
- DELETE /1/groups/:id/members/:username — take someone out of a group (server admins only)
- PUT /1/members/:id — disable or re-enable an account (server admins only)