API
DecideNext exposes a token-authenticated HTTP API so an external AI agent or script can manage a single prioritization table — reading and updating initiatives, voters, and results without going through the dashboard UI by hand.
Blind mode
New tables and retro boards start with results_hidden: true. While hidden, voters and the public link see no ranks, scores or vote counts, and retro voters see only their own cards. Your token always sees live results. Reveal with PUT /table (or PUT /retro/board) and {"results_hidden": false}; send true to hide them again.
Join link
Instead of adding voters one by one, turn on a single join link with PUT /join-link and {"enabled": true} (or PUT /retro/join-link for a board). The table and board responses then carry join_enabled and join_url. People who open the link type their name and become ordinary voters, listed by GET /users. Joining stops at 100 voters, and each name can be used once per session. Send {"enabled": false} to pause the link and keep its URL, or POST /join-link/reset to replace it: the old link stops working at once. While the link is off, join_url is null (and left out of board responses).
Brainstorm boards
A brainstorm is a retro board with board_type IDEAS (Prompt + Ideas) or REVERSE (Reverse brainstorming), so the Retrospective API below manages it. Its board responses add prompt, phase (WRITE, VOTE or RESULTS), silent_writing, and timer_ends_at while a countdown runs. Every board response also carries server_time.
Move the phase in any direction with PUT /retro/board and {"phase": "VOTE"}; ideas and votes are kept. {"timer_minutes": 5} starts a display-only countdown of 1-60 minutes and 0 clears it; any phase change clears it too. Show the time left as timer_ends_at minus server_time, not the device clock. results_hidden follows the phase (true in Write and Vote, false in Results) and cannot be set: sending it returns 400 validation_error, as do phase, prompt, silent_writing and timer_minutes on a retro board.
- Participants add ideas only in Write. Adding one in Vote or Results returns
409 writing_closed. - Participants vote only in Vote and see no vote counts until Results. Voting at any other time returns
409 voting_not_open. - Exporting from a brainstorm with more than one column tags each new initiative with its column's name: a sub-prompt, or a Reverse brainstorming column.
- Your token always sees every idea with live counts. A brainstorm's participant links and join link open
/login/brainstorm-voter/and/brainstorm/join/.
Authentication
Every request is authenticated with a bearer token. The token identifies the table, so there is no key or ID in the URL.
Authorization: Bearer dnx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxBase URL:
https://decidenext.app/api/v1Getting a token
- Open your manager dashboard and go to the API Access tab.
- Click Generate token and re-enter your manager password. The token (
dnx_live_…) is shown only once — copy it immediately. - Each table has one token at a time. It expires after 90 days; generate a new one from the dashboard when it does.
Rate limit
Each token is limited to 10 requests per minute. Exceeding it returns a 429 status with a Retry-After header indicating how many seconds to wait before retrying.
Errors
Errors return the matching HTTP status and a JSON body with an error code and a human-readable message:
{ "error": "not_found", "message": "Initiative not found" }400 validation_error— the request body failed validation.401 unauthorized/401 token_expired— missing/invalid token, or a token past its 90-day expiry.404 not_found— the resource does not exist in this table.429 rate_limited— rate limit exceeded; see Retry-After.
Endpoints
All paths are relative to the base URL above (e.g. GET /api/v1/table).
Table
| GET | /table | Table details |
| PUT | /table | Update name, description, or budget |
Criteria
| GET | /criteria | Weighted Decision Matrix criteria |
Initiatives
| GET | /initiatives | List initiatives |
| POST | /initiatives | Create an initiative |
| GET | /initiatives/{id} | Get a single initiative |
| PUT | /initiatives/{id} | Update an initiative |
| DELETE | /initiatives/{id} | Delete an initiative |
| PUT | /initiatives/reorder | Reorder initiatives |
| POST | /initiatives/bulk | Bulk import initiatives |
Comments
| GET | /initiatives/{id}/comments | List comments on an initiative |
| POST | /initiatives/{id}/comments | Add a comment to an initiative |
Voters
| GET | /users | List voters |
| POST | /users | Add a voter |
| DELETE | /users/{id} | Remove a voter |
| PUT | /voter-password | Set or update the voter password |
Results & progress
| GET | /results | Calculated results |
| GET | /voter-rankings | Per-voter rankings |
| GET | /progress | Voting progress |
Sharing & backup
| PUT | /public-share | Toggle the public results URL |
| PUT | /join-link | Turn the join link on or off |
| POST | /join-link/reset | Replace the join link with a new one |
| GET | /backup | Full table export |
Not available to tokens: deleting the table and managing tokens. Those actions stay dashboard-only, so a leaked or misbehaving token can never destroy the table or mint/revoke other tokens.
Quick start with curl
Read the table
curl https://decidenext.app/api/v1/table \
-H "Authorization: Bearer dnx_live_xxx"Create an initiative
curl -X POST https://decidenext.app/api/v1/initiatives \
-H "Authorization: Bearer dnx_live_xxx" \
-H "Content-Type: application/json" \
-d '{"title": "Launch onboarding revamp", "description": "Q4 priority"}'Bulk import
curl -X POST https://decidenext.app/api/v1/initiatives/bulk \
-H "Authorization: Bearer dnx_live_xxx" \
-H "Content-Type: application/json" \
-d '{"initiatives": [{"title": "A"}, {"title": "B"}]}'Request & response examples
Payloads below are accurate to the API's data model. Optional fields are omitted when empty. For the complete schema of every endpoint, see the OpenAPI spec.
/tableGet table details
Response (200 OK)
{
"id": "2c9d1e7a-1f3b-4a2c-9f1e-8b7a6c5d4e3f",
"name": "Q4 Roadmap",
"description": "Candidate initiatives for next quarter",
"methodology": "ICE",
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-20T14:05:00Z",
"is_active": true,
"has_voter_password": false,
"public_share_enabled": false,
"join_enabled": false,
"join_url": null
}/initiativesList initiatives
Returns an array of initiatives, each with a live comment count.
Response (200 OK)
[
{
"id": "7f1e2d3c-4b5a-6978-8c7d-6e5f4a3b2c1d",
"title": "Launch onboarding revamp",
"description": "Q4 priority",
"tags": ["growth", "onboarding"],
"display_order": 1,
"status": "active",
"created_at": "2026-01-16T08:00:00Z",
"updated_at": "2026-01-16T08:00:00Z",
"comment_count": 2
}
]/initiativesCreate an initiative
Only title is required. Tags are optional; Buy a Feature tables also accept buyafeature_cost.
Request body
{
"title": "Launch onboarding revamp",
"description": "Q4 priority",
"tags": ["growth", "onboarding"]
}Response (201 Created)
{
"id": "7f1e2d3c-4b5a-6978-8c7d-6e5f4a3b2c1d",
"title": "Launch onboarding revamp",
"description": "Q4 priority",
"tags": ["growth", "onboarding"],
"display_order": 1,
"status": "active",
"created_at": "2026-01-16T08:00:00Z",
"updated_at": "2026-01-16T08:00:00Z",
"comment_count": 0
}/initiatives/{id}Update an initiative
Send only the fields you want to change. status is "active" or "archived".
Request body
{
"title": "Launch onboarding revamp v2",
"status": "active"
}Response (200 OK)
{
"id": "7f1e2d3c-4b5a-6978-8c7d-6e5f4a3b2c1d",
"title": "Launch onboarding revamp v2",
"description": "Q4 priority",
"tags": ["growth", "onboarding"],
"display_order": 1,
"status": "active",
"created_at": "2026-01-16T08:00:00Z",
"updated_at": "2026-01-21T11:15:00Z",
"comment_count": 0
}/initiatives/bulkBulk import initiatives
Up to 50 at once. Titles that already exist (case-insensitive) are skipped.
Request body
{
"initiatives": [
{ "title": "Improve search relevance", "tags": ["search"] },
{ "title": "Dark mode" }
]
}Response (201 Created)
{
"imported": 1,
"skipped": 1,
"skipped_titles": ["Dark mode"]
}/usersAdd a voter
name is required; email is optional. The response includes the voter’s unique voting URL.
Request body
{
"name": "Alex",
"email": "alex@example.com"
}Response (201 Created)
{
"id": "11111111-2222-4333-8444-555555555555",
"name": "Alex",
"email": "alex@example.com",
"access_token": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"voter_url": "https://decidenext.app/vote/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"has_voted": false,
"created_at": "2026-01-16T09:00:00Z"
}/voter-passwordSet or update the voter password
A single table-wide password (minimum 6 characters) shared by all voters.
Request body
{
"password": "team-secret-2026"
}Response (200 OK)
{
"message": "Voter password set successfully"
}/resultsGet calculated results
Ranked results with aggregated scores. Which optional fields appear depends on the table’s methodology (ICE shown here).
Response (200 OK)
{
"table_name": "Q4 Roadmap",
"methodology": "ICE",
"total_voters": 3,
"voted_count": 2,
"initiatives": [
{
"id": "7f1e2d3c-4b5a-6978-8c7d-6e5f4a3b2c1d",
"title": "Launch onboarding revamp",
"tags": ["growth"],
"rank": 1,
"calculated_score": 50.4,
"vote_count": 2,
"average_scores": {
"ice_impact": 8,
"ice_confidence": 90,
"ice_ease": 7
}
}
]
}/public-shareToggle the public results URL
When enabled, the response includes a public_share_key for the read-only results page.
Request body
{
"enabled": true
}Response (200 OK)
{
"id": "2c9d1e7a-1f3b-4a2c-9f1e-8b7a6c5d4e3f",
"name": "Q4 Roadmap",
"methodology": "ICE",
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-21T10:00:00Z",
"is_active": true,
"has_voter_password": false,
"public_share_enabled": true,
"public_share_key": "dddddddd-eeee-4fff-8aaa-bbbbbbbbbbbb",
"join_enabled": false,
"join_url": null
}/join-linkTurn the join link on or off
The first enable creates the link. false pauses it and keeps its URL; join_url is null while the link is off.
Request body
{
"enabled": true
}Response (200 OK)
{
"id": "2c9d1e7a-1f3b-4a2c-9f1e-8b7a6c5d4e3f",
"name": "Q4 Roadmap",
"methodology": "ICE",
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-21T10:00:00Z",
"is_active": true,
"results_hidden": true,
"has_voter_password": false,
"public_share_enabled": false,
"join_enabled": true,
"join_url": "https://decidenext.app/join/9b2f6c1e-3d4a-4e5f-8a7b-6c5d4e3f2a1b"
}/initiatives/{id}/commentsAdd a comment to an initiative
content is 1–180 characters. Comments created through the API are attributed to "Manager".
Request body
{
"content": "Let's prioritize this."
}Response (201 Created)
{
"id": "c0ffee00-0000-4000-8000-000000000001",
"initiative_id": "7f1e2d3c-4b5a-6978-8c7d-6e5f4a3b2c1d",
"author_name": "Manager",
"is_manager": true,
"content": "Let's prioritize this.",
"created_at": "2026-01-18T12:00:00Z"
}Retrospective API
Retro boards (the Basic / Starfish / 4Ls / Custom retrospective tool, and brainstorms) are a separate resource from prioritization tables and are managed with their own token type. A retro token only reads and writes the single board it was generated for.
Authentication
Retro requests are authenticated the same way — a bearer token — but with a distinct prefix and base path:
Authorization: Bearer dnx_retro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxBase URL:
https://decidenext.app/api/v1/retroThe two token types are not interchangeable. A dnx_retro_… token only works against /api/v1/retro/*, and a dnx_live_… prioritization token (above) only works against the rest of /api/v1. Each is rejected with 401 unauthorized on the other base path.
Getting a token
- Open the retro board's dashboard and go to the API Access tab.
- Click Generate token and re-enter the board's manager password. The token (
dnx_retro_…) is shown only once — copy it immediately. - Each board has one token at a time. It expires after 90 days; generate a new one from the dashboard when it does.
Rate limit & errors
Same rules as the prioritization API above: each token is limited to 10 requests per minute (429 rate_limited with a Retry-After header), and errors use the same { "error", "message" } shape.
Endpoints
All paths are relative to the retro base URL above (e.g. GET /api/v1/retro/board).
Board
| GET | /retro/board | Board details |
| PUT | /retro/board | Update board settings |
| PUT | /retro/voter-password | Set the participant password |
| PUT | /retro/join-link | Turn the join link on or off |
| POST | /retro/join-link/reset | Replace the join link with a new one |
Participants
| GET | /retro/users | List participants |
| POST | /retro/users | Add a participant |
| DELETE | /retro/users/{id} | Remove a participant |
Cards
| GET | /retro/cards | List cards |
| POST | /retro/cards/{id}/merge | Merge one card into another |
Results & export
| GET | /retro/results | Grouped, vote-ranked results |
| POST | /retro/export | Export cards to a new prioritization table |
| POST | /retro/export-to-existing | Export cards into an existing table |
Not available to tokens: deleting the board (DELETE /board) and managing tokens. Those actions stay dashboard-only, so a leaked or misbehaving retro token can never destroy the board or mint/revoke other tokens.
Request & response examples
Payloads below are accurate to the retro API's data model. For the complete schema of every retro endpoint, see the OpenAPI spec.
/retro/boardGet board details
Response (200 OK)
{
"id": "b1a2c3d4-0000-4000-8000-000000000001",
"name": "Sprint 24 Retro",
"description": "What went well, what didn't",
"board_type": "STARFISH",
"votes_per_user": 5,
"is_active": true,
"has_voter_password": true,
"created_at": "2026-02-10T09:00:00Z",
"updated_at": "2026-02-10T09:00:00Z",
"columns": [
{
"id": "c1a2c3d4-0000-4000-8000-000000000001",
"name": "Keep doing",
"display_order": 1,
"color": "#22C55E"
},
{
"id": "c1a2c3d4-0000-4000-8000-000000000002",
"name": "Stop doing",
"display_order": 2,
"color": "#EF4444"
}
]
}/retro/exportExport cards to a new prioritization table
Creates a brand-new prioritization table (secured by manager_password) with one initiative per card. edits optionally rewrites a card's title; include_users copies retro participants in as voters.
Request body
{
"card_ids": [
"d1a2c3d4-0000-4000-8000-000000000001",
"d1a2c3d4-0000-4000-8000-000000000002"
],
"methodology": "ICE",
"table_name": "Sprint 24 Action Items",
"manager_password": "new-table-secret",
"include_users": true
}Response (201 Created)
{
"table_id": "e1a2c3d4-0000-4000-8000-000000000001",
"manager_key": "f1a2c3d4-0000-4000-8000-000000000001",
"manager_url": "https://decidenext.app/manager/f1a2c3d4-0000-4000-8000-000000000001"
}/retro/boardMove a brainstorm to Vote with a 5-minute countdown
Brainstorm boards only. The phase can move in any direction and ideas and votes are kept; a phase change clears the countdown, and timer_minutes 0 clears it too. results_hidden follows the phase and cannot be set.
Request body
{
"phase": "VOTE",
"timer_minutes": 5
}Response (200 OK)
{
"id": "b2a2c3d4-0000-4000-8000-000000000001",
"name": "Onboarding ideas",
"board_type": "IDEAS",
"votes_per_user": 5,
"is_active": true,
"results_hidden": true,
"has_voter_password": false,
"created_at": "2026-10-15T09:00:00Z",
"updated_at": "2026-10-15T09:20:00Z",
"columns": [
{
"id": "c2a2c3d4-0000-4000-8000-000000000001",
"name": "Ideas",
"display_order": 1
}
],
"join_enabled": false,
"prompt": "How might we cut onboarding time?",
"phase": "VOTE",
"silent_writing": true,
"timer_ends_at": "2026-10-15T09:25:00Z",
"server_time": "2026-10-15T09:20:00Z"
}