Public API

Structured, read-only access to community compatibility reports of maps, buses, vehicles, mods, objects, plugins and tools running on openOMSI. Built for openOMSI developers, analysis tools, bots and integrations.

This is NOT an API for reporting openOMSI bugs. Bugs of the engine itself belong to the project's official channels. Here you only read what the community has tested.

⚠ PUBLIC API RATE LIMIT

6 requests per IP per 60 minutes

This API is intentionally heavily rate-limited because it is public and does not require authentication.

Design integrations to cache responses locally.
Do not poll the API continuously.
Use aggregate endpoints whenever possible: one call answers most questions.

The limit is shared by every public endpoint and applies to external consumers only; the website itself does not use this quota.

Quick start

Base URL: https://openomsi.omsimods.com.br/api/public/v1. Everything is JSON, GET only, no authentication. Start with the meta endpoint to discover the exact values accepted by the filters.

curl https://openomsi.omsimods.com.br/api/public/v1/meta
curl "https://openomsi.omsimods.com.br/api/public/v1/content?q=millennium&type=VEHICLE"

OpenAPI (JSON)

Rate limit, headers and errors

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. After the limit, the API answers 429 with Retry-After (seconds).
Conditional requests (If-None-Match / If-Modified-Since) return 304 without a body, but a 304 still counts against the quota.
Errors always use the same format {"error": code, "message": text}; statuses 400, 404, 429 and 500. No stack traces are ever returned.

HTTP/1.1 429 Too Many Requests
Retry-After: 1234
RateLimit-Limit: 6
RateLimit-Remaining: 0
RateLimit-Reset: 1234

{
  "error": "rate_limit_exceeded",
  "message": "Public API limit reached. Try again later.",
  "retry_after": 1234
}

Practical use cases

Example values are illustrative; the shape of the responses is real.

1. Does Grand Paris Moulon work on Windows?

One call returns the summary by platform, issue categories, FPS distribution, versions tested and the latest reports. Read compatibility.by_platform.WINDOWS.

GET https://openomsi.omsimods.com.br/api/public/v1/content/grand-paris-moulon

Response (abridged)

{
  "compatibility": {
    "total_reports": 4,
    "works": 2,
    "works_with_issues": 2,
    "does_not_work": 0,
    "inconclusive": 0,
    "low_data": false,
    "by_platform": {
      "WINDOWS": {
        "reports": 4,
        "works": 2,
        "works_with_issues": 2,
        "does_not_work": 0,
        "inconclusive": 0,
        "latest_tested_openomsi_version": "0.1.126",
        "fps": {
          "samples": 3,
          "median": 38,
          "min": 28,
          "max": 60
        }
      }
    }
  },
  "issues": {
    "by_category": {
      "TEXTURES": 2,
      "SCRIPTS": 1
    },
    "reports_with_issues": 2
  },
  "performance": {
    "source": "user_reported",
    "fps": {
      "samples": 3,
      "median": 38,
      "min": 28,
      "max": 60
    },
    "load_time_seconds": {
      "samples": 2,
      "median": 95,
      "min": 80,
      "max": 110
    }
  },
  "latest_tested_openomsi_version": "0.1.126"
}

2. List maps tested on Android

Filter by type and platform. Each item already carries totals, platforms tested and the latest tested openOMSI version.

GET https://openomsi.omsimods.com.br/api/public/v1/content?type=MAP&platform=ANDROID&sort=reports&limit=20

Response (abridged)

{
  "data": [
    {
      "id": "cm0millennium1",
      "slug": "mapa-brigadeiro-sampaio",
      "name": "Mapa Brigadeiro Sampaio",
      "type": "MAP",
      "author": null,
      "current_version": null,
      "url": "https://openomsi.omsimods.com.br/conteudo/caio-millennium-brt-i-o500u",
      "source_url": "https://omsimods.com.br/",
      "image_url": null,
      "omsimodsbr_verified": true,
      "reports": {
        "total": 3,
        "works": 0,
        "works_with_issues": 3,
        "does_not_work": 0,
        "inconclusive": 0,
        "by_platform": {
          "WINDOWS": {
            "reports": 3,
            "works": 0,
            "works_with_issues": 3,
            "does_not_work": 0,
            "inconclusive": 0
          }
        }
      },
      "reports_with_issues": 3,
      "latest_tested_openomsi_version": "0.1.126",
      "latest_test_at": "2026-09-29T15:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

3. As an openOMSI developer, show texture problems in the current version

Filter reports by openOMSI version and issue category. Every report lists structured issue_categories plus the tester's description.

GET https://openomsi.omsimods.com.br/api/public/v1/reports?openomsi_version=0.1.126&issue_category=TEXTURES&limit=50

Response (abridged)

{
  "data": [
    {
      "id": "cm0report0001",
      "content": {
        "id": "cm0grandparis01",
        "slug": "grand-paris-moulon",
        "name": "Grand Paris Moulon",
        "type": "MAP"
      },
      "content_version": null,
      "openomsi_version": "0.1.126",
      "platform": "WINDOWS",
      "architecture": "X64",
      "result": "WORKS_WITH_ISSUES",
      "fps": {
        "avg": 41,
        "min": 28,
        "max": 60
      },
      "load_time_seconds": 95,
      "device": {
        "label": "Desktop GTX 1060",
        "model": null,
        "os_version": "Windows 11",
        "cpu": "Ryzen 5 3600",
        "gpu": "GTX 1060 6GB",
        "ram_gb": 16
      },
      "issue_categories": [
        "TEXTURES"
      ],
      "issue_description": "Windows of some black buses render with wrong textures.",
      "notes": null,
      "tested_at": "2026-09-29T17:02:00.000Z",
      "screenshot_url": null,
      "author": {
        "display_name": "tester"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

4. Detect a possible regression between versions

compare shows one content side by side in two versions; regressions lists every content that worked before and reports problems now. Results are only possible regressions, never confirmed ones.

GET https://openomsi.omsimods.com.br/api/public/v1/compatibility/compare?content=grand-paris-moulon&from=0.1.121&to=0.1.126
GET https://openomsi.omsimods.com.br/api/public/v1/compatibility/regressions?from=0.1.121&to=0.1.126&type=BUS

Response (abridged)

{
  "changes": [
    {
      "platform": "WINDOWS",
      "from": {
        "works": 3,
        "works_with_issues": 0,
        "does_not_work": 0,
        "inconclusive": 0
      },
      "to": {
        "works": 1,
        "works_with_issues": 3,
        "does_not_work": 0,
        "inconclusive": 0
      },
      "from_reports": 3,
      "to_reports": 4,
      "possible_regression": true
    }
  ],
  "possible_regression": true
}

5. Feed a Discord bot

Search by name, then build the answer from the first item: name, platform, result, latest tested version and number of reports. Cache it on your side.

GET https://openomsi.omsimods.com.br/api/public/v1/content?q=grand%20paris&platform=WINDOWS&limit=1

Response (abridged)

{
  "data": [
    {
      "name": "Grand Paris Moulon",
      "reports": {
        "total": 4,
        "works": 2,
        "works_with_issues": 2
      },
      "latest_tested_openomsi_version": "0.1.126"
    }
  ]
}

Suggested bot reply

Grand Paris Moulon
Windows
⚠ Works with issues
Latest tested: 0.1.126
Reports: 4

6. Which problems are reported most on Android?

The issues endpoint aggregates categories with the number of reports and of distinct contents; the platform endpoint adds the most reported devices and FPS.

GET https://openomsi.omsimods.com.br/api/public/v1/issues?platform=ANDROID&openomsi_version=0.1.126
GET https://openomsi.omsimods.com.br/api/public/v1/platforms/android

Response (abridged)

{
  "data": [
    {
      "category": "TEXTURES",
      "reports": 31,
      "contents": 18
    },
    {
      "category": "PHYSICS",
      "reports": 22,
      "contents": 14
    }
  ]
}

7. Current release and downloads

releases/latest returns the version, publication date, GitHub URL and the official download assets by platform and architecture.

GET https://openomsi.omsimods.com.br/api/public/v1/releases/latest

Response (abridged)

{
  "version": "0.1.126",
  "published_at": "2026-09-27T20:11:00.000Z",
  "github_url": "https://github.com/openOMSI-org/openOMSI/releases/tag/v0.1.126",
  "assets": [
    {
      "key": "android-arm64",
      "label": "Android ARM64",
      "platform": "ANDROID",
      "architecture": "ARM64",
      "type": "CLIENT",
      "name": "openOMSI-android-arm64.apk",
      "download_url": "https://github.com/openOMSI-org/openOMSI/releases/download/v0.1.126/openOMSI-android-arm64.apk",
      "size_bytes": 152043520
    }
  ]
}

8. Find content nobody has tested yet

has_reports=false lists approved content without reports; combine it with type or q.

GET https://openomsi.omsimods.com.br/api/public/v1/content?has_reports=false&type=MAP&limit=50

Response (abridged)

{
  "data": [
    {
      "name": "…",
      "type": "MAP",
      "reports": {
        "total": 0
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 312,
    "pages": 7
  }
}

Endpoints

All paths start with https://openomsi.omsimods.com.br/api/public/v1. The full machine-readable description is the OpenAPI document.

Endpoint	What it returns
`GET /meta`	Taxonomies, limits and API version.
`GET /status`	Operational check (rate-limited too: do not poll it).
`GET /content`	Content search with report totals, platforms tested and latest tested version per item.
`GET /content/{slug}`	One content in a single call: sources, compatibility, issues, performance, versions tested, devices and latest reports.
`GET /reports`	Individual reports with structured issue categories, FPS, hardware and dates.
`GET /compatibility`	Aggregate by openOMSI version, platform or content type.
`GET /compatibility/compare`	One content compared between two openOMSI versions.
`GET /compatibility/regressions`	Possible regressions between consecutive tested versions.
`GET /issues`	Issue categories ranked by reports and affected contents.
`GET /platforms/{platform}`	Aggregate for one platform (android, windows, linux, macos).
`GET /devices`	Hardware entered by testers, grouped and counted.
`GET /runtime-reports`	Device tests of openOMSI itself (the session may never have started): hardware, OS, how far it got, graphics API, sanitized error text and an optional sanitized log. No content involved.
`GET /runtime-reports/{id}`	One device test, with its sanitized log when there is one.
`GET /releases/latest`	Current release and official download assets.
`GET /releases`	Paginated release history.

Device tests never expose the original log, IPs, e-mails, user names or account identifiers: only technical data and the sanitized log. They are community observations, not a benchmark or an official requirement.

Filters, pagination, sorting and fields

Pagination: page (from 1) and limit (default 20, maximum 50). Lists answer {"data": [...], "pagination": {page, limit, total, pages}}.
Sorting: sort = reports, recent, name, latest_test or issues; order = asc or desc.
Optional fields=name,slug,type keeps only those top-level fields of each item. The default response is already complete.
Enum filters are case-insensitive and accept comma-separated lists (platform=ANDROID,WINDOWS).
When report filters (platform, result, openomsi_version, issue_category) are used on content search, the counts refer to the matching reports.

Parameters

Parameter	Description
`q`	Text search in content names and aliases.
`type`	Content type. Comma-separated list allowed.
`platform`	Platform of the report. Comma-separated list allowed.
`result`	Result reported by the tester. Comma-separated list allowed.
`openomsi_version`	openOMSI version the test ran on.
`issue_category`	Issue category attached to the report (AUDIO is accepted as an alias of SOUND). Comma-separated list allowed.
`author`	Content author (partial match).
`has_reports`	true: only tested content; false: only content nobody has tested yet.
`sort`	Sort field.
`order`	Sort direction.
`page`	Page number, starting at 1.
`limit`	Items per page (maximum 50).
`fields`	Comma-separated top-level fields to keep in each item (optional; the default is the full item).
`content`	Content slug or id (exact), or part of its name.
`architecture`	CPU architecture of the report. Comma-separated list allowed.
`device`	Text contained in the device name.
`has_fps`	Only reports with (true) or without (false) an FPS value.
`from`	reports: tested on or after this ISO date. compare/regressions: older openOMSI version.
`to`	reports: tested on or before this ISO date. compare/regressions: newer openOMSI version.
`startup_stage`	How far openOMSI got on the device. Comma-separated list allowed.
`graphics_backend`	Graphics API chosen by the tester. Comma-separated list allowed.
`gpu`	Text contained in the GPU name.
`cpu`	Text contained in the CPU name.
`manufacturer`	Device manufacturer (partial match).
`device_model`	Device model (partial match).
`os_version`	OS version (partial match).
`media_indexing_observed`	Android: the tester reported that the gallery or media scanner was indexing OMSI images (true) or not (false).
`has_log`	Only tests with (true) or without (false) a sanitized log.
`include_log`	Include sanitized_log in each item (default false: the list only says has_sanitized_log).

Enums / Taxonomies

Generated from the application's own lists. AUDIO is accepted as an alias of SOUND in filters.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Performance data

FPS and load times are USER-REPORTED data, not a controlled benchmark. Statistics use the median first and always include sample size (samples), plus min and max.

Cache, CORS and versioning

Responses carry Cache-Control, ETag and Last-Modified. Browsers may reuse them for a few minutes; shared caches must revalidate so the quota is always enforced.
CORS is open for GET, HEAD and OPTIONS only. There are no write methods.
The API is versioned in the path (/api/public/v1). Older unversioned paths redirect (308) to v1. Breaking changes will only ship as a new version.
The openOMSI Compatibility website reads its own database directly and never consumes this API or its quota.

Integration guidelines

Cache data locally.
Avoid polling; request only when needed.
Use aggregate endpoints (content detail, compatibility, issues, platforms).
Respect Retry-After and the RateLimit-* headers.
Do not scrape HTML when the API has equivalent data.
Do not infer confirmed engine bugs from community reports.
Always keep the openOMSI version in your analyses.

About the data

Community reports are observations, not authoritative compatibility certification. A single report does not mean "this mod is compatible" nor "this is an openOMSI bug". Consider sample count, openOMSI version, platform, hardware, content version, issue category and consistency between reports.

Privacy

Responses never include Discord IDs, e-mails, IP addresses, sessions, notification subscriptions, moderation data or device identifiers. Reports show only the public display name and the hardware the tester chose to publish. In a report, issue_categories is structured while issue_description is the tester's single free-text description for the whole report.

https://openomsi.omsimods.com.br/api/openapi.json