Modlist REST API

A REST API for the Modlist database, built on Cloudflare Workers and D1.

Authorization

All write requests require API key authorization. Keys are stored as SHA-256 hashes in the api_keys table. API keys use a 3-level permission system to control access.

Permission Levels

Level 1 - Admin

• Full access to all endpoints
• Can create, view, and revoke API keys

Level 2 - Moderator

• Can manage mods and versions
• Can verify new versions on existing mods

Level 3 - Modder

• Can add (but not verify) new versions on existing mods the user is an author of

Database Schema

The database is a SQLite database hosted on Cloudflare R1. See schema.sql for the complete schema.

Endpoints

Mods

GET /api/mods
Lists all mods. Public endpoint (no auth required).

Response fields:

• mod_id (text): Unique mod identifier
• url (text): Mod import URL
• name (text): Mod name
• authors (JSON array): List of mod authors
• game_versions (JSON array): Game versions the mod supports
• latest (object): Latest mod version for each game version (e.g., {"0.6.0": "1.3.2", "0.5.2": "1.1.0"})
• tags (JSON array, optional): Mod tags/categories
• description (text, optional): A short description of the mod
• icon_url (text, optional): Icon URL

GET /api/mods/:mod_id
Get a specific mod by ID. Public endpoint (no auth required).

POST /api/mods
Add a new mod. Requires Level 2+ authentication.

Request body:

• mod_id (text, required): Unique identifier
• url (text, required): Import URL
• name (text, required): Mod name
• authors (JSON array, required): List of author names
• game_versions (JSON array, required): Game versions supported
• latest (object, required): Latest version mapping ({"game_version": "mod_version", ...})
• tags (JSON array, optional): Mod tags
• description (text, optional): A short description of the mod
• icon_url (text, optional): Icon URL

All semver fields are validated. Returns 400 if validation fails.

PATCH /api/mods/:mod_id
Update a mod. Requires Level 2+ authentication.

You can update any fields from the POST request except mod_id. Semver validation applies to game_versions and latest fields.

DELETE /api/mods/:mod_id
Delete a mod. Requires Level 2+ authentication.

Versions

GET /api/versions
Lists all versions. Public endpoint (no auth required).

Response fields:

• id (integer): Version ID
• mod_id (text): ID of the mod this version belongs to
• version (text): Mod version number
• game_versions (JSON array): Game versions this mod version supports
• dependencies (object, optional): Dependencies ({"mod_id": "version_requirement", ...})
• changelog (text, optional): A changelog to show for this version
• verified (boolean): Verification status
• verified_by (text, optional): User who verified it
• verified_at (datetime, optional): ISO timestamp of when it was verified

GET /api/mods/:mod_id/versions Get all versions of a specific mod by mod ID. Public endpoint (no auth required).

GET /api/versions/:id
Get a specific version by ID. Public endpoint (no auth required).

POST /api/versions
Add a new version. Requires Level 2+ authentication for any mod, or Level 3 if you're an author.

Request body:

• mod_id (text, required): ID of the mod
• version (text, required): Version number (semver format)
• game_versions (JSON array, required): Supported game versions (semver format)
• dependencies (object, optional): Dependencies with version constraints (semver format)
• changelog (text, optional): A changelog to show for this version

All semver fields are validated. Returns 400 if validation fails.

DELETE /api/versions/:id
Delete a version. Requires Level 2+ authentication.

POST /api/versions/verify/:id
Verify a version. Requires Level 2+ authentication.

POST /api/versions/invalidate/:id
Invalidate a verified version. Requires Level 2+ authentication.

API Keys

GET /api/users Returns a list of users who have an API key. Public

GET /api/keys
List all API keys. Requires Level 1 (Admin) authentication.

Response fields:

• user (text): The user the key belongs to
• perm_level (integer): Permission level (1-3)
• created_at (datetime): Creation timestamp
• active (boolean): Whether the key is active

GET /api/keys/:user
Get a specific API key. Requires Level 1 (Admin) authentication.

Response fields:

• user (text): The user the key belongs to
• key_hash (text): The SHA256 hash of the API key
• perm_level (integer): Permission level (1-3)
• created_at (datetime): Creation timestamp
• active (boolean): Whether the key is active

GET /api/keys/self
Get details about the API key used in the request

Response fields:

• user (text): The user the key belongs to
• perm_level (integer): Permission level (1-3)
• active (boolean): Whether the key is active

POST /api/keys/generate
Generate a new random API key. Requires Level 1 (Admin) authentication.

Request body:

• user (text, required): The user the key belongs to
• perm_level (integer, required): Permission level (1-3)

Response:

• key (text): The generated API key (shown only once)
• user (text): The user the key belongs to

POST /api/keys
Manually add a pre-generated API key. Requires Level 1 (Admin) authentication.

Request body:

• user (text, required): The user the key belongs to
• key (text, required): The API key to add (minimum 32 characters)
• perm_level (integer, required): Permission level (1-3)

POST /api/keys/deactivate/:user
Deactivate an API key. Requires Level 1 (Admin) authentication.

POST /api/keys/activate/:user
Activate an API key. Requires Level 1 (Admin) authentication.

DELETE /api/keys/:user
Permanently delete an API key. Requires Level 1 (Admin) authentication.

Examples

Some example HTTP requests are included in the requests folder