inkwell
Sign in
← Documentation

Publish mods on Inkwell

Mods have their own catalog at /mods and their own dashboard at /dashboard/mods. Switch between Games and Mods at the top of browse. Mod listings never become playable builds, and do not appear in the games catalog.

Every account has can publish mods enabled by default, including existing players. Complete account setup and accept the current Terms and Privacy Policy. Game creator approval is not required. Administrators can disable mod publishing independently, take down listings, or suspend accounts. Disabling publishing prevents new/updated listings; takedown hides existing content. Owners can still remove a listing after the mod permission is disabled.

What to share

Link to the mod components you have the rights to distribute: patches, scripts, configuration and original assets. Require players to obtain their own lawful copy of the base game. Do not share or link to unauthorized base-game source, copied assets, ROMs or complete games. Calling something a mod, or hosting it elsewhere, does not establish distribution rights. Respect the game’s license and modding rules. Inkwell does not endorse linked projects or verify their ownership, safety or legality.

Each visible publication/update requires a rights confirmation, an external repository or project URL, and installation instructions. The report button accepts copyright and other concerns. Moderators can take down and restore a mod separately from games.

Make a page

Open Manage mods → New mod. Add a title, stable slug, base game, short description, compatibility and tags. Link a GitHub repository (https://github.com/owner/repo), a project site, and optionally a release/download page. A repository link does not install a GitHub App, import files, verify ownership, or trigger deployments.

Add an external cover image, up to 8 screenshots with captions, and up to 4 video links. YouTube and Vimeo videos load after a click; other video links open externally. Images load directly from their hosts with no referrer. Download files, images, videos and repository source remain externally hosted; there is no mod file upload endpoint.

Write an About section and an installation guide in Markdown. Include required game version, platform, mod loader, dependencies, backup and removal steps as applicable. Choose Draft (owner only), Unlisted (anyone with the link), or Public (appears in Mods). All published modes require the rights checkbox, including updates. Slugs cannot be changed after creation.

CLI

Use Inkwell CLI 0.0.14 or later and sign in with inkwell login, or set INKWELL_TOKEN to a developer key. Tokens belong only in local/server tooling. inkwell whoami reports mod publishing permission independently of game creator approval.

inkwell mods create --mod my-mod --title "My Mod" --base-game "Example Game" --repository https://github.com/me/my-mod --install-file INSTALL.md
inkwell mods update --mod my-mod --description-file ABOUT.md --metadata media.json
inkwell mods publish --mod my-mod --rights-confirmed
inkwell mods list
inkwell mods browse --base-game "Example Game"
inkwell mods show --mod my-mod
inkwell mods unpublish --mod my-mod
inkwell mods delete --mod my-mod --yes
inkwell docs mods

--metadata reads a JSON metadata file, not a mod archive. Flags override fields in the file. Additional flags: --summary, --compatibility, --tags (comma-separated), --project, --download, --cover-url, --visibility draft|unlisted|public. Public/unlisted updates need --rights-confirmed. Omitted fields stay unchanged; null clears URL fields and [] clears media/tags. Use --revision N to submit against a known revision; otherwise the CLI reads the current revision. A 409 requires reviewing the current listing before retrying.

Example media.json:

{
  "coverUrl": "https://example.com/cover.jpg",
  "screenshots": [{ "url": "https://example.com/screenshot.jpg", "caption": "The updated interface" }],
  "videos": [{ "url": "https://example.com/showcase", "caption": "Mod showcase" }]
}

SDK

Use the separate @silicon-jungle/inkwell-sdk/mods entry point in SDK 0.0.10 or later. It calls the listing API directly, independent of the game iframe/runtime SDK. Public catalog reads need no token. Owner operations require a developer token on a server or CLI; never ship it to a browser. Importing the normal game SDK does not include the mod publishing client.

import { createModClient } from '@silicon-jungle/inkwell-sdk/mods';
const catalog = createModClient();
const { mods, nextOffset } = await catalog.browse({ baseGame: 'Example Game' });

// Server/CLI only:
const client = createModClient({ token: process.env.INKWELL_TOKEN });
const { mod } = await client.create({
  slug: 'my-mod', title: 'My Mod', baseGame: 'Example Game',
  repositoryUrl: 'https://github.com/me/my-mod',
  installationMarkdown: 'Install the patch on your own lawful copy of Example Game.'
});
await client.update(mod.slug, {
  revision: mod.revision, visibility: 'public', rightsConfirmed: true
});

Methods: browse({q?,baseGame?,offset?}), getPublic(slug), list(offset?), get(slug), create(input), update(slug,input), remove(slug). Errors expose HTTP status through ModApiError. API origin defaults to https://inkwell.ing. Use apiUrl only for a trusted deployment; HTTP is restricted to localhost development. Requests do not follow redirects or send browser cookies. Public calls do not send the token.

API and limits

  • GET /api/v1/catalog/mods?q=&baseGame=&offset=0: public catalog, {mods,nextOffset}.
  • GET /api/v1/catalog/mods/:slug: {mod}, public/unlisted only. No private account IDs or rights attestations.
  • GET/POST /api/v1/mods: authenticated owner list/create; creation returns {mod}, status 201.
  • GET/PATCH/DELETE /api/v1/mods/:slug: authenticated owner read/update/remove; GET/PATCH return {mod}, DELETE returns {deleted:true}.

Create requires slug, title and baseGame. Other fields: description, compatibility, tags, repositoryUrl, projectUrl, downloadUrl, coverUrl, screenshots, videos, descriptionMarkdown, installationMarkdown, visibility, rightsConfirmed. PATCH also requires the current integer revision. Each successful update increments revision. Unknown fields and non-JSON bodies are rejected; there is no build, upload or source payload. Visibility defaults to draft.

Lists contain up to 24 items and nextOffset (null at the end). Offset range: 0–999999. Base-game filter is exact. Search matches title, summary, base game or public username. Mod creation is limited to 10 per UTC day, separately from game creation. Existing account/write rate limits apply. Metadata bodies are limited to 300 KB; title/baseGame 120 characters, summary/compatibility 300, slug 3–64 lowercase letters/numbers/single hyphens, tags up to 8 × 30 characters, About Markdown 40,000, installation Markdown 20,000, URLs 2,048, media captions 180. URLs must use public HTTPS hosts, without credentials or custom ports.

401 means sign-in required; 403 means consent, account, publishing permission or takedown restriction; 404 means absent/inaccessible; 409 means slug/revision conflict; 429 means rate/quota limit. Game publishing permissions remain unchanged. Mod URLs cannot be passed to game build-upload endpoints because mods are separate records.

Deleted listings are hidden immediately. Deleting an account removes its mod records, and account export includes mod metadata. External project content remains under the external host’s controls. See /terms and /privacy for the complete policies.