Aan de slag

Deze gids brengt je van niets naar een verwerkt document: een account, een token, één bericht over je dag, en het moment waarop undrstand teruggeeft wat het erin vond. Alles hier werkt hetzelfde of je het nu volgt met een terminal of met Claude.

undrstand is een hulpmiddel voor zelfinzicht. Je vertelt wat er gebeurd is, in je eigen woorden, en het vindt de patronen achter hoe je je voelt en wat je doet.

De meeste mensen gebruiken het in de webapp of via een AI-assistent. Alles wat die doen gaat via een REST API en een MCP-server, en beide staan voor jou open: vanuit een terminal, vanuit een app die je zelf bouwt, of vanuit Claude.

Deze pagina gebruikt de REST API. De voorbeelden gebruiken api.undrstand.com als API-domein.

1. Een account en een token

Registreren is één aanroep en heeft geen wachtwoord nodig; alleen het e-mailadres is verplicht. Het antwoord bevat je profiel en, onder meta, een bearer token voor de API. Heb je al een account uit de webapp, sla deze aanroep dan over en log hieronder in: het is hetzelfde account.

POST /users

curl -X POST https://api.undrstand.com/users \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"email": "you@example.com", "name": "Your name"}'

# {"data": {"id": "…", "email": "you@example.com", …},
#  "meta": {"token": "1|eyJ…"}}

Het token werkt meteen. Er volgt een mail met een verificatielink; klik die in de eerste dagen aan, anders gaat de API erom vragen zodra je onboarding af is.

Om later opnieuw in te loggen vraag je een code per mail en ruil je die voor een nieuw token. De code intypen verifieert ook je adres.

POST /magic-links/mails · POST /magic-links/tokens

# 1. a six-digit code is mailed to you
curl -X POST https://api.undrstand.com/magic-links/mails \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"email": "you@example.com"}'

# 2. trade the code for a token
curl -X POST https://api.undrstand.com/magic-links/tokens \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'

# {"data": {"token": "2|eyJ…", "two_factor": false}}

Een account met tweestapsverificatie antwoordt met two_factor true. Dat token wordt tegengehouden tot je één keer de code uit je authenticator-app stuurt, of een herstelcode. Daarna werkt het als elk ander.

POST /personal-access-tokens/two-factor-challenges

curl -X POST https://api.undrstand.com/personal-access-tokens/two-factor-challenges \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"code": "123456"}'

# 204 No Content

Een token blijft geldig tot je het intrekt. Trek het token dat je gebruikt in met een delete op de personal-access-token-route.

DELETE /personal-access-tokens/me

curl -X DELETE https://api.undrstand.com/personal-access-tokens/me \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

2. Kijk wie je bent

Elke geauthenticeerde aanroep draagt het token als bearer header. De profielroute is de snelste manier om te zien dat het werkt.

GET /users/me

curl https://api.undrstand.com/users/me \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

3. Stel je tijdzone in

undrstand telt in dagen: een patroon heeft drie verschillende dagen nodig en de tijdlijn is één regel per dag. Dagen worden in jouw tijdzone afgesneden, dus stel die in vóór je eerste document.

PUT /settings/me/timezone

curl -X PUT https://api.undrstand.com/settings/me/timezone \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"value": "Europe/Amsterdam"}'

De standaard is UTC. Elke IANA-naam werkt.

4. Je eerste document

Een document is elke tekst over je leven: hoe de dag ging, wat iemand zei, een ingesproken notitie. Schrijf het zoals je het een vriend zou vertellen, in de taal waarin je denkt. Niet samenvatten, niet opschonen, niet vertalen: dat doet de analyse.

Geef occurred_at mee als de tekst over een andere dag gaat dan vandaag; laat het weg en nu wordt gebruikt. De tekst mag tot vijftigduizend tekens lang zijn.

POST /documents

curl -X POST https://api.undrstand.com/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "original": "Mijn baas belde weer om zes uur over het rapport. Ik voelde die knoop in mijn maag en heb de avond zitten scrollen in plaats van het af te maken.",
    "occurred_at": "2026-09-26T18:10:00+02:00"
  }'

# {"data": {"id": "9d2f…", "status": "queued", "original": "…", "translated": null, …}}

Het antwoord komt meteen terug met status queued. De verwerking gebeurt op de achtergrond.

Op het gratis abonnement leest undrstand dertig documenten per maand. Eén daarboven wordt bewaard, komt terug met status waiting, en wordt gelezen als er een nieuwe maand begint of het abonnement verandert.

5. Wacht erop

Lees het document terug tot de status processed is. Het gaat van queued naar processing naar processed; failed betekent dat de analyse het opgaf, en dan kun je de tekst opnieuw insturen.

GET /documents/{id}

curl https://api.undrstand.com/documents/9d2f… \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

Reken op dertig seconden tot twee minuten per document.

6. Wat je terugkrijgt

Een verwerkt document komt met de taal waarin het geschreven is, een translated-veld dat altijd Engels is, en zijn segmenten. Het origineel blijft precies zoals je het schreef.

GET /documents/{id} · status processed

{
  "data": {
    "id": "9d2f…",
    "original": "Mijn baas belde weer om zes uur over het rapport. …",
    "translated": "My boss called again at six about the report. …",
    "language": "nl",
    "origin": "text",
    "source": null,
    "occurred_at": "2026-09-26T16:10:00.000000Z",
    "status": "processed",
    "created_at": "2026-09-26T16:11:02.000000Z",
    "segments": [
      {
        "id": "b41c…",
        "position": 1,
        "text": "My boss called again at six about the report. I felt that knot in my stomach and spent the evening scrolling instead of finishing it.",
        "tags": [
          {"id": "…", "type": "trigger",          "name": "boss calling about the report", "category": "work contact"},
          {"id": "…", "type": "negative_feeling", "name": "anxious",                       "category": null},
          {"id": "…", "type": "bad_behaviour",    "name": "scrolling instead of working",  "category": "procrastination"},
          {"id": "…", "type": "person",           "name": "boss",                          "category": null}
        ]
      }
    ]
  }
}

Een segment is één situatie: één ding dat gebeurde, samen met wat je erbij voelde en wat je deed. Een notitie over de ochtend, een telefoontje en de avond wordt drie segmenten, zodat de gevoelens van het ene nooit op het andere geplakt worden.

Elk segment draagt tags. Hun type zegt wat ze zijn:

trigger — wat je raakte: iemand die belt, een deadline, een volle kamer.
positive_feeling, negative_feeling — wat je voelde, vergeleken met een vaste lijst emoties. Een gevoel dat niet op de lijst staat valt af.
good_behaviour, bad_behaviour — wat je ermee deed: een rondje hardlopen, een uur scrollen.
person, location, activity — wie erbij was, waar je was, wat je aan het doen was. Deze worden nooit zelf een patroon, maar een patroon kan vaker met een ervan voorkomen.

Triggers en gedrag dragen ook een categorie: de naam die hetzelfde ding in andere woorden bij elkaar brengt. Een categorie is waar een patroon naar vernoemd wordt zodra het vaak genoeg opduikt.

Waar nu heen

API — De API-gids legt patronen, correlaties, flows, de tijdlijn, zoeken en review uit.
MCP — De MCP-gids koppelt Claude of ChatGPT, zodat je kunt praten in plaats van posten.
Apps en OAuth — De apps-gids is voor het bouwen van een frontend waar anderen op inloggen.