beeminder

Beeminder API 用于目标跟踪和承诺设备。在检查 Beeminder 目标、添加数据点、查看到期目标、管理承诺或跟踪习惯时使用。触发“beeminder”、“目标到期”、“添加数据点”、“跟踪习惯”、“目标状态”、“脱轨”。

## 概述（中文）

Beeminder API 用于目标跟踪和承诺设备。在检查 Beeminder 目标、添加数据点、查看到期目标、管理承诺或跟踪习惯时使用。触发“beeminder”、“目标到期”、“添加数据点”、“跟踪习惯”、“目标状态”、“脱轨”。

## 原文

# 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