canonical: https://jentic.com/apis/beeminder.com/beeminder # Beeminder Jentic publishes the only available OpenAPI specification for Beeminder, keeping it validated and agent-ready. Beeminder is a goal-tracking service that pairs quantified self data with monetary commitment contracts: users define a goal with a numeric target, the system draws a yellow brick road, and if data points fall off the road the user is charged a pledge that escalates with each derailment. The 16-endpoint API exposes user goals, datapoints, charge handling, and goal-control operations like shortcircuit and stepdown, secured by an auth_token query parameter. ## For AI agents Track quantified-self goals and submit datapoints, manage goal pledges, and trigger derailment charges through Beeminder's 16-endpoint API. ## Scope Does not handle generic task lists, calendar events, or device-side activity tracking - use for goal datapoints, pledge management, and accountability charges only. ## Capabilities - Create a Beeminder goal with a numeric target, deadline, and pledge amount - Submit datapoints to a goal so the yellow brick road updates with measured progress - Update or delete previously submitted datapoints to correct a recording mistake - Refresh a goal graph to recompute the road and derailment risk - Short-circuit a goal to derail the user immediately and trigger a pledge charge - Step the pledge up or down for a goal and cancel a pending stepdown - Issue a charge against the user's payment method for an off-app accountability bet ## Use cases ### Quantified-self automation from trackers Users wire wearables, time-trackers, and habit apps to Beeminder so the data flows in automatically and the commitment contract enforces consistency. POST `/users/{userId}/goals/{goalSlug}/datapoints` submits a single datapoint and POST `/users/{userId}/goals/{goalSlug}/datapoints/create_all` batches multiple. Combined with PUT and DELETE, an integration can correct or replay history without leaving the goal off-road. Example prompt: Submit a datapoint of 5000 with comment fitbit-sync to goal slug daily-steps for the current user dated today ### Pledge management for accountability Power users adjust their pledge schedule to match how serious a goal is becoming. POST `/users/{userId}/goals/{goalSlug}/stepdown` queues a stepdown on the pledge ladder and POST `/users/{userId}/goals/{goalSlug}/cancel_stepdown` reverses it before it takes effect. POST `/users/{userId}/goals/{goalSlug}/shortcircuit` forces an immediate derailment and pledge charge when the user wants to acknowledge a slip. Example prompt: Stepdown the pledge on goal slug morning-run and confirm the next pledge level shown after the cancellation window ### Off-app charges for arbitrary accountability bets Beeminder offers POST /charges.json so apps and agents can charge a Beeminder user a specific dollar amount with a note for any external accountability bet (a coach paying a client back when they hit a milestone, or vice versa). The charge uses the user's stored payment method and shows up alongside derailment charges in their account. Example prompt: Issue a 10 USD charge to the authenticated user with note coaching-bet missed milestone via POST /charges.json ### AI agent integration for goal accountability Self-quantifiers and coaches use AI agents through Jentic to keep Beeminder goals fed with the right data: pulling daily pushup counts from a workout tracker, refreshing graphs after a manual entry, or stepping up pledges when a streak grows. The agent searches Jentic for the right Beeminder operation, loads the schema, and executes with the auth_token held in your Jentic One instance, so the token is never exposed in agent context or query strings outside the call. Example prompt: Through Jentic, find Beeminder's submit datapoint operation and log today's 30-minute meditation session against goal slug meditation ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/users/{userId}.json` | Get the user's profile | | GET | `/users/{userId}/goals.json` | List active goals | | POST | `/users/{userId}/goals.json` | Create a new goal | | POST | `/users/{userId}/goals/{goalSlug}/datapoints.json` | Submit a datapoint | | POST | `/users/{userId}/goals/{goalSlug}/datapoints/create_all.json` | Bulk submit datapoints | | POST | `/users/{userId}/goals/{goalSlug}/shortcircuit.json` | Derail and charge immediately | | POST | `/users/{userId}/goals/{goalSlug}/stepdown.json` | Stepdown the pledge | | POST | `/charges.json` | Issue an off-app charge | ## Key resources - **Users** — User profile and the user's active and archived goals - **Goals** — Goal definition, configuration, and graph refresh - **Datapoints** — Per-goal data submissions with create, update, delete, and bulk create - **Goal Controls** — Shortcircuit, stepdown, and cancel-stepdown pledge operations - **Charges** — Off-app charges against the user's payment method ## Why Jentic - **Setup:** Wiring Beeminder by hand means appending your auth_token to the query string, keeping it out of shareable logs, and threading user ids and goal slugs through the datapoint and charge calls yourself. Through Jentic you install once, import Beeminder from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Beeminder puts the user id and goal slug in the URL path (`/users/{userId}/goals/{goalSlug}/datapoints.json`), so a rule can pin your agent to one goal: it submits datapoints for that goal and nothing else. You choose the operations it may call, so destructive ones like shortcircuit, stepdown, or charges are not included unless you add them. - **Credential handling:** Your Beeminder auth_token is stored once, encrypted, by your own Jentic One instance and appended to the query string at execution time, redacted from logs. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'submit a Beeminder datapoint' or 'read my goals', and Jentic returns the matching Beeminder operation with its input schema so the agent calls `/users/{userId}/goals/{goalSlug}/datapoints.json` without browsing the reference docs. ## Related APIs - **Habitica** — Gamified habit and task tracker; alternative when monetary pledge accountability is not the right motivator. - **Strava** — Activity-tracking platform commonly piped into Beeminder for running, cycling, and swimming goals. - **Fitbit** — Wearable activity and sleep data source feeding Beeminder goals. ## FAQ ### Why is there no official OpenAPI spec for Beeminder? Beeminder publishes API documentation but not a maintained OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Beeminder via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Beeminder API use? Beeminder uses an auth_token sent as a query parameter on every request. You generate the token from your Beeminder account settings. Jentic stores the token in its vault and appends auth_token at execution time so it never enters agent context, and Jentic redacts it from logs. ### Can I submit datapoints to a Beeminder goal through the API? Yes. POST `/users/{userId}/goals/{goalSlug}/datapoints.json` submits a single datapoint with a value and optional comment, and `/users/{userId}/goals/{goalSlug}/datapoints/create_all.json` batches several. PUT and DELETE on `/users/{userId}/goals/{goalSlug}/datapoints/{datapointId}.json` correct or remove a prior entry. ### How do I trigger a pledge charge through Jentic? Search Jentic for derail a Beeminder goal to find POST `/users/{userId}/goals/{goalSlug}/shortcircuit.json`, which derails immediately and charges the current pledge. For a non-goal-related accountability charge, use POST /charges.json with the amount and note. Both calls execute through Jentic with the auth_token injected from the vault. ### Does the Beeminder API let me change a goal's pledge schedule? Yes. POST `/users/{userId}/goals/{goalSlug}/stepdown.json` schedules a stepdown to the next-lower pledge after the standard delay, and POST `/users/{userId}/goals/{goalSlug}/cancel_stepdown.json` cancels a queued stepdown before it takes effect. ### What are the rate limits for the Beeminder API? Beeminder does not document a hard rate limit in the spec; the service is designed for occasional human-scale writes plus tracker integrations. If you receive HTTP 429 responses, back off and retry, and avoid tight polling loops on /refresh_graph since that endpoint runs an expensive recompute server-side. ### Can I list a user's archived goals via the API? Yes. GET `/users/{userId}/goals/archived.json` returns archived goals for a user, complementing GET `/users/{userId}/goals.json` for active goals. Use the user_id self to refer to the authenticated user without knowing their numeric ID. ### Can I limit what my agent is allowed to do with the Beeminder API? Yes. Because Jentic One is self-hosted, your own rules decide which Beeminder operations and credentials the agent may use. Since Beeminder puts the user id and goal slug in the URL path, such as `/users/{userId}/goals/{goalSlug}/datapoints.json`, you can pin the agent to a single goal so it only submits datapoints there and touches nothing else. You also choose the operations it may call, so destructive ones like shortcircuit, stepdown, and /charges.json stay out of reach unless you explicitly add them.