Manager API contract

Surfaces

The current prototype is static JSON under /api/v1.

GET /api/v1/catalog.json
GET /api/v1/readiness.json
GET /api/v1/runtime/latest.json
GET /api/v1/framework/latest.json
GET /api/v1/manager/latest.json
GET /api/v1/mods/index.json
GET /api/v1/mods/{modId}/index.json
GET /api/v1/mods/{modId}/versions.json
GET /api/v1/publishing/workflow.json
GET /api/v1/publishing/backend-contract.json
GET /api/v1/publishing/backend-contract.schema.json
GET /api/v1/publishing/starminer-publishing-validation.v1.json
GET /api/v1/publishing/starminer-publishing-validation.schema.json
GET /api/v1/publishing/upload-submission.schema.json
GET /api/v1/publishing/mod-release-submission.schema.json

Future authenticated routes, including POST /api/v1/uploads, stay disabled until the backend stack is deployed and SMMODS_LIVE_UPLOADS=1. Until then, upload attempts return uploads_disabled before package bytes are accepted. Account creation also requires verification email delivery and returns email_delivery_unavailable when that provider is missing.

The workflow also publishes backendRequirements for auth, upload storage, validation workers, moderation, catalog publishing, audit logs, and post-publish smoke.

readiness.json publishes the production gate status so tooling can tell the difference between ready static surfaces and backend-blocked account/upload features.

backend-contract.json defines the account/session, upload, moderation, catalog publishing, validation worker, and audit API surface that must be implemented before uploads become live. Its schema is published beside it for backend implementers and CI validation.

upload-submission.schema.json defines the status response for a submitted ZIP, including validation checks, review state, hashes, and publication links.

starminer-publishing-validation.v1.json mirrors the framework validation contract used by staged upload checks, with a public schema beside it.

Approved manual releases use the published sidecar schema so uploader validation, moderation review, and the static importer all agree on the same required metadata.

Catalog rules

catalog.json is the manager's canonical startup document. It embeds the pinned runtime profile, latest framework release, latest manager release, and the installable mod list.

• Planned or prototype-only mods are not listed in manager-facing JSON.
• Every catalog mod must have a web detail URL, an API detail URL, latest version metadata, and version history.
• Catalog mod ids must match the manifest id pattern from the framework schema.
• Mod-to-mod dependencies must reference another published catalog mod, not a missing package.
• The manager release object includes target game build, runtime dependency, framework dependency, artifact state, download state, and SHA256.
• The catalog runtime object must match runtime/latest.json exactly.
• Catalog version records keep to manager-readable fields; release notes are required on each mod's versions endpoint.

Mod records

A published mod record gives the manager enough data to decide compatibility, dependency order, download safety, and install layout before extracting the ZIP.

{
  "id": "example.hello-lua",
  "latest": {
    "version": "0.1.3",
    "targetGameBuild": "23435040",
    "packageUrl": "https://smmods.com/downloads/mods/example.hello-lua/0.1.3/example.hello-lua-v0.1.3.zip",
    "sha256": "526f6fcd07610056b5d92ea7f509512d6a2cbc1c8f1e854ca593c6689050dc0b",
    "artifactStatus": "published",
    "downloadEnabled": true,
    "dependencies": {
      "starminer.framework": ">=0.5.5"
    }
  }
}

The catalog also includes example.hello-lua-companion, which depends on example.hello-lua. The site validator rejects mod-to-mod dependencies that do not resolve to another published catalog entry.

Detail and versions endpoints must stay aligned with the catalog. The site validator checks that alignment for every installable mod, including status, published time, and non-empty release notes on every versions endpoint record.

Download flow

1. Read catalog.json.
2. Compare the selected mod's targetGameBuild with the pinned runtime profile.
3. Install or update the pinned UE4SS runtime and starminer.framework.
4. Resolve mod dependencies before downloading mod ZIPs.
5. Verify SHA256 from the exact downloaded artifact.
6. Extract only after validation, then update UE4SS Mods/mods.txt enablement state.

Publication gates

Before a release appears as installable API data, the portal must have:

• An immutable ZIP under public/downloads/.
• A SHA256 hash computed from that tracked ZIP.
• artifactStatus that reflects the artifact's real release state.
• downloadEnabled: true only after static validation and manager parsing pass.
• Matching catalog, detail, and version endpoint metadata.
• A release sidecar that matches the public schema and points at an existing detail page.
• Backend services from backendRequirements before authenticated uploads are marked live.