REST API

Shayan TaslimBijgewerkt:

De UserJot REST API geeft je code toegang tot dezelfde werkruimtegegevens als het dashboard: metadata van de werkruimte, borden, verzoeken (inclusief samenvoegingen, vergelijkbare verzoeken, tags, abonnementen en bijlagen), opmerkingen, stemmen, changelog-items, leden (inclusief verwijdering volgens de AVG), bedrijven, gesprekken, assets en collecties en artikelen in het helpcentrum.

De volledige interactieve referentie, met elke route, elk schema en elk voorbeeld, is beschikbaar op userjot.com/docs/api en rechtstreeks op https://api.userjot.com/v1/docs. Het OpenAPI-document waarop deze is gebaseerd, staat op https://api.userjot.com/v1/openapi.json (ook beschikbaar op https://userjot.com/docs/api/openapi.json), zodat je getypeerde clients in jouw programmeertaal kunt genereren.

Basis-URL en verificatie

text
Base URL:      https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKEN

UserJot accepteert twee typen Bearer-tokens op routes van /v1/*:

  • API-tokens: Maak een token aan via Settings → MCP & API (alleen voor beheerders en eigenaren). Tokens hebben het voorvoegsel uj_live_, zijn gekoppeld aan één werkruimte, verlopen pas wanneer ze worden ingetrokken en kunnen een nieuwe naam krijgen. Gebruik Hold to revoke (ingedrukt houden) om een token onmiddellijk in te trekken; ingetrokken tokens blijven staan voor de auditgeschiedenis.

  • OAuth 2.0-toegangstokens: Ondersteunt PKCE (S256), Dynamic Client Registration (/oauth/register), Client ID Metadata Documents (CIMD), het intrekken van tokens (/oauth/revoke) en discovery-metadata op https://api.userjot.com/.well-known/oauth-authorization-server en https://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Toegangstokens zijn 1 uur geldig, met refresh-tokens die 30 dagen geldig zijn en rouleren (workspace- en offline_access-scopes). Ze blijven alleen geldig zolang de gebruiker die toestemming heeft gegeven eigenaar of beheerder van die werkruimte blijft.

Een eerste verzoek

Bash
curl https://api.userjot.com/v1/boards \
  -H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"

Snelheidslimieten

API- en MCP-verzoeken delen één snelheidslimietbudget per werkruimte:

Abonnement

Per minuut

Per uur

Free

10 verzoeken

150 verzoeken

Starter

60 verzoeken

1.500 verzoeken

Professional

120 verzoeken

5.000 verzoeken

Daarnaast gelden er afzonderlijke limieten per bewerking:

  • Assets: Assetimport, uploads in meerdere delen en automatisch geïmporteerde Markdown-afbeeldingen delen een afzonderlijke werkruimtelimiet van 20 aanvragen per minuut en 300 per uur (plus 20 per minuut en 300 per uur voor het voltooien van uploads).

  • Uitgaande gesprekken (POST /v1/conversations): Alleen beschikbaar bij betaalde abonnementen, beperkt tot 5 per dag bij Starter en 15 per dag bij Professional (geeft 409 plan_feature_unavailable terug bij Free).

Wanneer een limiet wordt overschreden, retourneert de API HTTP 429 met een Retry-After-header en error.details.retry_after_seconds.

Paginering, fouten en idempotentie

  • Paginering met cursors. Lijst-endpoints accepteren cursor en limit (tot 100; standaardwaarden verschillen per endpoint, zoals 10 voor uitgebreide lijsten zoals /v1/requests en /v1/changelogs) en retourneren next_cursor om verder te bladeren.

  • Foutstructuur. Foutreacties geven { "error": { "code", "message", "details" } } terug en bevatten in elke reactie een X-Request-Id-responseheader. Veelvoorkomende codes zijn 422 validation_error (met details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (bij GET/PATCH /v1/members/{member_id} na DELETE /v1/members/{member_id}-AVG-verwijdering), 409 member_erased (bij routes die verwijzen naar een verwijderd lid), 409 help_slug_taken en 409 help_version_conflict.

  • Idempotentie. Stuur een Idempotency-Key-header mee (24 uur bewaard, met een fingerprint van de aanvraagbody) om aanvragen voor het aanmaken van items veilig opnieuw te proberen op acht routes: /v1/requests, /v1/changelogs, /v1/conversations, /v1/conversations/{conversation_id}/replies, /v1/conversations/{conversation_id}/notes, /v1/assets/import, /v1/help/articles en /v1/help/collections.

Assets en afbeeldingen

Upload afbeeldingen (PNG, JPEG, GIF of WebP van maximaal 10 MiB) op drie manieren:

  • Upload in meerdere delen: POST /v1/assets (createAsset, alleen REST) uploadt een afbeelding met één multipart/form-data-aanvraag.

  • Importeren via URL: POST /v1/assets/import downloadt een openbare HTTPS-afbeelding naar de opslag van de werkruimte.

  • Upload in drie stappen met een vooraf ondertekende URL: POST /v1/assets/uploads (met de exacte size_bytes; maximaal 100 open uploadsessies per werkruimte) → PUT-bytes naar de vooraf ondertekende URL die 30 minuten geldig is → POST /v1/assets/uploads/{upload_id}/complete.

Verwijs in Markdown naar geüploade assets met asset:<id>. Openbare HTTPS-afbeeldings-URL's in Markdown die naar de changelog- en helpartikelendpoints worden gestuurd, worden ook automatisch geïmporteerd (maximaal 10 inline-afbeeldingen per changelogaanvraag en 20 per artikel in het Help Center), en tellen mee voor de assetlimiet van de werkruimte.

Webhooks

Uitgaande webhooks voor klanten zijn nog niet beschikbaar. Gebruik voor realtime teammeldingen Slack verbinden of Discord verbinden, of controleer wijzigingen via de REST API.

REST of MCP

De MCP server is gebouwd op deze API en biedt 98 van de 100 REST-bewerkingen aan als MCP-tools (POST /v1/assets uploaden in meerdere delen en DELETE /v1/members/{member_id}-AVG-verwijdering zijn alleen beschikbaar via REST). Gebruik de REST API vanuit je eigen backend, automatisering of applicatiecode als je volledige controle wilt over aanvragen en reacties. Gebruik MCP om een AI-client te koppelen die het Model Context Protocol ondersteunt.

Omgaan met tokens

Behandel je API-token als elk ander geheim:

  • Neem de token niet hardgecodeerd op in configuratiebestanden die worden vastgelegd in versiebeheer.

  • Gebruik bij voorkeur omgevingsvariabelen of een secretsmanager.

  • Gebruik waar mogelijk aparte tokens voor verschillende omgevingen of teamgenoten.

  • Trek tokens die je niet meer nodig hebt in via Settings → MCP & API met Hold to revoke.

Heeft dit je vraag beantwoord?