Getting started

This guide takes you from nothing to a processed capture: an account, a token, one message about your day, and the moment undrstand hands back what it found in it. Everything here works the same whether you follow it with a terminal or with Claude.

undrstand is a self-awareness backend. You tell it what happened, in your own words, and it finds the patterns behind how you feel and act.

It has no app of its own. You reach it over a REST API or over MCP, from a terminal, from an app you build, or from Claude.

This page uses the REST API. The examples use api.undrstand.com as the API domain; take the real one from your account mail.

1. An account and a token

Registration is one call and needs no password. The response holds your profile and, under meta, a bearer token for the API.

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…"}}

The token works right away. A mail with a verification link follows; click it in the first days, or the API starts asking for it once you have finished onboarding.

To sign in again later, ask for a code by mail and trade it for a new token. Typing the code also verifies your address.

# 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}}

A token stays valid until you revoke it. Revoke the one you are using with a delete on the personal access token route.

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

2. Check who you are

Every authenticated call carries the token as a bearer header. The profile route is the quickest way to see that it works.

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

3. Set your timezone

undrstand counts on days: a pattern needs three different days, and the timeline is one entry per day. Days are cut in your timezone, so set it before your first capture.

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"}'

The default is UTC. Any IANA name works.

4. Your first capture

A capture is any text about your life: how the day went, what someone said, a note you dictated. Write it as you would tell a friend, in whatever language you think in. Do not summarise, do not clean up, and do not translate: the analysis does that.

Give occurred_at when the text is about another day than today; leave it out and now is used. The text can be up to fifty thousand characters.

curl -X POST https://api.undrstand.com/captures \
  -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, …}}

The response comes back at once with status queued. Processing happens in the background.

5. Wait for it

Read the capture back until its status is processed. It goes queued, processing, processed; failed means the analysis gave up, and you can post the text again.

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

Count on thirty seconds to two minutes per capture. Most of that is the language model reading your text several times over, once per thing it looks for.

6. What you get back

A processed capture comes with the language it was written in, a translated field that is always English, and its segments. The original stays exactly as you wrote it.

{
  "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",
    "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}
        ]
      }
    ]
  }
}

A segment is one situation: one thing that happened together with what you felt about it and what you did. A note about the morning, a call and the evening becomes three segments, so the feelings of one are never pinned on another.

Each segment carries tags. Their type says what they are:

• trigger — what set you off: a person calling, a deadline, a room full of people.
• positive_feeling, negative_feeling — what you felt, matched against a fixed list of emotions. A feeling that is not on the list is dropped.
• good_behaviour, bad_behaviour — what you did about it: went for a run, scrolled for an hour.
• person, location, activity — who was there, where you were, what you were doing. These never become patterns on their own, but a pattern can happen more with one of them.

Triggers and behaviours also carry a category: the name that groups the same thing said in different words. A category is what a pattern is named after once it shows up often enough.

Where to next

• API — The API guide explains patterns, correlations, flows, the timeline and review.
• MCP — The MCP guide connects Claude or ChatGPT, so you can talk instead of post.
• Apps and OAuth — The apps guide is for building a frontend other people sign in to.