Skip to content
RaidKit
Sign up

For developers

The public API

Bearer keys with scopes, hashed at rest like passwords, revocable, and rate limited per key rather than per site. Everything on this page is generated from the same typed list the routes are checked against.

Getting a key

Sign in, open Settings, and make one under Developer. The key is shown once — it is stored as a hash, so nobody, including this site, can read it back. Up to 5 live keys per account.

Make a key

Using it

One header. No cookies, no session, no CSRF token — an API key IS the credential.

curl https://raidkit.app/api/v1/me \
  -H "Authorization: Bearer cs_your_key_here"

120 requests a minute per key. Past that, 429 with a Retry-After header saying how long to wait.

Scopes

A key carries the scopes chosen when it was made, and every endpoint names the one it needs. A key for reading cannot write, whatever the client asks for.

  • read:profileWho the key belongs to: id, name, email.
  • read:gameList the owner's save slots and their state.
  • write:gameStart games and play moves in the owner's slots.

Endpoints

Three routes. Small on purpose: this is a demonstration of the seam, not a product surface.

  • GET/api/v1/meread:profile

    Who this key belongs to. The endpoint a client calls first to check a key works.

    Response

    {
  "ok": true,
  "user": { "id": "clx…", "name": "Ada", "email": "ada@example.com" },
  "key": { "name": "My laptop", "scopes": ["read:profile", "read:game"] }
}

    Failures worth handling

    • 401The Authorization header is missing, malformed, revoked, or expired.
    • 403The key is valid but does not carry the scope this endpoint needs.
    • 429More than 120 requests in a minute from this key.
  • GET/api/v1/game/savesread:game

    Every save slot this account owns, with its current state and version.

    Response

    {
  "ok": true,
  "slots": [
    { "slot": 1, "version": 7, "state": { "room": "hall", "carrying": ["lamp"] } }
  ]
}

    Failures worth handling

    • 401The Authorization header is missing, malformed, revoked, or expired.
    • 403The key is valid but does not carry the scope this endpoint needs.
    • 429More than 120 requests in a minute from this key.
  • GET/api/v1/game/saves/{slot}read:game

    One slot, with the version a later move must send back.

    Parameters

    • slotinteger · pathWhich save slot.

    Response

    {
  "ok": true,
  "save": { "slot": 1, "version": 7, "state": { "room": "hall" } }
}

    Failures worth handling

    • 401The Authorization header is missing, malformed, revoked, or expired.
    • 403The key is valid but does not carry the scope this endpoint needs.
    • 429More than 120 requests in a minute from this key.
    • 404No save in that slot, or the slot number is not one this game has.
  • PUT/api/v1/game/saves/{slot}write:game

    Start a new game in this slot, replacing whatever was there.

    Parameters

    • slotinteger · pathWhich save slot.

    Response

    {
  "ok": true,
  "save": { "slot": 1, "version": 1, "state": { "room": "start" } },
  "output": "You are standing at the edge of a wood."
}

    Failures worth handling

    • 401The Authorization header is missing, malformed, revoked, or expired.
    • 403The key is valid but does not carry the scope this endpoint needs.
    • 429More than 120 requests in a minute from this key.
    • 404That slot number is not one this game has.
  • POST/api/v1/game/saves/{slot}write:game

    Play one move. The version is a lock, not a suggestion: send the one you read, and a mismatch is refused rather than silently overwriting what another client did.

    Parameters

    • slotinteger · pathWhich save slot.
    • inputstring · bodyThe move, as typed — "go north", "take lamp".
    • versioninteger · bodyThe version you last read. A mismatch is a 409.

    Response

    {
  "ok": true,
  "save": { "slot": 1, "version": 8, "state": { "room": "hall" } },
  "output": "You are in the hall. A lamp rests on the table."
}

    Failures worth handling

    • 401The Authorization header is missing, malformed, revoked, or expired.
    • 403The key is valid but does not carry the scope this endpoint needs.
    • 429More than 120 requests in a minute from this key.
    • 409The version you sent is not the current one. Read the slot again and replay the move.
    • 404That slot number is not one this game has.
  • DELETE/api/v1/game/saves/{slot}write:game

    Clear the slot. The save is gone; the slot itself stays and can be started again.

    Parameters

    • slotinteger · pathWhich save slot.

    Response

    { "ok": true }

    Failures worth handling

    • 401The Authorization header is missing, malformed, revoked, or expired.
    • 403The key is valid but does not carry the scope this endpoint needs.
    • 429More than 120 requests in a minute from this key.
    • 404That slot number is not one this game has.

No OpenAPI document. Three endpoints do not need a specification format, and generating one from the same typed list is a small change the day a client needs it. Writing it first would be ceremony.

The inventory