v2 API Details

Rate Limits:
Not more than 20 requests in 10 seconds, else restricted for 1 minute

API Key:
xx

API Scopes:
locked_spoiler_access
locked_encrypt_spoiler_access
can_unlock_spoiler
can_unlock_encrypt_spoiler
can_create_encrypt

Generic error return codes:
503 (API not ready)
403 (invalid API key or insufficient API scope)
429 (rate limit exceeded)


Endpoints (https://ootrandomizer.com):

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

Response:
Possible error codes: 400 (invalid settings), 409 (version requested is ambiguous or not available), 423 (queue is currently full), 500 (internal database error)
Return data type if success (seed queried): application/json
Return 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)


*Get Seed Status*
Request:
URL: "/api/v2/seed/status"
Method: GET
Required query parameters: key (API key), id (seed ID)

Response:
Possible error codes: 404 (seed not found/expired)
Return data type if success: application/json
Return data fields:
-status (0 = still generating, 1 = generated success, 2 = generated with link (not possible from API), 3 = failed to generate)
-progress (generation progress, 100 if finished with success or error)
Optional return data fields:
-version (randomizer version in-use ; only present if status = 0)
-positionQueue (position in queue, 0 if currently processing ; only present if status = 0)
-maxWaitTime (ETA in seconds, 0 if currently processing ; only present if status = 0)
-isMultiWorld (only present if status = 0)


*Get Seed Details*
Request:
URL: "/api/v2/seed/details"
Method: GET
Required query parameters: key (API key), id (seed ID)
Optional API scope: locked_spoiler_access, locked_encrypt_spoiler_access

Response:
Possible error codes: 404 (seed not found/expired/errored), 204 (still generating)
Return data type if success: application/json
Return data fields:
-version (randomizer version used)
-seed (seed string)
-settingsString
-settingsLog (full JSON settings log, null if none was generated which is only possible on very old versions)
-spoilerLog (full JSON spoiler log, null if none was generated or when insufficient API privileges to read a hidden log ; with correct API scope this data is present even if the log was hidden from users)
-creationTimestamp (timestamp when the seed was created)


*Get Seed Patch File*
Request:
URL: "/api/v2/seed/patch"
Method: GET
Required query parameters: key (API key), id (seed ID)

Response:
Possible error codes: 404 (seed not found/expired/errored), 204 (still generating)
Return data type if success: application/octet-stream
Return data: raw patch file


*Unlock Seed Spoiler Log*
Request:
URL: "/api/v2/seed/unlock"
Method: POST
Required API scope: can_unlock_spoiler
Optional API scope: can_unlock_encrypt_spoiler
Required query parameters: key (API key), id (seed ID)
Body: N/A

Response:
Possible error codes: 403 (insufficient API scope), 404 (seed not found/expired/errored), 204 (still generating), 208 (no spoiler log available or it was already unlocked)
Return data type if success: text/plain
Return data: "Spoiler log unlocked"