Build or Bye for developers

Build or Bye has a free, read-only API and an MCP server. They expose the public board, the rules, the pricing and a search over what Build or Bye says about itself. There is no key, no sign-up and no cost.

Quickstart

Read the top five builders on the board:

curl "https://www.buildorbye.com/api/v1/board?limit=5"

Every list answers in the same shape: data, next_cursor and has_more. To read the next page, pass next_cursor back as cursor.

Endpoints

• GET /api/v1/board: builders ranked by money earned from strangers in the last 30 days. Takes limit (1 to 100, 20 by default) and cursor.
• GET /api/v1/rules: the 30-day clock, the floors at $100, $1,000 and $10,000, and what counts as money. Takes section (summary, money, floors, bye or tasks) to read one part.
• GET /api/v1/pricing: what each stage costs, and whether each price is live, planned or draft terms. Takes stage (1, 2 or 3) to read one stage.
• GET /api/v1/search?q=batch: short passages about the program, each with a link to the full page. Takes q (required, up to 200 characters) and limit (1 to 20, 5 by default).
• GET /api/v1: a list of everything above.

The full description is the OpenAPI 3.1 document at openapi.json. The API catalog is at /.well-known/api-catalog.

Authentication

None. Every endpoint is public and read-only, so there is nothing to sign in to and nothing an agent can break. See auth.md.

Rate limits

Each client may make 60 requests a minute. Every response carries RateLimit-Policy and RateLimit headers saying how many requests are left and when the window resets. Over the limit, the API answers 429 with a Retry-After header in seconds.

Errors

Errors are RFC 9457 problem details, served as application/problem+json:

{"type":"https://www.buildorbye.com/developers#error-invalid_limit","title":"Invalid limit","status":400,"detail":"limit must be a whole number from 1 to 100.","code":"invalid_limit"}

The code is stable; the wording of detail may change. The codes are:

• invalid_limit (400): limit is not a whole number in range.
• invalid_cursor (400): cursor is not a next_cursor this API returned.
• invalid_section (400): section is not one of the parts of the rules.
• invalid_stage (400): stage is not 1, 2 or 3.
• missing_query (400): search needs q.
• query_too_long (400): q is over 200 characters.
• rate_limited (429): too many requests; wait for Retry-After.
• not_found (404): there is no such endpoint.
• method_not_allowed (405): the API only takes GET.

Versioning

The major version is in the path, /api/v1, and in the API-Version response header. New fields can appear within v1, so ignore fields you do not know. Anything that would break a client ships as /api/v2, announced on this page.

Deprecation policy

When v2 is announced, every v1 response starts carrying a Deprecation header (RFC 9745), a Sunset header (RFC 8594) with the date v1 stops, and a Link with rel="deprecation" to the migration notes. The sunset date is at least 90 days after the announcement. Nothing is deprecated today.

Writes, retries and long jobs

There are none. Every operation is a fast, synchronous read with no side effects, so a retry is always safe. Every operation accepts an Idempotency-Key header for clients that always send one; it changes nothing. There are no long-running jobs to poll. Starting a clock or reporting a payment happens in Telegram, by the builder, at https://t.me/buildorbyebot.

Testing

The API is read-only, so production is safe to test against: no call changes anything. The board can be empty or short; your code should handle zero rows.

MCP server

Connect an MCP client to https://www.buildorbye.com/mcp (Streamable HTTP, no authentication). It offers four read-only tools, get_build_or_bye_board, get_build_or_bye_rules, get_build_or_bye_pricing and search_build_or_bye, plus the same data as resources. In hosts that support MCP Apps, the board tool renders as a table.

A second server at https://www.buildorbye.com/mcp/docs serves these docs: search_build_or_bye_docs and read_build_or_bye_doc.

Each server's card is at its address plus /server-card, for example /mcp/server-card, and both are listed in the resource catalog.

Terms

The API is free. Show where the data came from with a link to buildorbye.com. Board rows are what builders chose to make public; do not use them to contact builders in bulk. The limits and these terms may change; changes are announced on this page.

Help

Send a direct message to @buildorbye on X.