Beeminder API
Direct REST API access to Beeminder. No CLI dependencies.
Setup
Set two env vars:
- -
BEEMINDER_USERNAME - Beeminder username - INLINECODE1 - personal auth token from https://www.beeminder.com/api/v1/auth_token.json (requires login)
All examples use:
CODEBLOCK0
Goals
List all goals
CODEBLOCK1
Get single goal
CODEBLOCK2
Key fields:
- -
slug - goal identifier - INLINECODE3 - days of safety buffer (0 = due today, negative = in the red)
- INLINECODE4 - minimum needed today to stay on track
- INLINECODE5 - human-readable summary (e.g. "+1 due in 2 days")
- INLINECODE6 - unix timestamp of derail date
- INLINECODE7 - commitment rate
- INLINECODE8 - rate units (d/w/m/y)
- INLINECODE9 - summary of current status
- INLINECODE10 - end goal value (null if no end goal)
- INLINECODE11 - goal units (e.g. "hours", "pages")
Goals due today
CODEBLOCK3
Goals due within N days
CODEBLOCK4
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
CODEBLOCK6
Update datapoint
CODEBLOCK7
Delete datapoint
CODEBLOCK8
Common Patterns
Check and report what's due
CODEBLOCK9
Add with idempotent retry
CODEBLOCK10
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
Beeminder API
直接通过REST API访问Beeminder，无需CLI依赖。
设置
设置两个环境变量：
- - BEEMINDERUSERNAME - Beeminder用户名
- BEEMINDERAUTHTOKEN - 来自 https://www.beeminder.com/api/v1/authtoken.json 的个人认证令牌（需登录）
所有示例均使用：
bash
BASE=https://www.beeminder.com/api/v1/users/$BEEMINDER_USERNAME
目标
列出所有目标
bash
curl -s $BASE/goals.json?auth
token=$BEEMINDERAUTH_TOKEN | jq [.[] | {slug, safebuf, baremin, limsum}]
获取单个目标
bash
curl -s $BASE/goals/GOAL.json?auth
token=$BEEMINDERAUTH_TOKEN
关键字段：
- - slug - 目标标识符
- safebuf - 安全缓冲天数（0=今天到期，负数=已逾期）
- baremin - 今天保持进度所需的最小值
- limsum - 人类可读摘要（例如+1 在2天内到期）
- losedate - 脱轨日期的Unix时间戳
- rate - 承诺速率
- runits - 速率单位（d/w/m/y）
- headsum - 当前状态摘要
- goalval - 最终目标值（若无最终目标则为null）
- gunits - 目标单位（例如小时、页数）
今天到期的目标
bash
curl -s $BASE/goals.json?auth
token=$BEEMINDERAUTH_TOKEN \
| jq [.[] | select(.safebuf <= 0)] | sort_by(.losedate) | .[] | {slug, baremin, limsum}
N天内到期的目标
bash
curl -s $BASE/goals.json?auth
token=$BEEMINDERAUTH_TOKEN \
| jq --arg cutoff $(date -d +2 days +%s) \
[.[] | select(.losedate <= ($cutoff | tonumber))] | sort_by(.losedate) | .[] | {slug, baremin, limsum}
数据点
添加数据点
bash
curl -s -X POST $BASE/goals/GOAL/datapoints.json \
-d auth
token=$BEEMINDERAUTH_TOKEN \
-d value=N \
-d comment=TEXT
可选：-d requestid=UNIQUE_ID 用于幂等重试（可安全重复而不产生重复数据）。
获取最近数据点
bash
curl -s $BASE/goals/GOAL/datapoints.json?auth
token=$BEEMINDERAUTH_TOKEN&count=5&sort=daystamp
更新数据点
bash
curl -s -X PUT $BASE/goals/GOAL/datapoints/DATAPOINT_ID.json \
-d auth
token=$BEEMINDERAUTH_TOKEN \
-d value=N \
-d comment=TEXT
删除数据点
bash
curl -s -X DELETE $BASE/goals/GOAL/datapoints/DATAPOINT
ID.json?authtoken=$BEEMINDER
AUTHTOKEN
常见模式
检查并报告到期项
bash
curl -s $BASE/goals.json?auth
token=$BEEMINDERAUTH_TOKEN \
| jq [.[] | select(.safebuf <= 1)] | sort_by(.safebuf) | .[] | {slug, baremin, limsum, safebuf}
使用幂等重试添加数据
bash
curl -s -X POST $BASE/goals/GOAL/datapoints.json \
-d auth
token=$BEEMINDERAUTH_TOKEN \
-d value=1 \
-d comment=done \
-d requestid=GOAL-$(date +%Y%m%d)
注意事项
- - 基础URL必须严格为 https://www.beeminder.com/api/v1/（需要https和www）
- 所有响应均为JSON格式
- 使用 jq 解析响应
- 日期戳使用 YYYYMMDD 格式
- 时间戳为Unix纪元秒数
