API Usage

API access requires an active $5/month subscription. Authenticate billing and account requests with your JWT, then use an API key for todo CRUD.

Machine-readable contract: /api/v1/openapi.json

Setup

Your JWT is returned when you log in or sign up. Your API_KEY is returned when you create an API key.

API_URL="https://api.braindump.latentedge.io"
JWT="your_jwt_from_login"
API_KEY="bdk_..."

Downloadable Agent Skill

Install this Codex-style skill on another machine so an agent knows how to use Brain Dump API keys and the todo CRUD endpoints without rediscovering the API.

Download skill zip View SKILL.md View helper script

Install on an agent machine

SKILLS_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$SKILLS_DIR"
curl -L "https://braindump.latentedge.io/skills/brain-dump-api-skill.zip" -o /tmp/brain-dump-api-skill.zip
unzip -o /tmp/brain-dump-api-skill.zip -d "$SKILLS_DIR"
chmod +x "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py"
export BRAINDUMP_API_KEY="bdk_your_key_here"

Use the bundled todo helper

python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" list
python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" create --text "Send project update" --priority 2 --category work --minutes 25
python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" update 123 --text "Send final project update" --priority 1
python "$SKILLS_DIR/brain-dump-api/scripts/braindump_todos.py" delete 123

Billing & Subscription

Check API subscription status and create a checkout session for paid access.

View subscription status

curl -sS "$API_URL/api/v1/billing/subscription" \
  -H "Authorization: Bearer $JWT"

Start checkout session

curl -sS -X POST "$API_URL/api/v1/billing/checkout-session" \
  -H "Authorization: Bearer $JWT"

Open billing portal

curl -sS -X POST "$API_URL/api/v1/billing/portal-session" \
  -H "Authorization: Bearer $JWT"

Cancel at period end

curl -sS -X POST "$API_URL/api/v1/billing/subscription/cancel" \
  -H "Authorization: Bearer $JWT"

Resume renewal

curl -sS -X POST "$API_URL/api/v1/billing/subscription/reactivate" \
  -H "Authorization: Bearer $JWT"

API Key Management

Authenticate with your JWT in the Authorization header. These endpoints return 402 SUBSCRIPTION_REQUIRED while your subscription is inactive.

Create key

curl -sS -X POST "$API_URL/api/v1/auth/api-keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"name":"My automation key"}'

List keys

curl -sS "$API_URL/api/v1/auth/api-keys" \
  -H "Authorization: Bearer $JWT"

Revoke key

curl -sS -X DELETE "$API_URL/api/v1/auth/api-keys/<key_id>" \
  -H "Authorization: Bearer $JWT"

Account Security & Privacy (JWT)

Manage active sessions, rotate password, export data, and delete your account.

List sessions

curl -sS "$API_URL/api/v1/auth/sessions" \
  -H "Authorization: Bearer $JWT"

Revoke session

curl -sS -X DELETE "$API_URL/api/v1/auth/sessions/<session_id>" \
  -H "Authorization: Bearer $JWT"

Change password

curl -sS -X POST "$API_URL/api/v1/auth/change-password" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"currentPassword":"old-pass","newPassword":"new-pass-123","newPasswordConfirm":"new-pass-123"}'

Export account data

curl -sS "$API_URL/api/v1/account/export" \
  -H "Authorization: Bearer $JWT"

Delete account

curl -sS -X DELETE "$API_URL/api/v1/account" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"password":"current-pass","confirmText":"DELETE"}'

Todo CRUD (API Key)

Authenticate with your API key as Authorization: Bearer <API_KEY>.

List todos

curl -sS "$API_URL/api/v1/todos" \
  -H "Authorization: Bearer $API_KEY"

Create todo

curl -sS -X POST "$API_URL/api/v1/todos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"text":"Ship integration","priority":2,"category":"work","estimatedDurationMinutes":30}'

Update todo

curl -sS -X PUT "$API_URL/api/v1/todos/123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"text":"Ship integration v2","priority":1}'

Delete todo

curl -sS -X DELETE "$API_URL/api/v1/todos/123" \
  -H "Authorization: Bearer $API_KEY"