Getting started

The Musecat bot API automates arcade creation and information edits with your account's permissions. Open Manage keys on your Bots page, enter a name and create a key. The secret is shown only once.

Founding supporters, supporters, designers, moderators and developers can issue keys. The official arcade account role alone is insufficient. Your account must be active and fully registered; eligibility is checked on every request.

Connection and authentication

Append /bot/v1 to your backend origin and send Authorization: Bearer <bot-key>. These examples use a local backend. For a deployed environment, substitute its HTTPS backend origin, not the website origin or a web /api proxy.

export MUSECAT_API_URL="http://localhost:8090"
export MUSECAT_BOT_KEY="YOUR_BOT_KEY"

curl --fail-with-body \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  "$MUSECAT_API_URL/bot/v1/arcade/drafts"

Store the key in an environment variable or secret store. Never put it in URLs, query strings, public code or logs. It cannot be exchanged for a web session or used on normal account or PocketBase collection APIs.

Supported API routes

Every path below requires the /bot/v1 prefix. Unlisted routes are unavailable.

Use URL query parameters for reads and JSON with Content-Type: application/json for ordinary edits. Photo uploads use multipart form data. Existing arcade visibility and creator permissions still apply.

Create and read an arcade

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Example Arcade","address":"Tokyo","location":{"lat":35.6895,"lon":139.6917}}' \
  "$MUSECAT_API_URL/bot/v1/arcade/new"

The response's id identifies the arcade. Creation produces a private draft, not a published arcade. List your drafts with GET /arcade/drafts; read a draft with GET /arcade/draft?id=ARCADE_ID&expand=all. Read a public arcade with GET /arcade?id=ARCADE_ID&expand=all.

If a creation response is lost, check your drafts first. Blindly retrying may create a duplicate arcade.

Edit basic information and opening hours

Read basic.id from the detail response and send it as base_basic_id to edit the revision you inspected. Send only the fields you intend to change. Replace placeholder IDs with actual values.

curl --fail-with-body -X PUT \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  -H "Content-Type: application/json" \
  --data '{"arcade":"ARCADE_ID","base_basic_id":"CURRENT_BASIC_ID","direction":"Basement entrance"}' \
  "$MUSECAT_API_URL/bot/v1/arcade/basic"

PUT /arcade/hour accepts weekdays as shown below. Times are integers in 24-hour HHMM format. Omitted weekdays remain unchanged.

{"arcade":"ARCADE_ID","Monday":{"start":1000,"end":2300}}

Edit game information

Read version IDs from GET /game/catalog?locale=en-US, then fetch arcade details with expand=game. The current state ID is game.state_id; use an empty base_state_id when no game state exists.

Send changes to PUT /arcade/game as add, modify and remove, not a full replacement games list. Each modify entry needs its existing item id; remove contains item IDs. The game field uses a catalog version ID, not a series ID.

{
  "arcade": "ARCADE_ID",
  "base_state_id": "CURRENT_GAME_STATE_ID",
  "add": [{
    "game": "VERSION_ID_FROM_CATALOG",
    "quantity": 1,
    "location": "1F",
    "price": {"currency": "JPY", "type": "free", "list": [], "accept": []},
    "tag": []
  }],
  "modify": [],
  "remove": []
}

On 409, fetch the latest state and recompute the changes. Do not attach a new state ID to an unchanged stale delta.

Upload and apply photos

Upload up to 10 PNG, APNG or JPEG files per request using photos. Uploading alone does not change the arcade's photo list. Collect uploaded[].atomId and submit the final photo list to PUT /arcade/photo. Include existing atom IDs to retain existing photos. Retry only failed uploads when a batch partly succeeds.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  -F "arcade=ARCADE_ID" -F "photos=@photo.jpg" \
  "$MUSECAT_API_URL/bot/v1/arcade/photo/upload"

{"arcade":"ARCADE_ID","photos":["ATOM_ID_FROM_UPLOAD"]}

Publish a draft

Check requirements with GET /arcade/public?arcade=ARCADE_ID, then send {"arcade":"ARCADE_ID"} to PUT /arcade/public. Only the creator may publish. Registered games and the photo, contact or opening-hour requirements for the account's level must be satisfied.

The bot API does not provide GPS verification. Map coordinates are not proof of a visit. Keep the draft private if requirements remain unmet.

Limits and error handling

• Keys have no automatic expiry, including previously issued keys. Each account may have up to five unrevoked keys.
• Each key permits 60 accepted requests per minute. Separate IP limits also apply.
• 400: check required fields, IDs and JSON formatting.
• 401: check revocation and the issuing account's eligibility and status. Do not automatically fall back to password login.
• 403: check permission to edit or publish the arcade.
• 404: check the route, resource ID and visibility.
• 409: reload current state and recompute the delta.
• 429: honor Retry-After; key-rate-limit responses specify 60 seconds.
• After network or server errors during writes, check whether the edit was applied before retrying.

Account management, messaging, attendance, visit verification, memo editing and moderation are excluded.

History and privacy

The issuing account remains the editor. Arcade history displays a BOT badge beside its nickname. Bot names are visible only to their owner and are omitted from other viewers' API responses. Your Bots page filters history by bot. Bot work earns no XP.

Rotate and revoke keys

Issue a replacement, update your bot's configuration, then revoke the old key in Manage keys. Revocation blocks later requests; already accepted requests may finish. Past edit history remains intact.

Key management requires a signed-in web session. A bot key cannot list, issue or revoke keys.