API pública

Acceso estructurado y de solo lectura a los informes de compatibilidad de la comunidad sobre mapas, autobuses, vehículos, mods, objetos, plugins y herramientas que se ejecutan en openOMSI. Pensada para desarrolladores de openOMSI, herramientas de análisis, bots e integraciones.

Esta NO es una API para reportar errores de openOMSI. Los errores del propio motor corresponden a los canales oficiales del proyecto. Aquí solo se lee lo que la comunidad ha probado.

⚠ LÍMITE DE PETICIONES DE LA API PÚBLICA

6 peticiones por IP cada 60 minutos

Esta API tiene un límite de peticiones deliberadamente estricto porque es pública y no requiere autenticación.

Diseña las integraciones para almacenar las respuestas en caché localmente.
No consultes la API de forma continua.
Usa endpoints agregados siempre que sea posible: una sola llamada responde a la mayoría de las preguntas.

El límite se comparte entre todos los endpoints públicos y se aplica solo a consumidores externos; el propio sitio web no usa esta cuota.

Inicio rápido

URL base: https://openomsi.omsimods.com.br/api/public/v1. Todo es JSON, solo GET, sin autenticación. Empieza por el endpoint meta para descubrir los valores exactos que aceptan los filtros.

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)

Límite de peticiones, cabeceras y errores

Cada respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Al superar el límite, la API responde 429 con Retry-After (segundos).
Las peticiones condicionales (If-None-Match / If-Modified-Since) devuelven 304 sin cuerpo, pero un 304 también cuenta para la cuota.
Los errores siempre usan el mismo formato {"error": code, "message": text}; estados 400, 404, 429 y 500. Nunca se devuelven trazas de pila.

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
}

Casos de uso prácticos

Los valores de ejemplo son ilustrativos; la forma de las respuestas es real.

1. ¿Funciona Grand Paris Moulon en Windows?

Una sola llamada devuelve el resumen por plataforma, las categorías de problemas, la distribución de FPS, las versiones probadas y los últimos informes. Lee compatibility.by_platform.WINDOWS.

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

Respuesta (abreviada)

{
  "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. Listar los mapas probados en Android

Filtra por tipo y plataforma. Cada elemento ya incluye totales, plataformas probadas y la última versión de openOMSI probada.

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

Respuesta (abreviada)

{
  "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. Como desarrollador de openOMSI, ver los problemas de texturas en la versión actual

Filtra los informes por versión de openOMSI y categoría de problema. Cada informe lista issue_categories estructurado junto con la descripción del tester.

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

Respuesta (abreviada)

{
  "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. Detectar una posible regresión entre versiones

compare muestra un mismo contenido lado a lado en dos versiones; regressions lista todo el contenido que antes funcionaba y ahora reporta problemas. Los resultados son solo posibles regresiones, nunca confirmadas.

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

Respuesta (abreviada)

{
  "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. Alimentar un bot de Discord

Busca por nombre y construye la respuesta a partir del primer elemento: nombre, plataforma, resultado, última versión probada y número de informes. Guárdalo en caché por tu parte.

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

Respuesta (abreviada)

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

Respuesta sugerida para el bot

Grand Paris Moulon
Windows
⚠ Funciona con problemas
Últimos probados: 0.1.126
Informes: 4

6. ¿Qué problemas se reportan más en Android?

El endpoint issues agrega las categorías con el número de informes y de contenidos distintos; el endpoint de plataforma añade los dispositivos más reportados y los 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

Respuesta (abreviada)

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

7. Versión actual y descargas

releases/latest devuelve la versión, la fecha de publicación, la URL de GitHub y los recursos de descarga oficiales por plataforma y arquitectura.

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

Respuesta (abreviada)

{
  "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. Encontrar contenido que nadie ha probado aún

has_reports=false lista el contenido aprobado sin informes; combínalo con type o q.

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

Respuesta (abreviada)

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

Endpoints

Todas las rutas empiezan por https://openomsi.omsimods.com.br/api/public/v1. La descripción completa legible por máquina es el documento OpenAPI.

Endpoint	Qué devuelve
`GET /meta`	Taxonomías, límites y versión de la API.
`GET /status`	Comprobación operativa (también limitada: no la consultes en bucle).
`GET /content`	Búsqueda de contenido con totales de informes, plataformas probadas y última versión probada por elemento.
`GET /content/{slug}`	Un contenido en una sola llamada: fuentes, compatibilidad, problemas, rendimiento, versiones probadas, dispositivos y últimos informes.
`GET /reports`	Informes individuales con categorías de problemas estructuradas, FPS, hardware y fechas.
`GET /compatibility`	Agregado por versión de openOMSI, plataforma o tipo de contenido.
`GET /compatibility/compare`	Un contenido comparado entre dos versiones de openOMSI.
`GET /compatibility/regressions`	Posibles regresiones entre versiones probadas consecutivas.
`GET /issues`	Categorías de problemas ordenadas por informes y contenidos afectados.
`GET /platforms/{platform}`	Agregado de una plataforma (android, windows, linux, macos).
`GET /devices`	Hardware introducido por los testers, agrupado y contabilizado.
`GET /runtime-reports`	Pruebas de dispositivo del propio openOMSI (puede que la sesión nunca llegara a iniciarse): hardware, sistema operativo, hasta dónde llegó, API gráfica, texto de error sanitizado y un registro sanitizado opcional. Sin contenido de por medio.
`GET /runtime-reports/{id}`	Una prueba de dispositivo, con su registro sanitizado cuando lo hay.
`GET /releases/latest`	Versión actual y recursos de descarga oficiales.
`GET /releases`	Historial de versiones paginado.

Las pruebas de dispositivo nunca exponen el registro original, las IP, los correos electrónicos, los nombres de usuario ni los identificadores de cuenta: solo datos técnicos y el registro sanitizado. Son observaciones de la comunidad, no un benchmark ni un requisito oficial.

Filtros, paginación, ordenación y campos

Paginación: page (desde 1) y limit (por defecto 20, máximo 50). Las listas responden {"data": [...], "pagination": {page, limit, total, pages}}.
Ordenación: sort = reports, recent, name, latest_test o issues; order = asc o desc.
El parámetro opcional fields=name,slug,type conserva solo esos campos de primer nivel de cada elemento. La respuesta por defecto ya es completa.
Los filtros de enumerados no distinguen mayúsculas de minúsculas y aceptan listas separadas por comas (platform=ANDROID,WINDOWS).
Cuando se usan filtros de informes (platform, result, openomsi_version, issue_category) en la búsqueda de contenido, los recuentos se refieren a los informes coincidentes.

Parámetros

Parámetro	Descripción
`q`	Búsqueda de texto en los nombres y alias de los contenidos.
`type`	Tipo de contenido. Se permite una lista separada por comas.
`platform`	Plataforma del informe. Se permite una lista separada por comas.
`result`	Resultado indicado por el tester. Se permite una lista separada por comas.
`openomsi_version`	Versión de openOMSI en la que se ejecutó la prueba.
`issue_category`	Categoría de problema asociada al informe (AUDIO se acepta como alias de SOUND). Se permite una lista separada por comas.
`author`	Autor del contenido (coincidencia parcial).
`has_reports`	true: solo contenido probado; false: solo contenido que nadie ha probado todavía.
`sort`	Campo de ordenación.
`order`	Sentido de la ordenación.
`page`	Número de página, empezando en 1.
`limit`	Elementos por página (máximo 50).
`fields`	Campos de primer nivel separados por comas que se conservan en cada elemento (opcional; por defecto, el elemento completo).
`content`	Slug o id del contenido (exacto), o parte de su nombre.
`architecture`	Arquitectura de CPU del informe. Se permite una lista separada por comas.
`device`	Texto contenido en el nombre del dispositivo.
`has_fps`	Solo informes con (true) o sin (false) valor de FPS.
`from`	reports: probado en esta fecha ISO o después. compare/regressions: versión anterior de openOMSI.
`to`	reports: probado en esta fecha ISO o antes. compare/regressions: versión más reciente de openOMSI.
`startup_stage`	Hasta dónde llegó openOMSI en el dispositivo. Se permite una lista separada por comas.
`graphics_backend`	API gráfica elegida por el tester. Se permite una lista separada por comas.
`gpu`	Texto contenido en el nombre de la GPU.
`cpu`	Texto contenido en el nombre de la CPU.
`manufacturer`	Fabricante del dispositivo (coincidencia parcial).
`device_model`	Modelo del dispositivo (coincidencia parcial).
`os_version`	Versión del sistema operativo (coincidencia parcial).
`media_indexing_observed`	Android: el tester indicó que la galería o el escáner de medios estaba indexando imágenes de OMSI (true) o no (false).
`has_log`	Solo pruebas con (true) o sin (false) registro sanitizado.
`include_log`	Incluye sanitized_log en cada elemento (por defecto false: la lista solo indica has_sanitized_log).

Enumerados / Taxonomías

Generado a partir de las propias listas de la aplicación. AUDIO se acepta como alias de SOUND en los filtros.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Datos de rendimiento

Los FPS y los tiempos de carga son datos REPORTADOS POR USUARIOS, no un benchmark controlado. Las estadísticas usan primero la mediana e incluyen siempre el tamaño de la muestra (samples), además de mín. y máx.

Caché, CORS y versionado

Las respuestas incluyen Cache-Control, ETag y Last-Modified. Los navegadores pueden reutilizarlas durante unos minutos; las cachés compartidas deben revalidar para que la cuota se aplique siempre.
CORS está abierto solo para GET, HEAD y OPTIONS. No hay métodos de escritura.
La API está versionada en la ruta (/api/public/v1). Las rutas antiguas sin versión redirigen (308) a v1. Los cambios incompatibles solo se publicarán como una nueva versión.
El sitio web de openOMSI Compatibility lee su propia base de datos directamente y nunca consume esta API ni su cuota.

Directrices de integración

Guarda los datos en caché localmente.
Evita el polling; solicita solo cuando sea necesario.
Usa endpoints agregados (detalle de contenido, compatibilidad, problemas, plataformas).
Respeta Retry-After y las cabeceras RateLimit-*.
No hagas scraping de HTML cuando la API tiene datos equivalentes.
No deduzcas errores confirmados del motor a partir de informes de la comunidad.
Conserva siempre la versión de openOMSI en tus análisis.

Acerca de los datos

Los informes de la comunidad son observaciones, no una certificación de compatibilidad con autoridad. Un solo informe no significa "este mod es compatible" ni "esto es un error de openOMSI". Ten en cuenta el número de muestras, la versión de openOMSI, la plataforma, el hardware, la versión del contenido, la categoría del problema y la coherencia entre informes.

Privacidad

Las respuestas nunca incluyen IDs de Discord, correos electrónicos, direcciones IP, sesiones, suscripciones a notificaciones, datos de moderación ni identificadores de dispositivo. Los informes muestran solo el nombre público y el hardware que el tester decidió publicar. En un informe, issue_categories es estructurado, mientras que issue_description es la única descripción de texto libre del tester para todo el informe.

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