Making requests

Every public endpoint is a plain HTTPS GET request that returns JSON (or, for pictures, the file itself). No headers are required.

The base URL

https://bazoodle.com/api/v1

Add the endpoint path to it. For example, the list of categories is https://bazoodle.com/api/v1/catalog/categories.

The same API is also served from https://api.bazoodle.com/v1, without the /api part. Use https://bazoodle.com/api/v1, the one these docs show. The /v1 is the API version: see Fair use and changes. Paths without it (https://bazoodle.com/api/catalog/categories) still answer, but they are the unversioned form the website uses, they keep the old error format, and they can change without notice. New tools should use /v1.

curl -s "https://bazoodle.com/api/v1/catalog/categories"

• Use GET. Other methods are not part of the public API.
• Put options in the query string (?sort=new&limit=10). Values are case-sensitive and lower case.
• Send a User-Agent that says what your tool is, for example MyGameList/1.0 (contact: you@example.com). It helps if we ever need to reach you about heavy use. curl and fetch work without one, but Python’s built-in urllib sends a default agent that Bazoodle’s bot protection blocks with 403 Forbidden, so always set your own.
• You do not need cookies. Signed-out calls only ever see kid-friendly games: see Kid safety.
• Always call the https:// address.

Responses

All catalogue and status endpoints return one JSON object, never a bare array. Lists are in a field such as games.

Rule	Detail
Field names	Lower case with underscores (players_online, next_offset).
Missing values	Sent as null (for example like_pct when a game has too few votes). Empty lists are []. A field is not left out because it is empty.
Times	Whole seconds since 1 January 1970 UTC (a Unix timestamp), for example "updated_at": 1792290579.
Text	UTF-8. Titles and descriptions are written by creators and checked by moderation, but treat them as untrusted text: escape them before putting them in a web page.
New fields	Can appear at any time. Ignore fields you do not know.

Errors

When something is wrong, the status code is 4xx or 5xx and the body has one error object with a code and a message:

{"error": {"code": "bad_request", "message": "sort must be popular, new or top"}}

code is a short lower-case word that does not change: test it in your program. message is a sentence for people and can be reworded. Some errors add fields beside error (for example how many minutes are missing).

Status	code	When	Example message
400	bad_request	A query value is not allowed	sort must be popular, new or top, unknown filter, unknown tag
404	not_found	There is no such game or file, or it is not public	not found
429	rate_limited	You are calling too often	too many requests; slow down
5xx	server_error, unavailable	Our side; try again later
416		A Range request for a file is outside the file	(empty body)

Note

Match on the status code or the code, not the message text. A game that is hidden, taken down or above the kid-friendly level answers 404, exactly like a game that never existed.

A search with no matches, a category with no games or a page past the end of a list is not an error: it answers 200 with an empty games list. Treat any 5xx as “try again later”; see Be resilient.

Paging through lists

Lists of games (browse and search) come in pages.

Parameter	Meaning	Default	Allowed
limit	How many games to return	24	1 to 50 (larger numbers are lowered to 50)
offset	How many games to skip	0	0 to 500

A value that is not a number is ignored and the default is used. Values outside the allowed range are moved to the nearest allowed value; they do not cause an error.

Every list response has a next_offset: a number (ask again with offset set to it to get the next page) or null (that was the last page). Follow it instead of working out offsets yourself.

curl -s "https://bazoodle.com/api/v1/catalog/browse?limit=1&offset=1"

{"games":[{"id":"net2d","title":"Net 2D","tags":["party"],"tier":"kid","players":{"min":1,"max":8},"like_pct":null,"players_online":0,"thumbnail":null,"thumbnail_url":null,"creator":{"id":"BZSAMPLES00001","name":"Bazoodle Samples"}}],"next_offset":2}

Caution

You can reach at most the first 500 games of any list. To find games further down, narrow the list with a tag or filter (Browse) or use Search. Lists also change between requests, so a game can show up twice or be missed while you page: de-duplicate by id if it matters. List all games shows a loop.

Calling the API from a browser

The public API is meant for programs that run on a server, in a script or in a desktop or mobile app. Browsers only let a page read a response from another website if that website sends CORS headers such as Access-Control-Allow-Origin. The Bazoodle API does not send them:

curl -s -D - -o /dev/null -H "Origin: https://example.org" "https://bazoodle.com/api/v1/catalog/categories"

The response headers contain no Access-Control-Allow-Origin, so JavaScript on https://example.org that calls fetch("https://bazoodle.com/api/...") is blocked by the browser. The same call from curl, Node.js, Python or any server works normally.

What to do instead:

• Call the API from your own server and send the result to your page. This also keeps you within the rate limits, because a server shares one cache between all visitors.
• For a static site, fetch the data when you build the site and publish it as part of your pages.
• Pictures are different. Files from the media endpoint are sent with Cross-Origin-Resource-Policy: cross-origin, so you can show a game’s thumbnail in an <img> on any website. Use the exact thumbnail_url from the response (Media files).

Do not use a third-party “CORS proxy”: it would send your visitors’ addresses to a stranger and can break the rate limits for everyone behind it.