Scrumbo API & MCP server — developer docs

Authenticatie

Elke aanvraag heeft een persoonlijke API-sleutel nodig. Maak er een aan op je accountpagina — hij wordt één keer getoond, dus kopieer hem meteen.

Stuur hem als bearer-token mee bij elke aanvraag:

Authorization: Bearer sbo_your_key_here

REST-API

De API is beschikbaar op https://scrumbo.com/api/v1 en geeft JSON terug. Een sleutel heeft precies jouw toegang: hij bereikt alleen projecten en boards waarvan je eigenaar, lid of beheerder bent.

Methode	Pad	Omschrijving	Benodigde toegang
GET	`/projects`	Projecten tonen waar je toegang toe hebt	Elke sleutel
GET	`/projects/:token/boards`	Boards in een project tonen	Viewer
GET	`/boards/:boardid`	Een board met statussen en stories ophalen	Viewer
GET	`/boards/:boardid/statuses`	Statussen van een board tonen	Viewer
GET	`/boards/:boardid/stories`	Stories op een board tonen, eventueel gefilterd op status of toegewezene	Viewer
GET	`/boards/:boardid/stories/:storyid`	Eén story ophalen	Viewer
POST	`/boards/:boardid/stories`	Een story aanmaken	Editor
PATCH	`/boards/:boardid/stories/:storyid`	Velden van een story bijwerken	Editor
POST	`/boards/:boardid/stories/:storyid/status`	Status van een story wijzigen	Editor of contributor
DELETE	`/boards/:boardid/stories/:storyid`	Een story verwijderen	Editor
POST	`/boards/:boardid/stories/:storyid/comments`	Een reactie aan een story toevoegen	Commenter
Account, facturering & facturen
GET	`/account`	Je account ophalen: plan, gebruikslimieten van het gratis plan en factuurgegevens	Elke sleutel
GET	`/invoices`	Je facturen tonen	Elke sleutel
GET	`/invoices/:invoiceid` · `…/pdf`	De gegevens van één factuur ophalen, of hem als PDF downloaden	Elke sleutel
Urenbank
GET	`/projects/:token/hourbank` · `…/transactions`	De urenbankinstellingen en het huidige saldo van een project ophalen, of het transactielogboek	Viewer
POST	`…/hourbank/settings` · `…/entries`	De urenbank van een project instellen, of er een aankoop/correctie aan toevoegen	Projecteigenaar
Team
GET	`/team`	Je interne team tonen over al je projecten en feature boards heen	Elke sleutel
Feature boards
GET	`/featureboards`	De feature boards tonen waar je lid van bent	Boardlid
POST	`/featureboards`	Een feature board aanmaken	Betaald plan
GET	`/featureboards/:boardid`	Een feature board ophalen met zijn features, stemmen, reacties en leden	Boardlid
POST	`…/features` · `…/vote` · `…/comments`	Een feature-verzoek indienen, erop stemmen, of een reactie toevoegen	Boardlid
PATCH POST DELETE	`…/features/:featureid` · `…/status`	Een feature-verzoek bijwerken, de status ervan instellen, of het verwijderen	Boardbeheerder
DELETE	`…/comments/:commentid`	Een reactie op een feature-verzoek verwijderen	Auteur van de reactie of boardbeheerder
POST DELETE	`/featureboards/:boardid/members` · `…/:userid/admin` · `…/:userid/external`	Een boardlid toevoegen, promoveren/degraderen, herindelen of verwijderen	Boardbeheerder

"Editor of contributor" geldt ook voor developers, die alleen de status mogen wijzigen, niet de storytekst.

Voorbeeld:

curl https://scrumbo.com/api/v1/boards/123/stories \
  -H "Authorization: Bearer sbo_your_key_here"

curl -X POST https://scrumbo.com/api/v1/boards/123/stories \
  -H "Authorization: Bearer sbo_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"subject": "New story", "story": "Details go here"}'

Parameters

Request-bodies zijn JSON. Elke parameter hieronder wordt zowel door de REST-API als door de bijbehorende MCP-tool geaccepteerd.

Padparameters

Naam	Type	Verplicht	Omschrijving
`:token`	string	Ja	Projecttoken, zoals GET /projects die teruggeeft.
`:boardid`	integer	Ja	Numeriek board-id, zoals GET /projects/:token/boards dat teruggeeft.
`:storyid`	integer	Ja	Numeriek story-id, uniek binnen het eigen board.

Queryparameters

GET /boards/:boardid/stories

Naam	Type	Verplicht	Omschrijving
`status`	string	Nee	Geeft alleen stories met deze status terug. Hoofdletters worden bij het filteren genegeerd.
`assigned`	string	Nee	Geeft alleen stories met deze naam als toegewezene terug. Hoofdletters worden bij het filteren genegeerd.

Story-velden (aanmaken en bijwerken)

POST /boards/:boardid/stories · PATCH /boards/:boardid/stories/:storyid

Naam	Type	Verplicht	Omschrijving
`subject`	string	Bij aanmaken	Korte titel, maximaal 500 tekens. Verplicht bij aanmaken; langere waarden worden geweigerd.
`story`	string	Nee	Story-tekst. HTML mag, maar wordt server-side geschoond, dus niet-ondersteunde tags en attributen worden verwijderd.
`status`	string	Nee	Moet exact overeenkomen met een status van het project, inclusief hoofdletters. Bij aanmaken valt een onbekende of ontbrekende status terug op de eerste status van het board; bij bijwerken wordt een onbekende status geweigerd.
`assigned`	string	Nee	Naam van de toegewezene, vrije tekst. Dit is alleen een label — het koppelt de story niet aan een Scrumbo-account.
`requester`	string	Nee	Naam van degene die de story heeft aangevraagd, vrije tekst.
`scope`	string	Nee	Kort scope-label, maximaal 100 tekens. Langere waarden worden geweigerd.
`comment`	string	Nee	Verouderd vrijetekstveld dat op de story zelf wordt opgeslagen. Het wordt niet in de webinterface getoond — gebruik voor een zichtbare reactie het comments-endpoint hieronder.
`notify`	boolean	Nee	Mail de volgers van het board en de story over deze wijziging. Standaard false.

Velden die hier niet staan worden genegeerd in plaats van geweigerd.
Een update moet minstens één van deze velden bevatten; alleen de velden die je meestuurt worden gewijzigd.
Een story aan een Scrumbo-account koppelen (de toegewezene-kiezer) kan niet via de API.

Een story verplaatsen

POST /boards/:boardid/stories/:storyid/status

Naam	Type	Verplicht	Omschrijving
`status`	string	Ja	Doelstatus. Moet exact overeenkomen met een status van het project, inclusief hoofdletters.
`notify`	boolean	Nee	Mail de volgers van het board en de story over deze wijziging. Standaard false.

Een reactie toevoegen

POST /boards/:boardid/stories/:storyid/comments

Naam	Type	Verplicht	Omschrijving
`comment`	string	Ja	Reactietekst, platte tekst. De tekst wordt vóór opslag ge-escaped, dus HTML wordt letterlijk getoond in plaats van weergegeven.
`name`	string	Nee	Auteursnaam die bij de reactie wordt getoond. Standaard de naam van het account van de API-sleutel.
`notify`	boolean	Nee	Mail de volgers van het board en de story over deze wijziging. Standaard false.

Geweigerde verzoeken geven de bijbehorende HTTP-status (400, 403 of 404) terug met een JSON-body:

{"error": "subject must be at most 500 characters"}

MCP-server

Scrumbo levert een losstaande MCP-server die de REST-API als tools aanbiedt, zodat een MCP-bewuste assistent zoals Claude Desktop of Claude Code je boards direct kan gebruiken. Node.js 20 of nieuwer is vereist.

Download de MCP-server (ZIP)

Pak het uit en installeer eenmalig de dependencies:
```
unzip scrumbo-mcp.zip
cd scrumbo-mcp
npm install
```
Maak een API-sleutel aan op je accountpagina en kopieer hem.
Registreer de server bij je MCP-client, bijvoorbeeld:

{
  "mcpServers": {
    "scrumbo": {
      "command": "node",
      "args": ["/absolute/path/to/scrumbo-mcp/index.js"],
      "env": {
        "SCRUMBO_API_KEY": "sbo_your_key_here",
        "SCRUMBO_API_URL": "https://scrumbo.com/api/v1"
      }
    }
  }
}

Tools:

Omschrijving	Benodigde toegang
`list_projects`	Elke sleutel
`list_boards`, `get_board`, `list_stories`, `get_story`, `list_statuses`	Viewer
`add_comment`	Commenter
`create_story`, `update_story`, `move_story`, `delete_story`	Editor
`get_account`, `list_invoices`, `get_invoice`, `get_invoice_pdf`, `get_team`	Elke sleutel
`get_hourbank`, `list_hourbank_transactions`	Viewer
`save_hourbank_settings`, `add_hourbank_entry`	Projecteigenaar
`list_feature_boards`, `get_feature_board`, `create_feature`, `vote_feature`, `add_feature_comment`	Boardlid
`create_feature_board`	Betaald plan
`update_feature`, `set_feature_status`, `delete_feature`, `add_feature_board_member`, `set_feature_board_member_admin`, `set_feature_board_member_external`, `remove_feature_board_member`	Boardbeheerder
`delete_feature_comment`	Auteur van de reactie of boardbeheerder

Let op

Een sleutel heeft precies jouw toegang — wie hem heeft kan binnen dat bereik namens jou handelen, behandel hem dus als een wachtwoord.
Trek een sleutel op elk moment in via je accountpagina; alles wat hem gebruikt stopt dan meteen met werken.
De MCP-server zelf heeft geen databasetoegang — het is een dunne HTTP-client die nooit meer rechten heeft dan de sleutel die je meegeeft.

API en MCP-server