API Reference

Base URL: https://mowser.net

All endpoints return JSON. Dates are in ISO 8601 / UTC format.

🔐 Authentication

Most endpoints are public. For protected endpoints (/api/profile), you need a Bearer token.

Get a token from your API Tokens page after logging in, then add the header: Authorization: Bearer <your-token>

✍️ Write API & Token Scopes

Tokens carry scopes chosen at creation: read (profile) or read,write. Write-scope endpoints (all Bearer-authenticated, JSON bodies):

POST /api/v1/mods — submit a new mod (enters the moderation queue)
PUT /api/v1/mods/:id — edit summary, license_url, description_md_url, tags
POST /api/v1/mods/:id/files — add a file (server-verified, see checksum auto-fill)
PUT|DELETE /api/v1/mods/:id/files/:file_id — edit or remove a file
POST /api/v1/mods/:id/links · DELETE /api/v1/mods/:id/links/:link_id — typed links (issues/source/social/donation)
POST /api/v1/lists — create a manifest: {"name", "entries": [{"id", "optional"}]}

Deliberately not available to tokens (log in on the website instead): deleting a whole mod, claiming or transferring ownership, team and member management, and token management. A leaked token can never destroy work or change who owns it.

Token management itself is API too, but session-cookie authenticated only — GET|POST /api/v1/tokens, DELETE /api/v1/tokens/:id. A Bearer header on these endpoints is always rejected: tokens cannot manage tokens. The website's token page is a direct client of these endpoints.

CSRF: Session-cookie POST/PUT/DELETE requests require a CSRF token — HTML forms carry it automatically; scripted clients using cookie auth must send it in the X-CSRF-Token header. Bearer-authenticated requests are exempt (a Bearer header is never attached automatically by a browser).

🧪 Interactive Testing

Fill in path/query params below, set a Bearer token if needed, then click "Try It" on any endpoint.

Bearer Token (optional — for protected endpoints)

Token is sent only in the request headers. Not stored server-side. Get one at /profile/tokens (you must be logged in).

POST

/api/v1/resolve

Resolve Mods

Resolve a list of mod Mowser IDs to their full details including download files, checksums, and metadata. Supports optional MC version and mod loader filters. Max 50 IDs per request.

Request URL: https://mowser.net/api/v1/resolve

Parameter	Location	Req	Value / Description
ids	body	Yes	Array of mod Mowser IDs to resolve
mc_version	body	No	Filter files by Minecraft version
mod_loader	body	No	Filter files by mod loader

Auth: NoneResponse: 200 OK

📄 Response Example (click to expand)

{
  "results": [
    {
      "id": "mowser:mod_a3K8mR2j",
      "name": "Applied Energistics 2",
      "slug": "ae2",
      "summary": "A mod about storing and managing resources",
      "files": [
        {
          "id": "mowser:file_b4X9pQ2k",
          "label": "AE2 1.20.1 Fabric 15.2.1",
          "urls": ["https://github.com/.../ae2-fabric-15.2.1.jar"],
          "checksum": "abc123...",
          "checksum_type": "sha256",
          "mc_version": "1.20.1",
          "mod_loader": "fabric"
        }
      ]
    }
  ]
}

Click "▶ Try It" above to send a live request.

GET

/api/v1/lookup/<mowser:mod_a3K8mR2j>

Lookup Resource

Look up any Mowser resource by its ID. Returns the full resource with type-specific fields. Works for mods, files, authors, and lists.

Request URL: https://mowser.net/api/v1/lookup/:id

Parameter	Location	Req	Value / Description
id	path	Yes	A Mowser ID (mod, file, author, or list)

Auth: NoneResponse: 200 OK

📄 Response Example (click to expand)

{
  "id": "mowser:mod_a3K8mR2j",
  "resource_type": "mod",
  "name": "Applied Energistics 2",
  "slug": "ae2",
  "summary": "A mod about storing and managing resources",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:22:00Z"
}

Click "▶ Try It" above to send a live request.

GET

/api/mods

Search Mods

List and search mods with optional filters. Returns paginated results sorted by most recently updated.

Request URL: https://mowser.net/api/mods

Parameter	Location	Req	Value / Description
q	query	No	Full-text search across name, summary, and slug
mc_version	query	No	Filter by Minecraft version
mod_loader	query	No	Filter by mod loader
tags	query	No	Comma-separated tags
page	query	No	Page number (default: 1)
per_page	query	No	Results per page (default: 20, max: 100)

Auth: NoneResponse: 200 OK

📄 Response Example (click to expand)

{
  "items": [
    {
      "id": "mowser:mod_a3K8mR2j",
      "slug": "ae2",
      "team_owner_slug": "testuser",
      "name": "Applied Energistics 2",
      "summary": "A mod about storing and managing resources",
      "tags": ["tech", "storage"],
      "owner_name": "TestUser",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:22:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

Click "▶ Try It" above to send a live request.

GET

/api/mods/<ae2>

Get Mod Detail

Get full details for a specific mod by its URL slug, including description, tags, and download files.

Request URL: https://mowser.net/api/mods/:slug

Parameter	Location	Req	Value / Description
slug	path	Yes	The mod's URL slug

Auth: NoneResponse: 200 OK

📄 Response Example (click to expand)

{
  "id": "mowser:mod_a3K8mR2j",
  "slug": "ae2",
  "team_owner_slug": "testuser",
  "name": "Applied Energistics 2",
  "summary": "A mod about storing and managing resources",
  "description_html": "Applied Energistics 2...",
  "description_md_url": "https://raw.githubusercontent.com/.../README.md",
  "license_url": "https://mit-license.org/",
  "source_url": "https://github.com/user/ae2",
  "tags": ["tech", "storage"],
  "files": [
    {
      "id": "mowser:file_b4X9pQ2k",
      "mod_id": "mowser:mod_a3K8mR2j",
      "label": "AE2 1.20.1 Fabric 15.2.1",
      "url": "https://github.com/.../ae2-fabric-15.2.1.jar",
      "checksum": "abc123...",
      "checksum_type": "sha256",
      "mc_version": "1.20.1",
      "mod_loader": "fabric",
      "created_at": "2025-01-20T14:22:00Z"
    }
  ],
  "links": [
    { "id": "a1b2c3d4-...", "type": "source", "url": "https://github.com/user/ae2" },
    { "id": "e5f6g7h8-...", "type": "donation", "url": "https://ko-fi.com/user" }
  ],
  "owner_name": "TestUser",
  "owner_id": "mowser:author_c7D8fR5m",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:22:00Z",
  "approved_at": "2025-01-15T11:00:00Z"
}

Click "▶ Try It" above to send a live request.

GET

/api/mods/<ae2>/files

Get Mod Files

List downloadable files for a mod, with optional filtering and pagination. Supports multiple download mirrors per file via the `all_urls` field.

Request URL: https://mowser.net/api/mods/:slug/files

Parameter	Location	Req	Value / Description
slug	path	Yes	The mod's URL slug
mc_version	query	No	Filter by exact Minecraft version
mod_loader	query	No	Filter by exact mod loader
label	query	No	Filter by substring match on the file label
page	query	No	Page number (default: 1)
per_page	query	No	Results per page (default: 20, max: 100)

Auth: NoneResponse: 200 OK

📄 Response Example (click to expand)

{
  "items": [
    {
      "id": "mowser:file_b4X9pQ2k",
      "mod_id": "mowser:mod_a3K8mR2j",
      "label": "AE2 1.20.1 Fabric 15.2.1",
      "url": "https://github.com/.../ae2-fabric-15.2.1.jar",
      "all_urls": [
        "https://github.com/.../ae2-fabric-15.2.1.jar",
        "https://mirror.example.com/ae2-fabric-15.2.1.jar"
      ],
      "checksum": "abc123...",
      "checksum_type": "sha256",
      "mc_version": "1.20.1",
      "mod_loader": "fabric",
      "created_at": "2025-01-20T14:22:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "pages": 1
}

Click "▶ Try It" above to send a live request.

GET

/api/profile

Get User Profile

Get the authenticated user's profile and a list of their mods. Requires a valid API token in the Authorization header.

Request URL: https://mowser.net/api/profile

Auth: Bearer tokenResponse: 200 OK

📄 Response Example (click to expand)

{
  "user": {
    "id": "mowser:author_c7D8fR5m",
    "display_name": "TestUser",
    "slug": "testuser",
    "created_at": "2025-01-10T08:00:00Z"
  },
  "mods": [
    {
      "id": "mowser:mod_a3K8mR2j",
      "slug": "ae2",
      "name": "Applied Energistics 2",
      "summary": "A mod about storing and managing resources",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:22:00Z"
    }
  ]
}

Click "▶ Try It" above to send a live request.