API Reference
Authentication
Every request to the Realms of Shod API must carry a Bearer token. This page covers how to mint tokens, authenticate calls, understand rate limits, and revoke access.
API tokens are created from the H.U.B.. Open the Configure API panel from the drawer rail on the bottom right of the screen.
When creating a token you choose a name and an optional expiry (1, 7, 30, or 120 days, or unlimited). The raw token value is shown once immediately after creation. Copy it before closing the panel. Only the first eight characters are stored and displayed afterward.
Tokens begin with the prefix ros_ and are 68 characters long in total.
Pass your token in the Authorization header using the Bearer scheme. The scheme name is case-insensitive.
curl https://realmsofshod.com/api/v1/realms \
-H "Authorization: Bearer ros_your_token_here"Requests missing the header, or carrying an expired or revoked token, receive a 401 Unauthorized response with a plain-text body.
Each token is limited to approximately 100 requests per 60 seconds. The limit is enforced with a fixed window counter, so it may overshoot slightly under heavy concurrency.
When the limit is exceeded the API responds with 429 Too Many Requests and a Retry-After header indicating how many seconds to wait before retrying. The response body is the plain text Too Many Requests.
HTTP/1.1 429 Too Many Requests
Retry-After: 37
Too Many RequestsAuth and rate-limit errors (401, 403, 429, 500) return plain-text bodies. Validation errors from individual endpoints (400, 404, 409) return a JSON envelope:
{
"error": "Human-readable message",
"code": "MACHINE_READABLE_CODE"
}Status codes
| Parameter | Type | Description |
|---|---|---|
| 200 | Success | The request succeeded. Response body is JSON. |
| 400 | Bad Request | Invalid query parameters or request body. Body: { "error": "...", "code": "..." } — the code is endpoint-specific (e.g. BAD_REQUEST, INVALID_CURSOR, INVALID_ENTITY). |
| 401 | Unauthorized | Missing or invalid token. Body: plain text "Unauthorized". |
| 403 | Access Denied | Token is valid but API access has not been enabled for your account. Body: plain text "Access Denied". |
| 404 | Not Found | The requested resource does not exist or you lack access. Body: { "error": "Not Found", "code": "NOT_FOUND" }. |
| 409 | Conflict | The resource already exists. Body: { "error": "...", "code": "..." }. |
| 429 | Too Many Requests | Rate limit exceeded. Body: plain text "Too Many Requests". Check the Retry-After header (in seconds) before retrying. |
| 500 | Internal Server Error | Unexpected server error. Body: plain text "Internal Server Error". |
Tokens with an expiry stop authenticating once the expiry time passes. They return 401 Unauthorized just like an invalid token.
From the H.U.B. API Tokens panel you can also disable a token without deleting it (useful for temporarily pausing access) or revoke it permanently. Revocation is immediate and irreversible. The token stops working the moment it is deleted.