✓ Verified 💻 Development ✓ Enhanced Data

Beeminder

Beeminder API for goal tracking and commitment devices.

Rating: 4 (284 reviews)
Downloads: 35,807 downloads
Version: 1.0.0

Overview

Beeminder API for goal tracking and commitment devices.

Complete Documentation

View Source →

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:

bash

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

Goals

List all goals

bash

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

Get single goal

bash

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

bash

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

bash

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

bash

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

bash

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

Update datapoint

bash

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

bash

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

Common Patterns

Check and report what's due

bash

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

bash

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

Installation

Terminal bash


openclaw install beeminder

Copied!

💻Code Examples

### Goals due today

-goals-due-today.sh

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

-goals-due-within-n-days.sh

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

### Add datapoint

-add-datapoint.sh

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

### Update datapoint

-update-datapoint.sh

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

### Check and report what's due

-check-and-report-whats-due.sh

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

-add-with-idempotent-retry.sh

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)"