Your first call

The BuddyPad API gives you your own goals, buddies and activity over HTTP. You can make your first call in about two minutes. You need the BuddyPad app, signed in, and a terminal.

1. Make a token

In the app, open Me, then Connected tools, then tap Make a token. Name it after whatever will use it. Read and Goals start ticked. Leave them for now, because step 5 adds a goal. If your tool only reads, untick Goals. Then tap Make token.

Tap Copy token. You only see it this once. If you lose it, revoke it and make another.

2. Put it in your shell

export BUDDYPAD_TOKEN=bp_paste_your_token_here

3. Ask who you are

curl https://api.buddypad.builtbymo.dev/v1/me \
  -H "Authorization: Bearer $BUDDYPAD_TOKEN"

You get your profile back:

{
  "id": "00000000-0000-4000-8000-00000000a001",
  "display_name": "Ana",
  "avatar_path": null
}

That's a working call. A 401 means the token didn't paste cleanly, so check that the variable holds the whole 52 characters.

4. See your buddies and goals

curl https://api.buddypad.builtbymo.dev/v1/pairs \
  -H "Authorization: Bearer $BUDDYPAD_TOKEN"

curl "https://api.buddypad.builtbymo.dev/v1/items?owner=me" \
  -H "Authorization: Bearer $BUDDYPAD_TOKEN"

5. Add a goal

This one needs the Goals permission, which your token has if you left it ticked. Permissions are set when you make a token, so if you unticked it, make another. Send a new Idempotency-Key with every write. If your connection drops, send the same request with the same key and it won't add a second goal.

curl -X POST https://api.buddypad.builtbymo.dev/v1/items \
  -H "Authorization: Bearer $BUDDYPAD_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title": "Read 20 pages"}'

What a token can do

Permission	What it lets a token do
`read`	See your profile, buddies, streaks, your goals, the goals buddies share with you, comments, reactions, nudges, check-ins, suggestions and the events feed.
`goals`	Add, edit, complete, delete, share, unshare, copy and move your own goals. Accept or decline suggestions on them.
`buddy`	Comment, react, nudge, send a check-in, answer one and suggest an edit. All of it shows up as you.
`webhooks`	Register, list, test, rotate and delete webhooks, and read their delivery logs.

Where next

The Reference lists every call with a real example. To hear about changes as they happen, read Events and webhooks. Calls that fail always have the same shape, which is covered in Errors. The terms cover what you can do with the API.