Beta Bud Gym API | Getting started

🚦

Before you start

Beta Bud turns the API on for one gym at a time. This step is the gate.

⚠️

The API must be on for your gym. Open Gym Settings. If API Access is absent, the API is off for that gym. Ask Beta Bud to turn it on.

Only a gym admin can create a key. A setter cannot.
The API is read-only. Every endpoint uses GET.
Keep the key secret. Do not share the key with a person who must not read the data.
Call the API from a server or a script. Do not call the API from a web page, because every visitor can then read the key.

🔒

Admin only. A setter does not see the API Access card and cannot create a key.

🔑

Step 1: Create your key

Gym Settings › API Access

1

Open Gym Settings Use the menu in Beta Bud.

2

Go to API Access If the card is absent, ask Beta Bud to turn the API on.

3

Type a name for the key Use a name that tells you where the key is used.

4

For a chain, select each location that the key must cover A single-gym key needs no selection.

5

Select Create token Beta Bud makes the key.

6

Copy the key and keep it in a safe place The key starts with bbk_. You can get it again later with Show and Copy.

Rules for a key

You must be an admin of every location that you select.
Beta Bud must turn the API on for every location that you select.
A key does not get a new location automatically. To add a location, create a new key.
A gym can have 20 active keys at most.
A key starts with bbk_ and does not expire.
Show and Copy recover the key at any time. You do not have to replace a key because you lost the copy.
Revoke is permanent. The next request with that key gets a 401 answer. You cannot undo this action.

💡

Give each script or each person its own key. To stop one script, revoke only its key. The other keys continue to work.

🤖

Step 2: Choose how to read your numbers

You have two routes. Use the skill with an AI assistant, or call the REST API yourself.

Option A

Ask an AI assistant (the skill)

The Beta Bud skill teaches an AI assistant to read your gym data. Install the skill once, then ask a question in plain words.

Claude Code

In a Claude Code session, run these two commands:

/plugin marketplace add Beta-Bud-Apps/betabud-gym-api-skill
/plugin install betabud-gym-api@betabud

From a terminal, use the long form:

claude plugin marketplace add Beta-Bud-Apps/betabud-gym-api-skill
claude plugin install betabud-gym-api@betabud

The session restarts after the install.

Claude desktop

Download betabud-gym-api.mcpb from the releases page. Open the file, choose Install, then paste your key.

Other routes

You can also use the ZIP file, or clone the repository and copy the skill:

git clone https://github.com/Beta-Bud-Apps/betabud-gym-api-skill.git
cp -r betabud-gym-api-skill/skills/betabud-gym-api ~/.claude/skills/

Other MCP agents

The package ships a standard MCP stdio server at mcpb/server/index.js. Run it with node. Supply the key in the environment variable BETA_BUD_API_TOKEN. The skill repository README gives the setup for each client, such as Codex or Cursor.

💡

Where does the key go? Supply the key as the environment variable BETA_BUD_API_TOKEN, or paste the key into the extension.

Get the download and the full instructions from the skill releases page.

Option B

Call the REST API directly

The API is read-only. Send every request with GET. The base URL is https://betabud.app. Send the key in the Authorization header.

curl -H "Authorization: Bearer $BETA_BUD_API_TOKEN" \
  "https://betabud.app/api/v1/gyms"

Endpoints

Endpoint	Data
`GET /api/v1/gyms`	The gyms that the key covers
`GET /api/v1/gyms/{gymId}`	One gym, with its modes and its timezone
`GET /api/v1/gyms/{gymId}/zones`	The walls and areas of the gym
`GET /api/v1/gyms/{gymId}/grades`	The grade systems of the gym
`GET /api/v1/gyms/{gymId}/climbs`	All climbs: live, archived and not live
`GET /api/v1/gyms/{gymId}/climbs/{climbId}`	One climb
`GET /api/v1/gyms/{gymId}/activity-summary`	Daily activity in a date window
`GET /api/v1/gyms/{gymId}/climb-stats`	Opinions and activity for each climb
`GET /api/v1/gyms/{gymId}/climbs/{climbId}/stats`	Opinions and activity for one climb
`GET /api/v1/gyms/{gymId}/setter-feedback`	Feedback for setters, with replies

Pages

A list endpoint gives one page for each request. limit sets the page size: the default is 50 and the maximum is 100. Send cursor set to nextCursor to get the next page. When nextCursor is null, there are no more pages.

The contract

The machine-readable contract is the OpenAPI file. It gives each field and each query parameter.

🔐

Keep your key safe

Keep the key in an environment variable or in a secret store. Do not put the key in source code.
Do not put the key in a web page. Every visitor can then read the key.
Send the key only in the Authorization header. Do not put the key in a URL.
Give a key only to a person who is permitted to read the data.
If a person without permission possibly knows a key, replace the key at once.

Replace a key

1

Create a new key

2

Change your script so that it uses the new key

3

Make sure that the script works

4

Revoke the old key Revoke is permanent. The next request with the old key gets a 401 answer.

🚫

What the API does not give

The API gives counts and opinions. It does not give the identity of a person. The API does not give any of these:

names, email addresses, user ids, photos or profile links of climbers
the name of a setter
the sends, attempts or repeats of one person
personal notes on attempts and repeats
competition entrants
public comments that are not for setters

⚠️

A count or a text is not guaranteed anonymous. A count for a small group, or a text, can point to one person. Handle a comment as personal data.

📊

Limits at a glance

Requests	Limit	Shared by
`GET /api/v1/gyms`	60 each minute	One key
Gym data (gym, zones, grades, climbs, setter feedback)	60 each minute	All keys of one gym
Statistics (activity summary, climb stats)	10 each minute	All keys of one gym
Page size	50 default, 100 maximum	Each list request

The counter starts again at the start of each minute. A 429 answer has a Retry-After header. Wait for that number of seconds, then try again.

💬

Need help

Ask Beta Bud to turn the API on for your gym. Ask Beta Bud also for help with a key, a limit or a wrong number.