API and development

Reforger Mods API Integration Guide

Build an integration that behaves well in production: choose the right endpoints, follow pagination links, cache responses, identify your client, and handle every response state cleanly.

API v1 Cache aware Retry ready

Need endpoint details?The full reference documents every route, parameter, cache header, and error code.

Open API Reference

Endpoints in one look

GET /v1/health                      process health, no Workshop data
GET /v1/mods                        first page of mod previews
GET /v1/mods/{page}                 specific page (positive integer)
GET /v1/search?query={query}        convenience alias for first-page search
GET /v1/mod/{mod_id}                full detail for one mod
GET /v1/rate-limits                 current public or API-key rate limit
GET /v1/refresh/jobs/{id}           status of a background refresh job
GET /v2/mods                        typed mod previews
GET /v2/mods?page={page}            typed page of mod previews
GET /v2/mods?search={query}         typed search
GET /v2/mods/{mod_id}               typed full detail for one mod
GET /v2/mods/{mod_id}/versions      version history under V2
GET /v2/mods/{mod_id}/versions/{v}  changelog and metadata for one version
GET /v2/mods/{mod_id}/dependencies  direct dependency metadata under V2
GET /v2/mods/{mod_id}/scenarios     scenario metadata under V2
GET /v2/mods/{mod_id}/license       license text under V2

V1 remains supported. Use V2 mod routes when you want raw byte sizes, IEC sizeFormatted, numeric ratings, RFC3339 timestamps, flattened tags, and plural /mods resources.

List endpoints accept search, sort, and Workshop tag filters through tags or the single-value category alias.

Pagination

List responses include meta and ready-built links.next / links.prev URLs. Follow the links instead of reconstructing URLs yourself.

Identify your client

Send a User-Agent or X-API-Client header that names your project and gives a way to reach you.

For paid access, send your API key with X-API-Key or Authorization: Bearer. Paid limits are shared across the account, and /v1/rate-limits reports the active plan for the key.

User-Agent: my-server-panel/2.1 (+https://example.com; [email protected])

Cache like you mean it

Honor Cache-Control, Age, and ETag.
Send If-None-Match with the last ETag to get cheap 304 Not Modified responses.
Use X-Cache to understand whether you received a HIT, STALE, or fresh response.
Do not vary query strings just to bust caches; it wastes your rate budget and refresh capacity.

Handle every status

200: Use the data.
202: Background refresh job accepted. Ordinary mod list, search, and detail reads should normally complete synchronously.
304: Your cached copy is still valid.
404: The mod or page does not exist. Cache the negative result briefly.
429: You exceeded the rate limit. Back off for Retry-After.
5xx: Treat as temporary; retry with backoff and surface a friendly error.

All errors include a requestId. Log it and include it when reporting support issues.

Worked retry exampleThe quickstart includes copy-paste code for bounded retries.

API Quickstart