API Endpoints

GET Endpoints

The following endpoints provide read access to various Kegbot data. All are accessible with HTTP GET operations.

/drinks

Listing of a drinks poured on the current Kegbot system. The results may be paginated; see Pagination for details. Results are sorted by drink id, in decreasing order.

Default Access: Public

Arguments

Argument Description
start First drink ID to show. Default will start with the most recent drink.

Response

Property Type Description
drinks DrinkSet A sequence of Drink objects

Example

// curl http://sfo.kegbot.net/api/drinks/?start=2000
{
  "result": {
    "paging": {
      "total": 2716,
      "limit": 100,
      "pos": 2000
    },
    "drinks": [
      {
        "volume_ml": 490.24793744200002,
        "user_id": "capn",
        "ticks": 1321,
        "session_id": "386",
        "is_valid": true,
        "pour_time": "2009-10-03T17:13:16",
        "duration": 15,
        "keg_id": 13,
        "id": 2000
      },
      {
        "volume_ml": 451.651582034,
        "user_id": "boysdontcall",
        "ticks": 1217,
        "session_id": "386",
        "is_valid": true,
        "pour_time": "2009-10-03T17:12:27",
        "duration": 14,
        "keg_id": 13,
        "id": 1999
      },
      // ...
    ]
  }
}

/drinks/<id>/

Detailed information about a single specific drink.

Default Access: Public

Response

Property Type Description
drink dict The Drink object corresponding to this drink
keg dict The Keg object corresponding to this drink
user dict The User object corresponding to this drink
session dict The Session object corresponding to this drink

Example

// curl http://sfo.kegbot.net/api/drinks/2000/
{
  "result": {
    "keg": {
      "status": "offline",
      "volume_ml_remain": 590.74554188041657,
      "finished_time": "2009-10-17T19:34:06",
      "description": "Racer 5",
      "type_id": "50ad52bc-35fb-4441-a5bf-f56a55608057",
      "started_time": "2009-09-06T14:46:00",
      "size_id": 1,
      "percent_full": 0.010068330147789123,
      "id": 13
    },
    "drink": {
      "volume_ml": 490.24793744200002,
      "user_id": "capn",
      "ticks": 1321,
      "session_id": "386",
      "is_valid": true,
      "pour_time": "2009-10-03T17:13:16",
      "duration": 15,
      "keg_id": 13,
      "id": 2000
    },
    "user": {
      "username": "capn",
      "joined_time": "2004-05-22T20:24:16",
      "mugshot_url": "mugshots/brian-wtf-hula-thing.jpg",
      "is_active": true,
      "is_superuser": false,
      "is_staff": false
    },
    "session": {
      "start_time": "2009-10-03T16:33:07",
      "volume_ml": 0.0,
      "id": "386",
      "end_time": "2009-10-03T20:26:24"
    }
  }
}

/taps/

Listing of all taps in the system.

Default Access: Public

Response

Note: The response is a list with property name taps, containing zero or more of the following structure.

Property Type Description
tap dict The KegTap objects itself
keg dict A Keg object for the current keg, or null.
beverage dict A BeerType object for the current keg, or null.

Example

// curl http://sfo.kegbot.net/api/taps/
{
  "result": {
    "taps": [
      {
        "keg": {
          "status": "online",
          "volume_ml_remain": 299.24664065039542,
          "finished_time": "2010-06-11T23:25:16",
          "description": "Celebrating the World Cup, and international relations, with a beer that's part Austria / part Berkeley.",
          "type_id": "20bd3f32-75eb-11df-80f2-00304833977c",
          "started_time": "2010-06-11T23:25:16",
          "size_id": 1,
          "percent_full": 0.0051001891001911156,
          "id": 17
        },
        "tap": {
          "meter_name": "kegboard.flow0",
          "name": "main tap",
          "ml_per_tick": 0.37111880200000003,
          "thermo_sensor_id": "1",
          "current_keg_id": 17,
          "id": "1"
        }
      }
    ]
  }
}

/taps/<id>/

Shows detailed information about a single tap.

Default Access: Public

Response

Property Type Description
tap dict The KegTap objects itself
keg dict A Keg object for the current keg, or null.

Example

// curl http://sfo.kegbot.net/api/taps/kegboard.flow0/
{
  "result": {
    "keg": {
      "status": "online",
      "volume_ml_remain": 299.24664065039542,
      "finished_time": "2010-06-11T23:25:16",
      "description": "Celebrating the World Cup, and international relations, with a beer that's part Austria / part Berkeley.",
      "type_id": "20bd3f32-75eb-11df-80f2-00304833977c",
      "started_time": "2010-06-11T23:25:16",
      "size_id": 1,
      "percent_full": 0.0051001891001911156,
      "id": 17
    },
    "tap": {
      "meter_name": "kegboard.flow0",
      "name": "main tap",
      "ml_per_tick": 0.37111880200000003,
      "thermo_sensor_id": "1",
      "current_keg_id": 17,
      "id": "1"
    }
  }

/kegs/

Lists all kegs known by the system. The response to this query may be paginated.

Default Access: Public

Response

Property Type Description
keg dict A Keg object corresponding to the keg.

Example

// curl http://sfo.kegbot.net/api/kegs/
{
  "result": {
    "kegs": [
      {
        "status": "online",
        "volume_ml_remain": 299.24664065039542,
        "finished_time": "2010-06-11T23:25:16",
        "description": "Celebrating the World Cup, and international relations, with a beer that's part Austria / part Berkeley.",
        "type_id": "20bd3f32-75eb-11df-80f2-00304833977c",
        "started_time": "2010-06-11T23:25:16",
        "size_id": 1,
        "percent_full": 0.0051001891001911156,
        "id": 17
      },
      {
        "status": "offline",
        "volume_ml_remain": -13363.120936177656,
        "finished_time": "2010-05-29T13:01:20",
        "description": "Memorial Day keg.",
        "type_id": "e29a5d90-6b5c-11df-bcbc-00304833977c",
        "started_time": "2010-05-29T13:01:20",
        "size_id": 1,
        "percent_full": -0.22775341302110927,
        "id": 16
      },
      // ...
    ]
  }
}

/kegs/<id>/

Detailed information about a specific keg.

Default Access: Public

Response

Property Type Description
keg multiple The Keg object for this keg.
type dict The BeerType object for this keg, or null
size dict The KegSize object for this keg, or null
drinks multiple A listing of individual Drink objects poured on this keg.

Example

// curl http://sfo.kegbot.neg/api/kegs/13/
{
  "result": {
    "keg": {
      "status": "offline",
      "volume_ml_remain": 590.74554188041657,
      "finished_time": "2009-10-17T19:34:06",
      "description": "Racer 5",
      "type_id": "50ad52bc-35fb-4441-a5bf-f56a55608057",
      "started_time": "2009-09-06T14:46:00",
      "size_id": 1,
      "percent_full": 0.010068330147789123,
      "id": 13
    },
    "type": {
      "name": "Racer 5",
      "style_id": "8afc60f5-2ee0-40a2-a53a-39c6f43ed4bf",
      "calories_oz": 12.5,
      "abv": 7.2000000000000002,
      "brewer_id": "4360bae4-5522-4fca-8e3a-0edebfc457a5",
      "id": "50ad52bc-35fb-4441-a5bf-f56a55608057"
    },
    "size": {
      "volume_ml": 58673.636363636397,
      "id": 1,
      "name": "15.5 gallon keg"
    }
    "drinks": [
      {
        "volume_ml": 55.667820300000002,
        "user_id": "scarfjerk",
        "ticks": 150,
        "session_id": "390",
        "is_valid": true,
        "pour_time": "2009-10-17T19:34:06",
        "duration": 7,
        "keg_id": 13,
        "id": 2054
      },
      {
        "volume_ml": 441.63137438000001,
        "user_id": null,
        "ticks": 1190,
        "session_id": "390",
        "is_valid": true,
        "user": null,
        "pour_time": "2009-10-17T19:02:55",
        "duration": 11,
        "keg_id": 13,
        "id": 2053
      },
      // ...
    ],
  }
}

/kegs/<id>/drinks/

Lists all drinks assigned to a specific keg. This is the same content as the drinks portion of the /kegs/<id>/ endpoint.

  • Default Access: Public

Response

Property Type Description
drinks multiple A listing of individual Drink objects poured on this keg.

Example

// curl http://sfo.kegbot.net/api/kegs/13/drinks/
{
  "result": {
    "drinks": [
      {
        "volume_ml": 55.667820300000002,
        "user_id": "scarfjerk",
        "ticks": 150,
        "session_id": "390",
        "is_valid": true,
        "pour_time": "2009-10-17T19:34:06",
        "duration": 7,
        "keg_id": 13,
        "id": 2054
      },
      {
        "volume_ml": 441.63137438000001,
        "user_id": null,
        "ticks": 1190,
        "session_id": "390",
        "is_valid": true,
        "user": null,
        "pour_time": "2009-10-17T19:02:55",
        "duration": 11,
        "keg_id": 13,
        "id": 2053
      },
    ]
  }
}

/kegs/<id>/sessions/

Lists all sessions involving specific keg.

Default Access: Public

Response

Property Type Description
sessions multiple A listing of individual Session objects involving this keg.

/users/<id>/

Lists detail about a single user.

Default Access: Public

Response

Property Type Description
user dict A User object corresponding to the user.

Example

// curl http://sfo.kegbot.net/api/users/mikey/
{
  "result": {
    "user": {
      "username": "mikey",
      "joined_time": "2004-05-22T20:22:39Z",
      "mugshot_url": "mugshots/mikey/a12b-mikey-kegbot.jpg",
      "is_active": true,
    }
  }
}

/users/<id>/drinks/

Lists all drinks by a specific user.

Default Access: Public

Response

Property Type Description
drinks multiple A listing of individual Drink objects poured on this keg.

Example

// curl http://sfo.kegbot.net/api/users/mikey/drinks/
{
  "result": {
    "drinks": [
      {
        "volume_ml": 453.13605724199999,
        "user_id": "mikey",
        "ticks": 1221,
        "session_id": "421",
        "is_valid": true,
        "pour_time": "2010-08-22T02:55:53Z",
        "duration": 12,
        "keg_id": 17,
        "id": 2694
      },
      {
        "volume_ml": 333.26468419600002,
        "user_id": "mikey",
        "ticks": 898,
        "session_id": "420",
        "is_valid": true,
        "pour_time": "2010-08-15T18:35:20Z",
        "duration": 8,
        "keg_id": 17,
        "id": 2686
      },
      // ...
    ]
  }
}

/auth-tokens/<id>/

Gives detail about an auth token.

  • Default Access: Protected

Response

Property Type Description
token dict A model-authtoken object corresponding to the user.

Example

// curl -F api_key=1000...aaa7 http://sfo.kegbot.net/api/auth-tokens/test.testval/
{
  "result": {
    "token": {
      "auth_device": "test",
      "created_time": "2010-10-13T00:41:01Z",
      "enabled": true,
      "id": "test|testval",
      "token_value": "testval"
    }
  }
}

/thermo-sensors/<id>/

Gives detail about a thermo sensor in the system.

  • Default Access: Public

POST Endpoints

Record a Drink

  • Endpoint: /tap/<id>/
  • Default Access: Protected

Posting to a Tap endpoint will record a new drink.

Publish Format

POST Argument Format Description
ticks integer The number of ticks recorded by the flow meter on this tap.
volume_ml float Optional. If specified, overrides the default volume calculation (based on the ticks field) with a specific volume in milliliters.
username string Optional. Gives the username of the user responsible for the pour. If auth_token was also given, the backend gives precendence to the username field.
pour_time integer Optional. Unix timestamp corresponding to the date the pour was completed. If this field is given, the field ‘now’ must also be given. If this field is not given, the backend will use the current time when the request is processed.
now integer Optional. Unix timestamp corresponding to the current time; the backend uses this to compensate for any skew in system clocks. Only meaningful when ‘pour_time’ is also given, dicarded otherwise.
duration integer Optional. Gives the time taken, in seconds, to complete the pour. This is used purely for trivia/statistical purposes.
auth_token string Optional. If known, gives the auth token ID used during the pour. If username is not specified, this value will be used by the backend to attempt to resolve to a user. Regardless, the value is stored with the drink record. (It can be useful for ‘claiming’ drinks poured with an unassigned auth token.)
spilled boolean Optional. If true, the pour is recorded as “spilled”: no drink record will be generated, and the username, pour_time, auth_token, now, and duration fields are all ignored. The volumed will be added to the spilled total for the tap’s current keg.

If the tap has an active keg assigned to it, the new drink will be recorded and accounted for against that keg. If not, the drink will not be associated with any keg.

Response

A new drink record is returned on success, in the same format as /drinks/<id>/.

Record a temperature

  • Endpoint: /thermo-sensor/<id>/
  • Default Access: Protected

Posting to a thermo sensor endpoint will record a new temperature sensor reading.

Publish Format

POST Argument Format Description
temp_c float Temperature, in degrees celcius.

Response

A new thermo sensor record is returned on success, in the same format as /thermo-sensors/<id>/.

Note that the Kegbot backend will record at most one reading, per sensor, per minute. If multiple readings are received within a minute, the most recent one received wins.

Error Codes

Error Code Meaning
Error A generic error.
NotFoundError The object being requested does not exist. This is served instead of an HTTP 404.
ServerError The server had a problem serving the request. This is served instead of an HTTP 500 error code, and probably indicates a bug or temporary server issue.
BadRequestError The request was incomplete or malformed. For example, when POSTing, this will be thrown when a required value is missing, or when a field’s format is incorrect.
NoAuthTokenError The resource/query is protected and requires an auth token to proceed. (See Security & Authentication).
BadAuthTokenError The provided auth token was invalid.
PermissionDeniedError The auth token provided does not have permission to perform this operation.

Next: API Object Reference
Previous: Overview and Basics

© Bevbot LLC 2014. All Rights Reserved. — Kegbot and Kegboard are trademarks of Bevbot LLC. — Terms of Service. Privacy Policy.