Mod managers and other tools can read the catalog as JSON from https://lucidpedia.site. The JSON endpoints need no sign-in or key, and a browser may call them from any site. Their answers carry a 30-second cache lifetime; keep them at least that long instead of asking again.
| Endpoint | Returns |
|---|---|
GET /api/mods | One page of the catalog |
GET /api/mods/<slug> | One mod with its description, images, versions and dependencies |
GET /api/mods/<slug>/versions | The mod's published versions with their files and checks |
GET /api/mods/<slug>/versions/<id>/download | A redirect to the version's main file, or to one file with ?file=pack or ?file=native, counted as a download |
List mods
GET /api/mods lists published mods that have a file to download. Every parameter is optional, and a value the API doesn't recognise falls back to the default.
| Parameter | Values | Default |
|---|---|---|
q | Search words, up to 100 characters. Each word has to appear in the name, the summary or a tag name. | none |
kind | code or assets | both |
native | only for mods whose current version replaces the game's native library, hide for the rest | both |
gv | A game version: 5.1.0, 4.0.1, 3.0.4, 2.9.3, 2.8.7 or 2.8.0. Repeat it to match any of several. | any |
tag | A tag slug. Repeat it or separate tags with commas; a mod has to carry every tag given. | any |
clean | 1 for mods whose current file scanned clean | off |
author | A userId from an author entry | anyone |
sort | trending, downloads, likes, newest, updated or name | trending |
period | week, month or all, the window for trending, downloads and likes | month |
offset | 0 to 100000 | 0 |
limit | 1 to 60 | 24 |
trending ranks by downloads plus five times the likes within the period. The tag slugs are gameplay, quality-of-life, visuals, audio, interface, items, vermin, world-gen, fusion, tools, framework, library, cheats and translation.
The answer is { mods, total, offset, limit, filters, facets }. filters echoes the filters as the API applied them, and facets counts mods per kind, game version, tag and clean scan, for a filter panel. Page through with offset until it reaches total. Each entry in mods has these fields:
| Field | Meaning |
|---|---|
slug | The mod's address. Its page is /mods/<slug>. |
name, summary | The name and the one-sentence summary |
cover | The first image (kind image with src, width, height and caption), else the first video (kind video with youtubeId), else null |
kind | code when the current file has scripts, assets when it has none |
native | true when the current version replaces the game's native library |
tags | Tag slugs, primary tag first |
gameVersions | The game versions the current file declares |
worksOnCurrent | true when those include 5.1.0, the game's current version on Steam |
latestVersion, sizeBytes | The current version's label and the size of all its files in bytes |
likes, downloads | Totals |
safety | clean, flagged or pending, from the current file's virus scan |
authors | userId, name, avatar and role (owner or coauthor) for each credited person |
publishedAt, updatedAt | Milliseconds since 1970, UTC |
One mod
GET /api/mods/<slug> returns the same fields plus the rest of the mod page:
| Field | Meaning |
|---|---|
description | Markdown |
media | Images and videos in gallery order |
versions | Published versions, newest first, in the shape below |
currentVersionId | The version the download button serves, which is not always the newest |
dependencies | { mod, kind } entries, with kind one of requires, optional or incompatible |
dependents | Published mods that require this one |
license, sourceUrl | The license value and the source link, or null |
stats | downloads, downloadsToday, likes, followers and views |
commentCount, collectionCount | Comments on the mod, and collections that include it |
Versions
GET /api/mods/<slug>/versions returns { slug, name, currentVersionId, versions } with only the published versions, newest first. Each version has these fields:
| Field | Meaning |
|---|---|
id | The version id, used in the download URL |
version, changelog | The label and its changelog in markdown |
gameVersions | Game versions this version declares |
createdAt, publishedAt | Milliseconds since 1970, UTC |
downloads | Downloads of this version |
file | The main file: the pack, or the native library of a version without a pack. fileName, sizeBytes, sha256 and downloadUrl |
files | Every file, pack first: the file fields plus role (pack or native), slot, installPath (relative to the game folder), scan, and native, a library's header report (linkName, linkerVersion, timestamp, imageSize, exports, imports, capabilities, sections, signed, hasDebugPath, baseline, warnings) |
pack | What the upload check found: engine, modFolder (the mod's own folder), modInitId (its mod_init.gd folder, if it has one), qualia (QualiaMods mod.cfg data and role, for a QualiaMods mod or the framework), kind, replacedFiles, scripts with their risky calls, conflicts and warnings, or null when the version ships no pack |
native | true when a file replaces the game's native library |
conflicts | Listed mods this version can't sit beside cleanly; native: true on mods that replace the same library |
scan | The virus scan: state, malicious, suspicious, engines, reportUrl and scannedAt. Over every file: done when all are, failed when any is |
Download a file
file.downloadUrl is a full address, such as https://lucidpedia.site/api/mods/better-hotbar/versions/<id>/download. Request it with GET and follow the redirect:
- It answers
302with the file's address under/mod-files/. That address never changes, so the file can be cached for good. - The file supports
Rangerequests for resuming, and itsETagis its SHA-256. Check what you downloaded againstfile.sha256. - A GET counts one download per visitor, per version, per UTC day.
HEADanswers the same way without counting. - Prefetches don't count, and neither do requests whose User-Agent looks like a crawler, with words such as
bot,crawl,spiderorpreviewin it. Request the URL when a player asks for the file, not ahead of time. - A version with a native library has two files. Install
role: "pack"files intomodsand arole: "native"file at itsinstallPath, keeping its name; the library replaceslibgdblocks.windows.template_release.double.x86_64.dllnext tolucid-blocks.exe, one mod at a time.?file=packor?file=nativedownloads one of them; both count as one download of the version. A mod manager that can't install a library should leave out versions whosenativeistrue.
Errors
The mod endpoints answer errors as JSON with a stable code and a sentence you can show as it is:
{ "error": "not_found", "message": "Mod not found." }A mod that isn't public answers 404 with not_found, the same as one that never existed. The download URL answers 404 for a version that isn't public.