NAV Navbar
Bee logo 110
curl

Beeminder API Reference

Introduction

See github.com/beeminder for API libraries in various languages. Examples here are currently just curl so far.

In case you’re here to automate adding data to Beeminder, there’s a good chance we’ve got you covered with our Zapier integration or our IFTTT integration. If you’re looking for ideas for things to do with the Beeminder API, we have a blog post with lots of examples. The tech category of our forum is a good place to ask questions and show off what you’re working on.

It’s really important to us that this API be easy for developers to use so please don’t be shy about asking us questions. Whether you post in the forum or email us at support@beeminder.com we’ve invariably found that questions people avoided asking for fear they were dumb turned out to point to things we needed to improve in the API or the documentation. So lean on us heavily as you’re hacking away with our API – it helps us a lot when you do!

Preliminaries

The base URL for all requests is https://www.beeminder.com/api/v1/

You may also consume the Beeminder API via Mashape:    

Back to top

Authentication

All API endpoints require authentication. There are two ways to authenticate. Both ultimately give you a token which you must then include with every API request.

Personal authentication token

For example, if your username is “alice” and your token is “abc123” you can query information about your “weight” goal like so:

GET https://www.beeminder.com/api/v1/users/alice/goals/weight.json?auth_token=abc123

This authentication pattern is for making API calls just to your own Beeminder account.

After you log in to Beeminder, visit https://www.beeminder.com/api/v1/auth_token.json to get your personal auth token. Append it to API requests you make as an additional GET or POST parameter.

Client OAuth

This authentication pattern is for clients (applications) accessing the Beeminder API on a user’s behalf. Beeminder implements the OAuth provider protocol to allow access reasonably securely.

There are four steps to build a client:

1. Register your app

Register your app at beeminder.com/apps/new. Application name and redirect URL are required. The redirect URL is where the user is sent after authorizing your app.

2. Send your users to the Beeminder authorization URL

Example authorization URL:

  https://www.beeminder.com/apps/authorize?\ 
   client_id=xyz456&redirect_uri=http://foo.com/auth_callback\ 
   &response_type=token

The base URL is the same for all apps: https://www.beeminder.com/apps/authorize. You’ll need to add the following parameters:

3. Receive and store user’s access token

For example, if the user “alice” has access token “abc123” then the following string would be appended to the URL when the user is redirected there:

  ?access_token=abc123&username=alice

After the user authorizes your application they’ll be redirected to the redirect_uri that you specified, with two additional parameters, access_token and username, in the query string.

You should set up your server to handle this GET request and have it remember each user’s access token. The access token uniquely identifies the user’s authorization for your app.

The username is provided here for convenenience. You can retrieve the username for a given access token at any time by sending a GET request for /api/v1/me.json with the token appended as a parameter.

4. Include access token as a parameter

  GET https://www.beeminder.com/api/v1/users/me.json?access_token=abc123

Append the access token as a parameter on any API requests you make on behalf of that user. For example, your first request will probably be to get information about the User who just authorized your app.

You can literally use “me” in place of the username for any endpoint and it will be macro-expanded to the username of the authorized user.

5. Optional: De-authorization callback

If you provide a Post De-Authorization Callback URL when you register your client, we will make a POST to your endpoint when a user removes your app. The POST will include the access_token removed in the body of the request.

6. Optional: Autofetch callback

The autofetch callback URL is also optional. We will POST to this URL if provided, including the params username, and slug when the user wants new data from you. E.g., when the user pushes the manual refresh button, or prior to sending alerts to the user, and before derailing the goal at the end of an eep day.

Back to top

User Resource

A User object (“object” in the JSON sense) includes information about a user, like their list of goals.

Attributes

Get information about a user

Examples

  GET /api/v1/users/alice.json?goals_filter=frontburner

  { "username": "alice",
    "timezone": "America/Los_Angeles",
    "updated_at": 1343449880,                       
    "goals": ["gmailzero", "weight"] }
  GET /api/v1/users/alice.json?diff_since=1352561989

  { "username": "alice",
    "timezone": "America/Los_Angeles",
    "updated_at": 1343449880,                       
    "goals": [ {"slug": "weight", ..., 
               "datapoints": [{"timestamp": 1325523600,    
                    "value": 70.45,            
                    "comment": "blah blah",     
                    "id": "4f9dd9fd86f22478d3"}, 
                   {"timestamp": 1325610000,
                    "value": 70.85,
                    "comment": "blah blah", 
                    "id": "5f9d79fd86f33468d4"}], 
               "title": "Weight Loss", ...}, 
               { another goal }, ... ],
    "deleted_goals": [{ "id": "519279fd86f33468ne"}, ... ] 
}

HTTP Request

GET /users/u.json

Retrieves information and a list of goalnames for the user with username u.

Since appending an access_token to the request uniquely identifies a user, you can alternatively make the request to /users/me.json (without the username).

Parameters

Returns

A User object.

Use the updated_at field to be a good Beeminder API citizen and avoid unnecessary requests for goals and datapoints. Any updates to a user, their goals, or any datapoints on any of their goals will cause this field to be updated to the current unix timestamp. If you store the returned value and, on your next call to this endpoint, the value is the same, there’s no need to make requests to other endpoints.

Checking the timestamp is an order of magnitude faster than retrieving all the data, so it’s definitely wise to use this approach.

Authenticate and redirect the user

Examples

  GET /api/v1/users/alice.json?redirect_to_url=https%3A%2F%2Fwww.beeminder.com%2Fpledges

HTTP Request

GET /users/u.json

Attempts to authenticate the user and if successful redirects to the given URL. Allows third-party apps to send the user to a specific part of the website without getting intercepted by a login screen, for doing things not available through the API.

Parameters

Back to top

Goal Resource

A Goal object includes everything about a specific goal for a specific user, including the target value and date, the steepness of the yellow brick road, the graph image, and various settings for the goal.

Attributes

The goal types are shorthand for a collection of settings of more fundamental goal attributes. Note that changing the goal type of an already-created goal has no effect on those fundamental goal attributes. The following table lists what those attributes are.

hustlerbikerfatlosergainerinboxerdrinker
yaw11-11-1
dir11-11-1
exprdfalsefalsefalsefalsefalse
kyoomtruefalsefalsefalsefalse
odomfalsetruefalsefalsefalse
edgyfalsefalsefalsefalsefalse
noisyfalsefalsetruetruefalse
aggday“sum”“last”“min”“last”“min”
steppytruetruefalsefalsetrue
rosyfalsefalsetruetruefalse
movingavfalsefalsetruetruefalse
aurafalsefalsetruetruefalse

There are four broad, theoretical categories – called the platonic goal types – that goals fall into, defined by dir and yaw:

PHAT = dir -1 & yaw -1: “go down, like weightloss or gmailzero”
MOAR = dir +1 & yaw +1: “go up, like work out more”
WEEN = dir +1 & yaw -1: “go up less, like quit smoking”
RASH = dir -1 & yaw +1: “go down less, ie, rationing, for example

The dir parameter is mostly just for the above categorization, but is used specifically in the following ways:

  1. Where to draw the watermarks (amount pledged and number of safe days)
  2. How to phrase things like “bare min of +123 in 4 days” and the status line (also used in bot email subjects)
  3. Which direction is the optimistic one for the rosy dots algorithm

If you just want the dot color, here’s how to infer it from lane and yaw:

Finally, the way to tell if a goal has finished successfully is now >= goaldate && goaldate < losedate. That is, you win if you hit the goal date before hitting losedate. You don’t have to actually reach the goal value – staying on the yellow brick road till the end suffices.

Get information about a goal

Examples


  GET /api/v1/users/alice/goals/weight.json?datapoints=true

  { "slug": "weight",               
    "title": "Weight Loss",         
    "goaldate": 1358524800,         
    "goalval": 166,                 
    "rate": null,                   
    "graph_url": "http://static.beeminder.com/alice+weight.png",
    "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",    
    "goal_type": "fatloser",            
    "losedate": 1358524800,        
    "panic": 54000,                 
    "queued": false,                
    "updated_at": 1337479214,       
    "datapoints": [{"timestamp": 1325523600,    
                    "value": 70.45,            
                    "comment": "blah blah",     
                    "id": "4f9dd9fd86f22478d3"}, 
                   {"timestamp": 1325610000,
                    "value": 70.85,
                    "comment": "blah blah",
                    "id": "5f9d79fd86f33468d4"}]}

HTTP Request

GET /users/u/goals/g.json

Gets goal details for user u‘s goal g – beeminder.com/u/g.

Parameters

Returns

A Goal object, possibly without the datapoints attribute.

Get all goals for a user

Examples

  GET /api/v1/users/alice/goals.json?filter=frontburner

  [ 
    { "slug": "gmailzero",
      "title": "Inbox Zero",
      "goal_type": "inboxer",
      "graph_url": "http://static.beeminder.com/alice+gmailzero.png",
      "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",
      "panic":54000,
      "losedate": 1347519599,
      "goaldate": 0,
      "goalval": 25.0, 
      "rate": -0.5,
      "updated_at": 1345774578,
      "queued": false },
    { "slug": "fitbit-me",
      "title": "Never stop moving",
      "goal_type": "hustler",
      "graph_url": "http://static.beeminder.com/alice+fitbit-me.png",
      "thumb_url": "http://static.beeminder.com/alice+fitbit-thumb.png",
      "panic": 86400,
      "losedate": 1346482799,
      "goaldate": 1349582400,
      "goalval": null,
      "rate": 8.0,
      "updated_at": 1345771188,
      "queued": false } 
  ]

HTTP Request

GET /users/u/goals.json

Get user u‘s list of goals.

Parameters

None.

Returns

A list of Goal objects for the user.

Create a goal for a user

Examples

  POST /api/v1/users/alice/goals.json?slug=exercise&title=Work+Out+More&goal_type=hustler&goaldate=1400000000&rate=5&goalval=null

  { "slug": "exercise",
    "title": "Work Out More",
    "goal_type": "hustler",
    "graph_url": "http://static.beeminder.com/alice+exercise.png",
    "thumb_url": "http://static.beeminder.com/alice+exercise-thumb.png",
    "panic": 54000,
    "losedate": 1447519599,
    "goaldate": 1400000000,
    "goalval": null, 
    "rate": 5,
    "updated_at": 1345774578,
    "queued": false }

HTTP Request

POST /users/u/goals.json

Create a new goal for user u.

Parameters

Exactly two out of three of goaldate, goalval, and rate are required.

If you pass in your API client’s registered name for the datasource, and your client has a registered autofetch_callback_url, we will POST {username: u, slug: s} to your callback when this goal wants new data.

Returns

The newly created Goal object.

One of the three fields goaldate, goalval, and rate will return a null value. This indicates that the value is calculated based on the other two fields, as selected by the user.

Update a goal for a user

Examples

  PUT /api/v1/users/alice/goals.json?slug=exercise&title=Work+Out+Even+More&panic=3600

  { "slug": "exercise",
    "title": "Work Out Even More",
    "goal_type": "hustler",
    "graph_url": "http://static.beeminder.com/alice+exercise.png",
    "thumb_url": "http://static.beeminder.com/alice+exercise-thumb.png",
    "panic": 3600,
    "losedate": 1447519599,
    "goaldate": 1400000000,
    "goalval": null, 
    "rate": 5,
    "updated_at": 1345774578,
    "queued": false }

HTTP Request

PUT /users/u/goals/g.json

Update user u‘s goal with slug g. This is similar to the call to create a new goal, but the goal type (goal_type) cannot be changed. To change any of {goaldate, goalval, rate} use the dial_road call below.

Parameters

Returns

The updated Goal object.

Force a fetch of autodata and graph refresh

Example Request

  GET /api/v1/users/alice/goals/weight/refresh_graph.json

  true

HTTP Request

GET /users/u/goals/g/refresh_graph.json

Analagous to the refresh button on the goal page. Forces a refetch of autodata for goals with automatic data sources. Refreshes the graph image regardless. Please be extremely conservative with this endpoint!

Parameters

None.

Returns

This is an asynchronous operation, so this endpoint simply returns true if the goal was queued and false if not. It is up to you to watch for an updated graph image.

[deprecated] Update a yellow brick road

  // Example request 

  POST /api/v1/users/alice/goals/weight/dial_road.json?rate=-0.5&goalval=166&goaldate=null

  // Example result

  { "slug": "weight",                       
    "title": "Weight Loss",                 
    "goal_type": "fatloser",                    
    "graph_url": "http://static.beeminder.com/alice+weight.png",
    "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",
    "goaldate": null,                 
    "goalval": 166,                         
    "rate": -0.5,                           
    "losedate": 1358524800 }

HTTP Request

POST /users/u/goals/g/dial_road.json

Change the slope of the yellow brick road (starting after the one-week Akrasia Horizon) for beeminder.com/u/g.

Parameters

Exactly two of goaldate, goalval, and rate should be specified – setting two implies the third.

Returns

The updated Goal object.

Short circuit a goal’s pledge

HTTP Request

POST /users/u/goals/g/shortcircuit.json

Increase the goal’s pledge level and charge the user the amount of the current pledge.

Parameters

None

Returns

The updated Goal object.

Step down a goal’s pledge

HTTP Request

POST /users/u/goals/g/stepdown.json

Decrease the goal’s pledge level subject to the akrasia horizon, i.e., not immediately. After a successful request the goal will have a countdown to when it will revert to the lower pledge level.

Parameters

None

Returns

The updated Goal object.

Cancel a scheduled step down

HTTP Request

POST /users/u/goals/g/cancel_stepdown.json

Cancel a pending stepdown of a goal’s pledge. The pledge will remain at the current amount.

Parameters

None

Returns

The updated Goal object.

Back to top

Datapoint Resource

A Datapoint consists of a timestamp and a value, an optional comment, and meta information. A Datapoint belongs to a Goal, which has many Datapoints.

Attributes

Get all the datapoints

Examples

  GET /api/v1/users/alice/goals/weight/datapoints.json

  [{"id":"1", "timestamp":1234567890, "daystamp":"20090213", "value":7, "comment":"", "updated_at":123, "requestid":"a"}, 
   {"id":"2", "timestamp":1234567891, "daystamp":"20090214", "value":8, "comment":"", "updated_at":123, "requestid":"b"}]

HTTP Request

GET /users/u/goals/g/datapoints.json

Get the list of datapoints for user u‘s goal g – beeminder.com/u/g.

Parameters

None.

Returns

The list of Datapoint objects.

Create a datapoint

Examples

  POST /api/v1/users/alice/goals/weight/datapoints.json?timestamp=1325523600&value=130.1&comment=sweat+a+lot+today

  { "timestamp": 1325523600,
    "daystamp": "20120102",
    "value": 130.1,         
    "comment": "sweat a lot today",   
    "id": "4f9dd9fd86f22478d3000008",
    "requestid":"abcd182475925"}

HTTP Request

POST /users/u/goals/g/datapoints.json

Add a new datapoint to user u‘s goal g – beeminder.com/u/g.

Parameters

Returns

The updated Datapoint object.

Create multiple datapoints

Examples

  POST /api/v1/users/alice/goals/weight/datapoints/create_all.json?datapoints=[{"timestamp":1343577600,"value":220.6,"comment":"blah+blah", "requestid":"abcd182475929"}, {"timestamp":1343491200,"value":220.7, "requestid":"abcd182475930"}]

  [ { "id": "5016fa9adad11576ad00000f", 
      "timestamp": 1343577600, 
      "daystamp": "20120729",
      "value": 220.6, 
      "comment": "blah blah", 
      "updated_at": 1343577600,
      "requestid":"abcd182475923"}, 
    { "id": "5016fa9bdad11576ad000010", 
      "timestamp": 1343491200, 
      "daystamp": "20120728",
      "value": 220.7, 
      "comment": "", 
      "updated_at": 1343491200,
      "requestid":"abcd182475923" } ]

HTTP Request

POST /users/u/goals/g/datapoints/create_all.json

Create multiple new datapoints for beeminder.com/u/g.

Parameters

Returns

The list of created Datapoints.

Update a datapoint

Examples

  PUT /api/v1/users/alice/goals/weight/datapoints/5016fa9adad11576ad00000f.json&comment=a+real+comment

  { "id": "5016fa9adad11576ad00000f", 
    "value": 220.6, 
    "comment": "a real comment", 
    "timestamp": 1343577600, 
    "daystamp": "20120729",
    "updated_at": 1343577609 }

HTTP Request

PUT /users/u/goals/g/datapoints/id.json

Update the datapoint with ID id for user u‘s goal g (beeminder.com/u/g).

Parameters

Returns

The updated Datapoint object.

Delete a datapoint

Examples

  DELETE /api/v1/users/alice/goals/weight/datapoints/5016fa9adad11576ad00000f.json

  { "id": "5016fa9adad11576ad00000f", 
    "value": 220.6, 
    "comment": "a real comment", 
    "timestamp": 1343577600, 
    "daystamp": "20120729",
    "updated_at": 1343577609 }

HTTP Request

DELETE /users/u/goals/g/datapoints/id.json

Delete the datapoint with ID id for user u‘s goal g (beeminder.com/u/g).

Parameters

None.

Returns

The deleted Datapoint object.

Back to top

Charge Resource

Beeminder provides an endpoint to charge an arbitrary amount to a Beeminder user. The user is inferred from the access_token or auth_token provided. A Charge object has the following attributes:

Attributes

Create a charge

Example request

  curl -X POST 'https://www.beeminder.com/api/v1/charges.json' \
    -d auth_token=abc123 \
    -d amount=10 \
    -d note=I%27m+not+worthy%3B+charge+myself+%2410 \

Example response

  { "id": "5016fa9adad11576ad00000f", 
    "amount": 10, 
    "note": "I'm not worthy; charge myself $10", 
    "username": "alice" }

HTTP request

POST /charges

Create a charge of a given amount and optionally add a note.

Parameters

Returns

The Charge object, or an object with the error message(s) if the request was not successful.

Back to top

Webhooks

Example of POSTed data

  { "goal": 
    { "id": "5016fa9adad11576ad00000f", 
    "slug": "example", ... }  
  }

You can configure Beeminder to remind you about goals that are about to derail via webhook, either on the individual goal settings page or on your reminder settings page.

Beeminder will remind you via POST request to the URL you specify with a JSON body with all the attributes specified in the description of the Goal Resource.

Errors

The Beeminder API uses the following error codes. Check your HTTP response code, but also we will usually pass back a JSON object with a key errors that will hopefully illuminate what went wrong.

Error CodeMeaning
400Bad Request
401Unauthorized – Wrong / missing key. (Check your parameter name?)
404Not Found – Couldn’t find that resource, or path requested.
406Not Acceptable – Check the format of your params?
500Internal Server Error – We had a problem with our server. Try again later.
503Service Unavailable – We’re temporarily offline for maintenance. Please try again later.