Public integration surface

Build on the PalMods API.

Search the catalog, inspect safe release metadata, check compatibility, and connect community actions through a stable JSON API designed for Palworld tooling.

Make your first request Browse endpoints

Quickstart

Your first catalog request.

No API key is required for public reads. Responses use JSON unless an endpoint explicitly documents a redirect or RSS payload.

curl --get 'https://www.palmods.gg/api/v1/mods' \
  --data-urlencode 'q=inventory' \
  --data-urlencode 'loader_types=lua,pak' \
  --data-urlencode 'platforms=steam' \
  --data-urlencode 'sort=most_downloaded' \
  --data-urlencode 'page_size=3'

{
  "mods": [
    {
      "id": "7fb3c6a8-1ac5-4e9a-8db1-cc7e66e4ad70",
      "slug": "example-inventory-mod",
      "title": "Example Inventory Mod",
      "summary": "A representative search result.",
      "category_slug": "gameplay",
      "author_handle": "example-author",
      "loader_type": "lua",
      "platforms": ["steam"],
      "download_count": 12480,
      "likely_broken": false,
      "newest_supported_version": "1.0"
    }
  ],
  "total": 18,
  "page": 1,
  "page_size": 3,
  "facets": {
    "categories": { "gameplay": 11, "utilities": 7 },
    "sides": { "client": 15, "both": 3 },
    "tags": { "inventory": 18 }
  }
}

Example records and UUIDs are illustrative. Production responses include the complete DTO fields documented by the typed client.

Before you build

Four rules that keep clients predictable.

Versioning, credentials, filtering, and install capability negotiation are part of the public contract.

Base URL

Start every integration at v1.

https://www.palmods.gg/api/v1

The unversioned /api alias is deprecated. Auth and upload routes are website internals and are excluded from the v1 rewrite.

Authentication

Reads are public. Writes identify a user.

Send a Supabase access token as Authorization: Bearer …, or use the signed-in website cookie session for same-origin browser requests. Release automation instead uses a mod-scoped publish token from the author setup guide.

Query values

Combine filters without extra requests.

List filters accept comma-separated values; category and side also accept repeated query keys. Boolean filters accept 1 or true.

Install contracts

Advertise only formats you understand.

Send supported package contracts on detail and file requests. Unknown clients receive conservative auto_install_ready values.

Safe installer behavior

Capability negotiation is not archive validation.

Supported values are palmods_game_root_v1 and pocketpair_info_v1. Even after the API marks a file auto-install ready, clients must revalidate the downloaded archive, paths, checksums, and install rules before writing into the game directory.

Common workflows

Requests you can adapt directly.

Each example pairs the request with the shape your integration should be prepared to consume.

Preflight

Check compatibility before offering an install.

Pass the player’s exact environment and keep the returned reason available to explain the verdict.

curl 'https://www.palmods.gg/api/v1/mods/example-inventory-mod/compatibility?game_version=1.0&platform=steam'

{
  "mod_id": "7fb3c6a8-1ac5-4e9a-8db1-cc7e66e4ad70",
  "verdict": "compatible",
  "reason": "Supports Palworld 1.0 on Steam.",
  "checked_against": {
    "game_version": "1.0",
    "platform": "steam",
    "is_known_version": true
  }
}

Installer

Request files with explicit package capabilities.

The response combines scan state, supported game versions, normalized package metadata, and a download handoff URL.

curl --get 'https://www.palmods.gg/api/v1/mods/example-inventory-mod/files' \
  --data-urlencode 'install_contracts=palmods_game_root_v1,pocketpair_info_v1'

[
  {
    "id": "4ad74fb0-0f26-4613-bfd3-308c10b606fb",
    "version": "2.1.0",
    "release_channel": "release",
    "loader_type": "lua",
    "game_versions_supported": ["1.0"],
    "virus_scan_status": "clean",
    "download_ready": true,
    "auto_install_ready": true,
    "package_format": "pocketpair_info_v1",
    "package_name": "ExampleInventoryMod",
    "package_version": "2.1.0",
    "official_dependencies": ["UE4SS"],
    "download_url": "https://www.palmods.gg/api/download/4ad74fb0-0f26-4613-bfd3-308c10b606fb"
  }
]

Authenticated write

Publish a review with a user access token.

The reviewer must have downloaded the mod, may submit only one review, and cannot be an author or co-author of that mod.

curl -X POST 'https://www.palmods.gg/api/v1/mods/example-inventory-mod/reviews' \
  -H 'Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "rating": 5,
    "title": "Works on my server",
    "body": "Tested with four players and a clean save backup.",
    "test_game_version": "1.0"
  }'

{
  "id": "5ec2a1b5-a32b-4013-b092-51629ed4507d",
  "mod_id": "7fb3c6a8-1ac5-4e9a-8db1-cc7e66e4ad70",
  "rating": 5,
  "title": "Works on my server",
  "body": "Tested with four players and a clean save backup.",
  "user_handle": "sample-user",
  "test_game_version": "1.0",
  "helpful_score": 0,
  "author_response": null,
  "created_at": "2026-07-15T20:14:00.000Z"
}

Endpoint reference

23 documented operations.

Open any route to see its parameters, authentication boundary, response type, and important behavioral notes.

Catalog

Mods, files, and compatibility

The core read path for browsers, launchers, desktop clients, and update checkers.

GET

/api/v1/mods

Search and browse mods with faceted filters, sorting, and pagination.

Returns

SearchResult — mods, total, page, page_size, and category/side/tag facets.

ParameterTypeDescription

qstring

Full-text search across mod titles and summaries.

categorystring | CSV

One or more category slugs. Repeated values also work.

loader_typesCSV

Filter by loader, such as lua or pak.

sidestring | CSV

Filter by client_only, server_only, or both.

platformsCSV

Supported game platforms.

game_versionstring

Defaults to the current registered Palworld version.

tagsCSV

Require matching public tags.

dedicated_server_onlyboolean

Use 1 or true to restrict results.

auto_installable_onlyboolean

Only return mods with a compatible one-click file.

include_nsfwboolean

NSFW results are excluded unless explicitly enabled.

sortenum

relevance, trending, newest, recently_updated, name, and other supported sorts.

time_windowenum

today, week, month, or all for time-sensitive sorts.

pageinteger

One-based page number. Defaults to 1.

page_sizeinteger

Results per page. Defaults to 24.

GET

/api/v1/mods/{idOrSlug}

Resolve one mod by UUID or slug, including author, requirements, gallery, and a primary file after install-contract negotiation.

Returns

ModDetailDTO with a capability-gated primary_file.

ParameterTypeDescription

idOrSlugpathrequired

Public mod UUID or URL slug.

install_contractsCSV

Package formats the installer understands.

GET

/api/v1/mods/{idOrSlug}/files

List downloadable releases and their scan status, compatibility, and installation metadata.

Returns

ModFileDTO[] ordered by the repository file listing.

ParameterTypeDescription

idOrSlugpathrequired

Public mod UUID or slug.

include_oldboolean

Use 1 to include archived releases.

install_contractsCSV

Package formats the installer understands.

Public callers only receive downloadable files. Authors may see pending or rejected files in their own authenticated response.

GET

/api/v1/mods/{idOrSlug}/compatibility

Check whether the clean releases for a mod match a game version and platform.

Returns

Compatibility verdict, plain-language reason, and the environment checked.

ParameterTypeDescription

idOrSlugpathrequired

Public mod UUID or slug.

game_versionstring

Defaults to the current registered version.

platformenum

Defaults to steam.

Community

Reviews, bugs, and statistics

Public feedback and aggregate activity without exposing private user data.

GET

/api/v1/mods/{idOrSlug}/reviews

Read paginated ratings, written reviews, test versions, and author responses.

Returns

Paginated<ReviewDTO>.

ParameterTypeDescription

pageinteger

One-based results page.

sortenum

Supported review ordering.

ratinginteger

Restrict to one rating from 1 through 5.

game_versionstring

Restrict to a tested game version.

GET

/api/v1/mods/{idOrSlug}/bugs

Read public bug reports with status and priority filters.

Returns

Paginated<BugDTO>.

ParameterTypeDescription

pageinteger

One-based results page.

statusenum

Restrict reports by workflow status.

priorityenum

Restrict reports by reported priority.

GET

/api/v1/mods/{idOrSlug}/stats

Read daily downloads, unique downloads, endorsements, views, and release breakdowns.

Returns

daily, files, and game_versions arrays. No personally identifiable data.

ParameterTypeDescription

daysinteger

Window from 1 through 90 days. Defaults to 30.

Discovery

Reference and discovery surfaces

Taxonomies, authors, collections, feeds, landing rails, and download handoff.

GET

/api/v1/categories

List the category taxonomy and public mod counts.

Returns

CategoryDTO[].

No query parameters or request body.

GET

/api/v1/game-versions

List the Palworld version registry and identify the current release.

Returns

GameVersionDTO[].

No query parameters or request body.

GET

/api/v1/authors/{handle}

Resolve an author profile by handle together with their public mods.

Returns

Author profile fields plus a mods array.

ParameterTypeDescription

handlepathrequired

Case-normalized public author handle.

GET

/api/v1/collections/{idOrSlug}

Resolve a collection, its pinned releases, notes, and load order.

Returns

Collection detail with ordered entries.

ParameterTypeDescription

idOrSlugpathrequired

Collection UUID or slug.

GET

/api/v1/landing

Load a curated public discovery rail.

Returns

Up to 12 public mod summaries.

ParameterTypeDescription

sectionenum

trending, hot, newest, recently_updated, most_endorsed, or editors_picks.

GET

/feed

Subscribe to newly published and updated mods as RSS.

Returns

application/rss+xml rather than JSON.

ParameterTypeDescription

categorystring

Optional category slug.

game_versionstring

Optional compatibility version.

The feed is intentionally unversioned and lives outside /api/v1.

GET

/api/v1/download/{fileId}

Record a valid download and redirect to a short-lived signed file URL.

Returns

HTTP redirect. Only clean, downloadable files are eligible.

ParameterTypeDescription

fileIdpathrequired

File UUID returned by a mod or files request.

Authenticated

User actions

Session-bound mutations for endorsements, follows, reviews, and bug reports.

POST

/api/v1/mods/{idOrSlug}/endorse

Endorse a mod after the authenticated user has downloaded it.

Auth

Returns

{ "ok": true }. Repeating the request is safe.

No query parameters or request body.

DELETE

/api/v1/mods/{idOrSlug}/endorse

Remove the current user’s endorsement.

Auth

Returns

{ "ok": true }. Repeating the request is safe.

No query parameters or request body.

POST

/api/v1/mods/{idOrSlug}/follow

Follow a mod to receive release notifications.

Auth

Returns

{ "ok": true }. Repeating the request is safe.

No query parameters or request body.

DELETE

/api/v1/mods/{idOrSlug}/follow

Stop receiving release notifications for a mod.

Auth

Returns

{ "ok": true }. Repeating the request is safe.

No query parameters or request body.

POST

/api/v1/mods/{idOrSlug}/reviews

Create one review for a downloaded mod. Authors and co-authors cannot review their own work.

Auth

Returns

201 Created with the new ReviewDTO.

ParameterTypeDescription

ratingintegerrequired

Whole number from 1 through 5.

titlestring

Optional title, up to 200 characters.

bodystring

Optional review body, up to 10,000 characters.

test_game_versionstring

Optional version tested by the reviewer.

POST

/api/v1/mods/{idOrSlug}/bugs

Create a public bug report against a mod.

Auth

Returns

201 Created with the new BugDTO.

ParameterTypeDescription

titlestringrequired

Short issue title, up to 300 characters.

descriptionstringrequired

Reproduction details, up to 20,000 characters.

priorityenum

Optional domain priority.

affected_versionstring

Affected mod release.

game_versionstring

Palworld version used.

platformenum

Platform used during reproduction.

Author automation

Release publishing

Durable, idempotent publishing for the first-party GitHub Action and CI clients.

POST

/api/v1/publish/releases

Create or replay an idempotent release job and receive a short-lived upload URL.

Auth

Returns

201 Created (or 200 replay) with job, upload, finalize_url, and status_url.

ParameterTypeDescription

Authorizationheaderrequired

Bearer pmp_v1_ publish token bound to the target mod.

Idempotency-Keyheaderrequired

Stable printable key, up to 200 characters, reused for workflow retries.

bodyJSONrequired

Strict release metadata, changelog, archive size, content type, and SHA-256.

Publish-token authentication only. Store the token as an encrypted CI secret and follow the author setup guide.

POST

/api/v1/publish/releases/{jobId}/finalize

Queue an uploaded archive for durable verification and scanning.

Auth

Returns

202 Accepted while processing, or the current terminal job state on a replay.

ParameterTypeDescription

jobIdpathrequired

Job UUID returned by release creation.

Safe to retry. The worker verifies the signed upload before creating a downloadable file.

GET

/api/v1/publish/releases/{jobId}

Read the safe status projection for a release job owned by the token.

Auth

Returns

Job status, author-safe error, and file/download links when ready.

ParameterTypeDescription

jobIdpathrequired

Job UUID returned by release creation.

Nonterminal responses include Retry-After. Storage keys and raw scanner reports are never returned.

Decision model

Compatibility verdicts are explainable.

Display both the verdict and its reason. A single color or icon is not enough context for an install decision.

compatible

An eligible release explicitly supports the requested game version and platform.

likely_broken

The newest declared support predates the requested version, so breakage is likely but not proven.

unknown

No usable game-version declaration is available for a confident result.

incompatible

The platform or execution-side requirements do not match the requested environment.

Failure handling

Errors use a small, consistent shape.

Non-2xx JSON responses return an { "error": "…" } object. Redirect endpoints are the exception.

400Bad requestInvalid JSON, unknown fields, or invalid values.

401Authentication requiredMissing, invalid, or expired credentials.

403ForbiddenSuspension, origin rejection, or a domain rule violation.

404Not foundThe requested mod, author, collection, or file does not exist.

409ConflictA non-idempotent resource already exists.

429Rate limitedBack off before retrying the user action.

500Server errorThe request could not be completed.

{
  "error": "Field \"rating\" must be an integer from 1 to 5."
}

First-party package

Coming soon

The typed TypeScript client is on the way.

We are preparing @palmods/api-client as a public package with typed filters and DTOs, bearer authentication, install-format negotiation, and structured errors. Until it is released, use the HTTP examples and response contracts above.

Typed DTOs Pluggable fetch Planned package

// Coming soon — planned API
import { PalModsClient } from '@palmods/api-client';

const client = new PalModsClient({
  baseUrl: 'https://www.palmods.gg/api/v1',
  installContracts: ['pocketpair_info_v1'],
});

const result = await client.checkCompatibility(
  'example-inventory-mod',
  { game_version: '1.0', platform: 'steam' },
);

if (result.verdict === 'compatible') {
  const files = await client.listModFiles('example-inventory-mod');
  console.log(files.filter((file) => file.auto_install_ready));
}

Continue building

Connect the API to a valid package.

Read the packaging contract Return to author docs

Search PalMods

More

Discover

Account & creation

Resources

Build on the PalMods API.

Your first catalog request.

Four rules that keep clients predictable.

Start every integration at v1.

Reads are public. Writes identify a user.

Combine filters without extra requests.

Advertise only formats you understand.

Capability negotiation is not archive validation.

Requests you can adapt directly.

Check compatibility before offering an install.

Request files with explicit package capabilities.

Publish a review with a user access token.

23 documented operations.

Mods, files, and compatibility

Reviews, bugs, and statistics

Reference and discovery surfaces

User actions

Release publishing

Compatibility verdicts are explainable.

Errors use a small, consistent shape.

The typed TypeScript client is on the way.

Connect the API to a valid package.