NAV
shell ruby
  • Beeminder API Reference
  • Authentication
  • User Resource
  • Goal Resource
  • Datapoint Resource
  • Charge Resource
  • Webhooks
  • Errors
  • Beeminder API Reference

    Introduction

    See github.com/beeminder for API libraries in various languages. Examples here are currently just Curl and Ruby.

    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.

    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!

    If you're looking for ideas for things to do with the Beeminder API, we have a blog post with lots of examples. While we're talking about things that people have done with the Beeminder API, we want to ladle out some extra praise for the Intend and TaskRatchet integrations. Malcolm and Narthur, respectively, have built useful Beeminder integrations without us having to lift a finger. A beautiful example of our API earning its keep.

    Preliminaries

    API Base URL

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

    You may also consume the Beeminder API via RapidAPI.

    Troubleshooting

    A common mistake is to use the wrong URL, e.g., using an http protocol instead of https, or leaving out the www subdomain. We redirect insecure and non www requests to the canonical Beeminder URL, but do not forward parameters for POST requests, so some things will break opaquely if you don't use exactly the above base URL. (And even worse, others will not.)

    Also, please pay attention to the type of HTTP request an endpoint is expecting. For example, the Goal#create endpoint and Goal#update endpoint differ primarily in whether you are making a POST or a PUT request (respectively).

    Backwards Compatibility

    A note of caution for the reader: We document the User and Goal resources below, explaining various attributes that you will find in the API outputs. If you inspect the API outputs you get, however, you'll probably notice a bunch of info that's not included here. You can use any of that info you like, but it may change at our whim down the road. (That's why we don't document it.)

    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:

      curl 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

      curl 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 a single parameter, access_token in the body of the request. The value of this parameter will be the token that was de-authorized.

    6. Optional: Autofetch callback

    The autofetch callback URL is also optional. We will POST to this URL if provided, including the parameters username and slug in the body of the request 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 a beemergency 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

      curl https://www.beeminder.com/api/v1/users/alice.json?auth_token=abc123
    
      { "username": "alice",
        "timezone": "America/Los_Angeles",
        "updated_at": 1343449880,                       
        "goals": ["gmailzero", "weight"] }
    
      require 'beeminder'
    
      bee = Beeminder::User.new "yourtoken"
      bee.info
    
      curl https://www.beeminder.com/api/v1/users/alice.json?diff_since=1352561989&auth_token=abc123
    
      { "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

      curl https://www.beeminder.com/api/v1/users/alice.json?auth_token=abc123&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 bright red line, the graph image, and various settings for the goal.

    Attributes

    A note about rate, date, and val: 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.

    A detailed note about goal types: 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.

    parameter hustler biker fatloser gainer inboxer drinker
    yaw 1 1 -1 1 -1 -1
    dir 1 1 -1 1 -1 1
    kyoom true false false false false true
    odom false true false false false false
    edgy false false false false false true
    aggday "sum" "last" "min" "max" "min" "sum"
    steppy true true false false true true
    rosy false false true true false false
    movingav false false true true false false
    aura false false true true false false

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

    MOAR = dir +1 & yaw +1: "go up, like work out more"
    PHAT = dir -1 & yaw -1: "go down, like weightloss or gmailzero"
    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, for which direction the bright red line is expected to go, 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 safebuf (see code in sidebar).

    color = (safebuf < 1 ? "red"    :
             safebuf < 2 ? "orange" :
             safebuf < 3 ? "blue"   : 
             safebuf < 7 ? "green"  : "gray")
    

    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 right side of the bright red line till the end suffices.

    Get information about a goal

    Examples

      curl https://www.beeminder.com/api/v1/users/alice/goals/weight.json?auth_token=abc123&datapoints=true
    
      { "slug": "weight",               
        "title": "Weight Loss",         
        "goaldate": 1358524800,         
        "goalval": 166,                 
        "rate": null,                   
        "svg_url":   "http://static.beeminder.com/alice+weight.svg",
        "graph_url": "http://static.beeminder.com/alice+weight.png",
        "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",    
        "goal_type": "fatloser",            
        "losedate": 1358524800,        
        "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

      curl https://www.beeminder.com/api/v1/users/alice/goals.json?auth_token=abc123
    
      [ { "slug": "gmailzero",
          "title": "Inbox Zero",
          "goal_type": "inboxer",
          "svg_url": "http://static.beeminder.com/alice+gmailzero.svg",
          "graph_url": "http://static.beeminder.com/alice+gmailzero.png",
          "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",
          "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",
          "svg_url": "http://static.beeminder.com/alice+fitbit-me.svg",
          "graph_url": "http://static.beeminder.com/alice+fitbit-me.png",
          "thumb_url": "http://static.beeminder.com/alice+fitbit-thumb.png",
          "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. Goals are sorted in descending order of urgency, i.e., increasing order of time to derailment. (There's actually a very tiny caveat to this involving the long-deprecated "sort threshold" parameter. If you don't know what that is then you can ignore this parenthetical!)

    Get archived goals for a user

    Examples

      curl https://www.beeminder.com/api/v1/users/alice/goals/archived.json?auth_token=abc123
    
      [ { "slug": "gmailzero",
          "title": "Inbox Zero",
          "goal_type": "inboxer",
          "svg_url": "http://static.beeminder.com/alice+gmailzero.svg",
          "graph_url": "http://static.beeminder.com/alice+gmailzero.png",
          "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",
          "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",
          "svg_url": "http://static.beeminder.com/alice+fitbit-me.svg",
          "graph_url": "http://static.beeminder.com/alice+fitbit-me.png",
          "thumb_url": "http://static.beeminder.com/alice+fitbit-thumb.png",
          "losedate": 1346482799,
          "goaldate": 1349582400,
          "goalval": null,
          "rate": 8.0,
          "updated_at": 1345771188,
          "queued": false } ]
    

    HTTP Request

    GET /users/u/goals/archived.json

    Get user u's archived goals.

    Parameters

    None.

    Returns

    A list of Goal objects representing the user's archived goals.

    Create a goal for a user

    Examples

      curl -X POST https://www.beeminder.com/api/v1/users/alice/goals.json \
        -d auth_token=abc123 \
        -d slug=exercise \
        -d title=Work+Out+More \
        -d goal_type=hustler \
        -d goaldate=1400000000 \
        -d gunits=workouts \
        -d rate=5 \
        -d goalval=null
    
      { "slug": "exercise",
        "title": "Work Out More",
        "goal_type": "hustler",
        "svg_url": "http://static.beeminder.com/alice+exercise.svg",
        "graph_url": "http://static.beeminder.com/alice+exercise.png",
        "thumb_url": "http://static.beeminder.com/alice+exercise-thumb.png",
        "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 to your callback when this goal wants new data, as outlined in Client OAuth.

    Returns

    The newly created Goal object.

    Update a goal for a user

    Examples

      curl -X PUT https://www.beeminder.com/api/v1/users/alice/goals/exercise.json \
        -d auth_token=abc124 \
        -d title=Work+Out+Even+More \
        -d secret=true
    
      { "slug": "exercise",
        "title": "Work Out Even More",
        "goal_type": "hustler",
        "svg_url": "http://static.beeminder.com/alice+exercise.svg",
        "graph_url": "http://static.beeminder.com/alice+exercise.png",
        "thumb_url": "http://static.beeminder.com/alice+exercise-thumb.png",
        "secret": true,
        "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 roadall.

    Parameters

    Returns

    The updated Goal object.

    Force a fetch of autodata and graph refresh

    Example Request

      curl https://www.beeminder.com/api/v1/users/alice/goals/weight/refresh_graph.json?auth_token=abc123
    
      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 aka bright red line

      // Example request
    
      curl -X POST https://www.beeminder.com/api/v1/users/alice/goals/weight/dial_road.json \
        -d auth_token=abc124 \
        -d rate=-0.5 \
        -d goalval=166 \
        -d goaldate=null
    
      // Example result
    
      { "slug": "weight",                       
        "title": "Weight Loss",                 
        "goal_type": "fatloser",                    
        "svg_url": "http://static.beeminder.com/alice+weight.svg",
        "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 aka bright red line (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

      curl https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints.json?auth_token=abc123
    
      [{"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

    Returns

    The list of Datapoint objects.

    Create a datapoint

    Examples

      curl -X POST https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints.json \
        -d auth_token=abc123 \
        -d timestamp=1325523600 \
        -d value=130.1 \
        -d 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

      curl -X POST https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints/create_all.json \
        -d auth_token=abc123 \
        -d 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

    A list of successfully created Datapoints. Or, in the case of any errors, you will receive an object with two lists, successes, and errors.

    Update a datapoint

    Examples

      curl -X PUT https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints/5016fa9adad11576ad00000f.json \
        -d auth_token=abc123 \
        -d 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

      curl -X DELETE https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints/5016fa9adad11576ad00000f.json?auth_token=abc123
    
      { "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 user_id=alice \
        -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 Code Meaning
    400 Bad Request
    401 Unauthorized — Wrong / missing key. (Check your parameter name?)
    404 Not Found — Couldn't find that resource, or path requested.
    406 Not Acceptable — Check the format of your params?
    500 Internal Server Error — We had a problem with our server. Try again later.
    503 Service Unavailable — We're temporarily offline for maintenance. Please try again later.