Taplist.io API Docs Reference

Introduction

The Taplist.io is a REST-like API, available at https://taplist.io/api/v1 . The API is currently in beta. With the Taplist.io API, you can build integrations and mashups that use your Taplist.io data in new and fun ways.

API access is available to all paid subscribers. Thank you for supporting Taplist.io!

Note: The Taplist.io API is currently in beta, and some features may change or work unexpectedly. We would love you questions or feedback in the API forum.

Note: These docs are currently incomplete and will be updated. Last updated: December 6 2019.

Resource Scoping

Some resources, such as taps and kegs, are scoped to a venue. Other resources, such as beverages and beverage producers, are global to a Taplist.io organization. This distinction should be evident in the resource addresses (/venues/taplist-123/taps/3 versus /beverages/567).

Authentication

All requests require authentication using an API token. API examples below use HTTPie, a curl clone, but you can use any client you like.

To get an API token, visit https://taplist.io/account/developer . Create a new API key, copy the secret value, and save it somewhere safe.

You now have a ~long-lived access token to your account. Now you can explore the API.

export AUTH_TOKEN="secret-xxxxxx"
export VENUE_NAME="taplist-whatever"
# Get all taps
http get \
  https://taplist.io/api/v1/venues/$VENUE_NAME/taps \
  Authorization:"token $AUTH_TOKEN"

# Get a specific tap
http get \
  https://taplist.io/api/v1/venues/$VENUE_NAME/taps/1 \
  Authorization:"token $AUTH_TOKEN"

# Get all kegs
http get \
  https://taplist.io/api/v1/venues/$VENUE_NAME/kegs \
  Authorization:"token $AUTH_TOKEN"

# Get a specific keg
http get \
  https://taplist.io/api/v1/venues/$VENUE_NAME/kegs/1 \
  Authorization:"token $AUTH_TOKEN"

Quota and rate limiting

In order to prevent bugs and abuse, your use of the API is subject to certain rate limits. Authenticated requests will see the following headers in responses:

  • X-Ratelimit-Limit : Human-readable description of your quota (requests/period)
  • X-Ratelimit-Remaining : Credits remaining in the current period
  • X-Ratelimit-Reset : Number of seconds remaining in the current period (aka seconds until reset)

Example:

X-Ratelimit-Limit: 500/hour
X-Ratelimit-Remaining: 487
X-Ratelimit-Reset: 3440

Limits global to your account/organization. When quota is exhausted, an HTTP 429 will be returned. The default quota is 10k requests/hour. This limit is subject to change; please let us know if you encounter rate limits during ordinary use.

Endpoints reference

Work in progress.

Taps

GET /venues/:id/taps

List all taps.

POST /venues/:id/taps

Create a new tap.

PATCH /venues/:id/taps/:number

Modify a tap.

DELETE /venues/:id/taps/:number

Delete a tap.

Kegs

GET /venues/:id/kegs

List all kegs.

POST /venues/:id/kegs

Create a new keg.

PATCH /venues/:id/kegs/:kegId

Modify a keg.

DELETE /venues/:id/taps/:kegId

Delete a keg.

Beverages

GET /beverages

List all beverages.

POST /beverages

Create a new beverage.

PATCH /beverages/:id

Modify a beverage.

DELETE /beverages/:id

Delete a beverage.

Beverage Producers

GET /beverage-producers

List all beverage producers.

POST /beverage-producers

Create a new beverage producer.

PATCH /beverage-producers/:id

Modify a beverage producer.

DELETE /beverage-producers/:id

Delete a beverage producer.