API

De REST API is het hele oppervlak: captures erin, patronen eruit, met correlaties, flows, beoordeling en een tijdlijn ertussen. Deze pagina legt de begrippen en de levenscyclus uit; de gegenereerde referentie op het API-domein heeft elk veld.

Basis

Elke route leeft op het API-domein, neemt en geeft JSON, en wil een bearer token. Antwoorden wikkelen de resource in data; lijsten voegen links en meta toe met de pagina en het totaal.

GET    /captures              GET    /patterns
POST   /captures              GET    /patterns/{id}
GET    /captures/{id}         PATCH  /patterns/{id}
DELETE /captures/{id}         PATCH  /correlations/{id}
GET    /timeline?from&to      GET    /settings/me
GET    /users/me              PUT    /settings/me/{key}

{
  "data": [ … ],
  "links": {"first": "…", "last": "…", "prev": null, "next": "…"},
  "meta": {"current_page": 1, "per_page": 15, "total": 42, …}
}

De gegenereerde referentie heeft elke route, elk veld en elke fout, afgelezen van de code, dus altijd actueel. Deze pagina vertelt wat de resources betekenen. /docs/api, /openapi.json.

Wat er met een capture gebeurt

Eén capture, één run, vaste volgorde. Elke stap is een aanroep naar een taalmodel, behalve detectie, dat is tellen.

Reken op dertig seconden tot twee minuten. Detectie draait ook elke nacht opnieuw om jouw lokale middernacht, dus patronen kunnen verschijnen, veranderen of sluiten zonder nieuwe capture.

Captures

Een capture is de tekst die je hebt ingeleverd. Velden: original, precies zoals gepost; translated, altijd Engels; language, de gevonden ISO-code; origin, voorlopig text; occurred_at, het moment waar het over gaat; status; en segments zodra verwerkt.

Status loopt van queued naar processing naar processed of failed. Een mislukte capture houdt zijn tekst en verder niets; stuur hem opnieuw in. Een capture verwijderen haalt weg wat erin gevonden is en draait detectie opnieuw, dus een patroon dat alleen in die capture leefde sluit.

Lijsten zijn gepagineerd met page en limit, nieuwste eerst.

Segmenten en tags

Een segment is een letterlijk stuk van de vertaalde tekst: één ding dat gebeurde met het gevoel dat het gaf en wat je deed. Elk draagt tags van een type: trigger, positive_feeling, negative_feeling, good_behaviour, bad_behaviour, person, location, activity. Triggers en gedrag noemen ook hun categorie.

Patronen

Een patroon is een categorie die steeds terugkomt met dezelfde gevoelens: iets wat je steeds raakt, of iets wat je steeds doet. Het heeft minstens drie verschillende dagen nodig. Velden:

• name — de categorie, zoals werkcontact of uitstelgedrag.
• sentiment — positive of negative. Goed gedrag maakt een positief patroon, slecht gedrag een negatief, een trigger kan beide maken.
• impact — low, moderate of high: hoe vaak het opduikt, afgewogen tegen hoeveel je schrijft.
• urgent — true als het in de afgelopen week op drie verschillende dagen opdook.
• feelings — tot vier gevoelens waarmee het komt.
• description — een paar zinnen, voor jou geschreven, in jouw taal.
• status — detected, accepted of rejected.
• captures_count, last_detected_at, closed_at — waar het op rust, wanneer het voor het laatst gezien is, en wanneer het ophield op te duiken.

Een patroon dat een week stil is sluit en gaat weer open als het terugkomt; hetzelfde patroon, geen nieuw. Eén patroon lezen voegt zijn captures als samenvattingen toe, zijn correlaties en zijn flows.

{
  "data": {
    "id": "7c1e…",
    "name": "work contact",
    "sentiment": "negative",
    "impact": "low",
    "urgent": true,
    "status": "detected",
    "description": "Contact from work, a call or a message about a deadline, keeps landing as a knot in your stomach. …",
    "feelings": [{"id": "…", "name": "anxious"}],
    "captures_count": 4,
    "last_detected_at": "2026-09-26T22:00:03.000000Z",
    "closed_at": null,
    "created_at": "2026-09-24T22:00:01.000000Z",
    "captures": [{"id": "9d2f…", "status": "processed", "occurred_at": "2026-09-26T16:10:00.000000Z"}, …],
    "correlations": [
      {"id": "…", "tag": {"id": "…", "type": "person", "name": "boss"}, "impact": "moderate", "amount": 3, "status": "detected"}
    ],
    "flows": [
      {"id": "…", "segment_id": "b41c…", "trigger": "boss calling about the report", "feeling": "anxious", "behaviour": "scrolling instead of working"}
    ]
  }
}

Correlaties

Een correlatie is een persoon, locatie of activiteit waarmee een patroon vaker voorkomt. Hij draagt de tag, een impact, het aantal keren dat ze samen gezien zijn, en een status. De lijst is de top per type, elke run ververst, dus een die uit de top valt verdwijnt tenzij je hem geaccepteerd hebt.

Flows

Een flow is één segment in volgorde verteld: trigger, gevoel, gedrag. Wat er gebeurde, wat je voelde, wat je deed. Flows worden alleen gekoppeld, nooit verzonnen: elk van de drie is een tag die uit dat segment gehaald is.

Tijdlijn

De tijdlijn is één regel per kalenderdag in jouw tijdzone, lege dagen inbegrepen, tussen from en to, hoogstens 92 dagen uit elkaar. Elke dag noemt zijn captures als id, status en occurred_at, en de patronen waar die captures bij horen.

curl "https://api.undrstand.com/timeline?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# {"data": [
#   {"date": "2026-09-01", "captures": [], "patterns": []},
#   …
#   {"date": "2026-09-26",
#    "captures": [{"id": "9d2f…", "status": "processed", "occurred_at": "…"}],
#    "patterns": [{"id": "7c1e…", "name": "work contact", "sentiment": "negative", "impact": "low"}]}
# ]}

Review

Je kunt undrstand vertellen dat een patroon of correlatie van jou is, of niet. Accepteren houdt het in de lijst en buiten de nachtelijke opruiming. Een patroon afwijzen sluit het, laat zijn flows en correlaties vallen, en leert de extractie dat onderwerp voortaan met rust te laten in alles wat je daarna inlevert. Een afgewezen patroon is nog leesbaar op id, nooit in de lijst.

curl -X PATCH https://api.undrstand.com/patterns/7c1e… \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"status": "accepted"}'      # or "rejected"; same shape on /correlations/{id}

Review alleen op het woord van de gebruiker. Een app die op eigen initiatief afwijst leert de analyse dingen te negeren die de gebruiker nooit gezien heeft.

Instellingen

Twee instellingen doen er hier toe: timezone, die de dagen afsnijdt en de nachtelijke verversing om jouw lokale middernacht draait, en app_locale, de taal van de patroonbeschrijvingen. Lees ze allemaal, of schrijf er een op sleutel.

GET https://api.undrstand.com/settings/me
# {"data": [{"key": "timezone", "value": "Europe/Amsterdam"}, {"key": "app_locale", "value": "nl"}, …]}

PUT https://api.undrstand.com/settings/me/app_locale   {"value": "nl"}

Fouten

HTTP/1.1 422 Unprocessable Content
{
  "message": "The to field must be a date after or equal to from.",
  "errors": {"to": ["The to field must be a date after or equal to from."]}
}

Waar nu heen

• /docs/api — De gegenereerde referentie op het API-domein, met elk veld.
• Apps en OAuth — Apps en OAuth, voor een frontend waar anderen op inloggen.