Ocarina of Time Randomizer Full Logo
Ocarina of Time Randomizer Full Logo
Ocarina of Time Randomizer Full Logo
  • ID: N/A
  • Most Recent Seed: N/A
  • Date: N/A

OoTR API Documentation

Certain features of OoTRandomizer.com are available through a private API. We want to work together with developers to allow them to find creative solutions and new additions to the OoTR eco system.

Note that most of the API is private and that most API endpoints are not available without a dedicated, heavily scoped API key. If you are interested in access, please contact TreZ on Discord .

All API endpoints are rate limited, not allowing for more than 20 requests over a span of 10 seconds. Hitting the rate limit will result in a 429 response.

Seed creation

Request

  • URL: /api/v2/seed/create
  • Method: POST
  • Required query parameters: key (your provided API key)
  • Optional query parameters:
    • - version (SemVer format, e.g. 5.2.0 for release or devXYZ_x.x.x-x for dev branches)
    • - locked (if present spoiler log will be hidden by default, otherwise shown)
    • - encrypt (creates an encrypted seed, requires "can_create_encrypt" scope)
  • Required API scope(s): -
  • Optional API scope(s): can_create_encrypt, can_create_mw
  • Body: JSON settings map (a "seed" key can be included to force a specific seed string, otherwise random)

Response

  • Possible Error Codes:
    • - 400 (invalid settings)
    • - 409 (version ambigious or not available)
    • - 423 (seed creation queue is full)
    • - 429 (flood protection)
    • - 500 (internal database error)
  • Response Data Type: application/json
  • Response Data Fields:
    • - id (unique seed ID, can be attached to "https://ootrandomizer.com/seed/get?id=" to direct users to the seed page)
    • - version (randomizer version selected, defaults to latest master version unless overridden with query parameter)
    • - spoilers (true if a spoiler log will be generated and shown to the user by default, false otherwise)

Seed status

Request

  • URL: /api/v2/seed/status
  • Method: GET
  • Required query parameters:
    • - key (your provided API key)
    • - id (seed ID)
  • Required API scope(s): -

Response

  • Possible Error Codes:
    • - 404 (seed not found / expired)
    • - 429 (flood protection)
  • Response Data Type: application/json
  • Response Data Fields:
    • - status (0 = generation in progress, 1 = success, 2 = generated with link (not possible via API), 3 = generation failed)
    • - progress (generation process, returns 100 if finished with success or error)
    • - (optional): version (used version of the randomizer; only present while status = 0)
    • - (optional): positionQueue (position in generation queue, returns 0 while in progress; only present while status = 0)
    • - (optional): maxWaitTime (ETA for start of generation in seconds, returns 0 while in progress; only present while status = 0)
    • - (optional): isMultiWorld (boolean; only present while status = 0)

Seed details

Request

  • URL: /api/v2/seed/details
  • Method: GET
  • Required query parameters:
    • - key (your provided API key)
    • - id (seed ID)
  • Required API scope(s) (at least one of the following):
    • - locked_spoiler_access
    • - locked_encrypt_spoiler_access

Response

  • Possible Error Codes:
    • - 204 (seed is still generating)
    • - 404 (seed not found / expired)
    • - 429 (flood protection)
  • Response Data Type: application/json
  • Response Data Fields:
    • - version (randomizer version selected)
    • - seed (seed string used for generation)
    • - settingsString (the settings string generated by the randomizer)
    • - settingsLog (full JSON settings log)
    • - spoilerLog (full JSON spoiler log, null if none generated or insufficient API privileges to access hidden logs)
    • - creationTimestamp (ISO timestamp of seed generation date)

Seed patch file

Request

  • URL: /api/v2/seed/patch
  • Method: GET
  • Required query parameters:
    • - key (your provided API key)
    • - id (seed ID)
  • Required API scope(s): -

Response

  • Possible Error Codes:
    • - 204 (seed is still generating)
    • - 404 (seed not found / expired)
    • - 429 (flood protection)
  • Response Data Type: application/octet-stream
  • Response Data: raw patch file

Unlock seed spoiler log

Request

  • URL: /api/v2/seed/create
  • Method: POST
  • Required query parameters:
    • - key (your provided API key)
    • - id (seed ID)
  • Required API scope(s): can_unlock_spoiler
  • Optional API scope(s): can_unlock_encrypt_spoiler
  • Body: N/A

Response

  • Possible Error Codes:
    • - 204 (seed is still generating)
    • - 208 (no spoiler log available or unlocked already)
    • - 403 (insufficient API scope)
    • - 404 (seed not found / expired / errored)
    • - 429 (flood protection)
  • Response Data Type: text/plain
  • Response Data: "Spoiler log unlocked"

Available Versions (public endpoint)

Request

  • URL: /api/version
  • Method: GET
  • Required query parameters: branch (name of the fork on ootr.com, master for release, else dev + Suffix, e.g. devrreal)
  • Required API scope(s): -

Response

  • Possible Error Codes:
    • - 403 (invalid branch)
    • - 429 (flood protection)
  • Response Data Type: application/json
  • Response Data Fields:
    • - branch (name of the branch as provided)
    • - currentlyActiveVersion (latest version currently served by the website, semVer format)
    • - availableVersions (array of supported versions available for this branch)