The public roadmap API

Open the board's Public view, then Customize → API, and make a key. Anyone who can change the public roadmap can make keys for it, and a board can have up to 10.

A roadmap key is publishable: it starts with acta_pk_ and can sit in a web page's code where anyone can read it, as it reaches only what the page shows anyway. Rotate swaps it for a new one when it's been passed around too far, and Revoke stops it working at once.

Send it as a bearer token, an X-Acta-Key header, or ?key=:

curl https://acta.aaenz.no/api/roadmap/v1/tasks -H "Authorization: Bearer acta_pk_..."

The roadmap has to be public. While it's private, calls answer 404.

By default any site can call a key from a browser. List your own sites on the key, like https://yourco.com, and browsers on other sites are turned away. Calls from servers, which send no Origin, still work.

GET /tasks takes these, all optional:

• stage: planned, progress or shipped, or several with commas.
• project and label: only tasks with that project or label.
• q: words in the title or description.
• sort: position, the page's own order, or votes, newest, shipped or due.
• limit, up to 200 and 100 by default, and offset, to page through them. The answer's total counts every match.

GET /ideas takes sort: top or new.

Each task has its id, title, description in Markdown, status, stage and the stage's name on the page. Its project, labels, dates, subtask progress, votes and who's on it come where the page shows them. With Time to ship on, shipped tasks also have opened, closed and time_to_close, both in seconds and as words like “3 days”.

Votes and ideas work as they do on the page, and only where it takes them. Each needs a visitor: your site's own id for the person, 8 to 64 letters, numbers and hyphens, kept the same for them each time so they count once. A signed-in user's id works well, and a random one kept in their browser works too. Acta keeps it only as a hash, and apart from the visitors of the page itself.

curl https://acta.aaenz.no/api/roadmap/v1/tasks/ACT-12/vote \
  -H "Authorization: Bearer acta_pk_..." -H "Content-Type: application/json" \
  -d '{"visitor": "user-48213", "on": true}'

Votes answer with the new count. Each visitor can send 10 ideas a day, and each board takes 300. Send visitor with a read too, and each task and idea says whether they've voted for it.

Each key takes 240 reads and 30 votes or ideas a minute from each address. Past that, calls answer 429 with a Retry-After header in seconds. Reads without a visitor can be kept for 30 seconds.

• 200: the answer as JSON. 201: a new idea.
• 400: a mistake the caller can fix, with an error saying what to change.
• 401: the key is missing, or was rotated or revoked.
• 403: a site the key doesn't list, or a roadmap that doesn't take ideas.
• 404: no such task or idea, a roadmap that isn't public, or one that doesn't take votes.
• 429: too many calls. Wait for Retry-After.

Every public roadmap also has a read-only feed at /api/public/<workspace>/<board>, open to anyone, with all of the page's tasks and ideas in one answer.