Beeminder API

Direct REST API access to Beeminder. No CLI dependencies.

Setup

Set two env vars:

• BEEMINDER_USERNAME - Beeminder username
• BEEMINDER_AUTH_TOKEN - personal auth token from https://www.beeminder.com/api/v1/auth_token.json (requires login)

All examples use:

BASE="https://www.beeminder.com/api/v1/users/$BEEMINDER_USERNAME"

Goals

List all goals

curl -s "$BASE/goals.json?auth_token=$BEEMINDER_AUTH_TOKEN" | jq '[.[] | {slug, safebuf, baremin, limsum}]'

Get single goal

curl -s "$BASE/goals/GOAL.json?auth_token=$BEEMINDER_AUTH_TOKEN"

Key fields:

• slug - goal identifier
• safebuf - days of safety buffer (0 = due today, negative = in the red)
• baremin - minimum needed today to stay on track
• limsum - human-readable summary (e.g. "+1 due in 2 days")
• losedate - unix timestamp of derail date
• rate - commitment rate
• runits - rate units (d/w/m/y)
• headsum - summary of current status
• goalval - end goal value (null if no end goal)
• gunits - goal units (e.g. "hours", "pages")

Goals due today

curl -s "$BASE/goals.json?auth_token=$BEEMINDER_AUTH_TOKEN" \
  | jq '[.[] | select(.safebuf <= 0)] | sort_by(.losedate) | .[] | {slug, baremin, limsum}'

Goals due within N days

curl -s "$BASE/goals.json?auth_token=$BEEMINDER_AUTH_TOKEN" \
  | jq --arg cutoff "$(date -d '+2 days' +%s)" \
    '[.[] | select(.losedate <= ($cutoff | tonumber))] | sort_by(.losedate) | .[] | {slug, baremin, limsum}'

Datapoints

Add datapoint

curl -s -X POST "$BASE/goals/GOAL/datapoints.json" \
  -d "auth_token=$BEEMINDER_AUTH_TOKEN" \
  -d "value=N" \
  -d "comment=TEXT"

Optional: -d "requestid=UNIQUE_ID" for idempotent retries (safe to repeat without duplicating).

Get recent datapoints

curl -s "$BASE/goals/GOAL/datapoints.json?auth_token=$BEEMINDER_AUTH_TOKEN&count=5&sort=daystamp"

Update datapoint

curl -s -X PUT "$BASE/goals/GOAL/datapoints/DATAPOINT_ID.json" \
  -d "auth_token=$BEEMINDER_AUTH_TOKEN" \
  -d "value=N" \
  -d "comment=TEXT"

Delete datapoint

curl -s -X DELETE "$BASE/goals/GOAL/datapoints/DATAPOINT_ID.json?auth_token=$BEEMINDER_AUTH_TOKEN"

Common Patterns

Check and report what's due

curl -s "$BASE/goals.json?auth_token=$BEEMINDER_AUTH_TOKEN" \
  | jq '[.[] | select(.safebuf <= 1)] | sort_by(.safebuf) | .[] | {slug, baremin, limsum, safebuf}'

Add with idempotent retry

curl -s -X POST "$BASE/goals/GOAL/datapoints.json" \
  -d "auth_token=$BEEMINDER_AUTH_TOKEN" \
  -d "value=1" \
  -d "comment=done" \
  -d "requestid=GOAL-$(date +%Y%m%d)"

Notes

• Base URL must be exactly https://www.beeminder.com/api/v1/ (https, www required)
• All responses are JSON
• Use jq to parse responses
• Daystamps use YYYYMMDD format
• Timestamps are unix epoch seconds