API publique

Accès structuré et en lecture seule aux rapports de compatibilité de la communauté pour les cartes, bus, véhicules, mods, objets, plugins et outils fonctionnant sur openOMSI. Conçue pour les développeurs d'openOMSI, les outils d'analyse, les bots et les intégrations.

Ce n'est PAS une API pour signaler des bugs d'openOMSI. Les bugs du moteur lui-même relèvent des canaux officiels du projet. Ici, vous consultez uniquement ce que la communauté a testé.

⚠ LIMITE DE L'API PUBLIQUE

6 requêtes par IP toutes les 60 minutes

Cette API est volontairement très limitée car elle est publique et ne nécessite aucune authentification.

Concevez vos intégrations pour mettre les réponses en cache localement.
N'interrogez pas l'API en continu (polling).
Utilisez les endpoints agrégés dès que possible : un seul appel répond à la plupart des questions.

La limite est partagée par tous les endpoints publics et ne s'applique qu'aux consommateurs externes ; le site lui-même n'utilise pas ce quota.

Démarrage rapide

URL de base : https://openomsi.omsimods.com.br/api/public/v1. Tout est en JSON, GET uniquement, sans authentification. Commencez par l'endpoint meta pour découvrir les valeurs exactes acceptées par les filtres.

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)

Limite, en-têtes et erreurs

Chaque réponse contient RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset. Une fois la limite atteinte, l'API répond 429 avec Retry-After (en secondes).
Les requêtes conditionnelles (If-None-Match / If-Modified-Since) renvoient 304 sans corps, mais un 304 compte tout de même dans le quota.
Les erreurs utilisent toujours le même format {"error": code, "message": texte} ; statuts 400, 404, 429 et 500. Aucune stack trace n'est jamais renvoyée.

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
}

Cas d'usage pratiques

Les valeurs des exemples sont illustratives ; la forme des réponses est réelle.

1. Grand Paris Moulon fonctionne-t-il sous Windows ?

Un seul appel renvoie le résumé par plateforme, les catégories de problèmes, la distribution des FPS, les versions testées et les derniers rapports. Lisez compatibility.by_platform.WINDOWS.

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

Réponse (abrégée)

{
  "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. Lister les cartes testées sur Android

Filtrez par type et plateforme. Chaque élément inclut déjà les totaux, les plateformes testées et la dernière version d'openOMSI testée.

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

Réponse (abrégée)

{
  "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. En tant que développeur d'openOMSI, afficher les problèmes de textures dans la version actuelle

Filtrez les rapports par version d'openOMSI et catégorie de problème. Chaque rapport liste des issue_categories structurées ainsi que la description du testeur.

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

Réponse (abrégée)

{
  "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. Détecter une possible régression entre versions

compare affiche un contenu côte à côte dans deux versions ; regressions liste tous les contenus qui fonctionnaient avant et signalent des problèmes maintenant. Les résultats ne sont que de possibles régressions, jamais confirmées.

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

Réponse (abrégée)

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

Recherchez par nom, puis construisez la réponse à partir du premier élément : nom, plateforme, résultat, dernière version testée et nombre de rapports. Mettez-la en cache de votre côté.

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

Réponse (abrégée)

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

Réponse suggérée pour le bot

Grand Paris Moulon
Windows
⚠ Fonctionne avec des problèmes
Derniers testés: 0.1.126
Rapports: 4

6. Quels problèmes sont les plus signalés sur Android ?

L'endpoint issues agrège les catégories avec le nombre de rapports et de contenus distincts ; l'endpoint de plateforme ajoute les appareils les plus signalés et les 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

Réponse (abrégée)

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

7. Release actuelle et téléchargements

releases/latest renvoie la version, la date de publication, l'URL GitHub et les fichiers de téléchargement officiels par plateforme et architecture.

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

Réponse (abrégée)

{
  "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. Trouver les contenus que personne n'a encore testés

has_reports=false liste les contenus approuvés sans rapports ; combinez-le avec type ou q.

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

Réponse (abrégée)

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

Endpoints

Tous les chemins commencent par https://openomsi.omsimods.com.br/api/public/v1. La description complète, lisible par machine, est le document OpenAPI.

Endpoint	Ce qu'il renvoie
`GET /meta`	Taxonomies, limites et version de l'API.
`GET /status`	Vérification opérationnelle (également limitée : ne l'interrogez pas en boucle).
`GET /content`	Recherche de contenus avec totaux de rapports, plateformes testées et dernière version testée par élément.
`GET /content/{slug}`	Un contenu en un seul appel : sources, compatibilité, problèmes, performances, versions testées, appareils et derniers rapports.
`GET /reports`	Rapports individuels avec catégories de problèmes structurées, FPS, matériel et dates.
`GET /compatibility`	Agrégat par version d'openOMSI, plateforme ou type de contenu.
`GET /compatibility/compare`	Un contenu comparé entre deux versions d'openOMSI.
`GET /compatibility/regressions`	Régressions possibles entre versions testées consécutives.
`GET /issues`	Catégories de problèmes classées par rapports et contenus concernés.
`GET /platforms/{platform}`	Agrégat pour une plateforme (android, windows, linux, macos).
`GET /devices`	Matériel saisi par les testeurs, regroupé et compté.
`GET /runtime-reports`	Tests d'appareil d'openOMSI lui-même (la session a pu ne jamais démarrer) : matériel, système, jusqu'où le test est allé, API graphique, texte d'erreur sanitisé et journal sanitisé facultatif. Aucun contenu n'est concerné.
`GET /runtime-reports/{id}`	Un test d'appareil, avec son journal sanitisé lorsqu'il existe.
`GET /releases/latest`	Release actuelle et fichiers de téléchargement officiels.
`GET /releases`	Historique paginé des releases.

Les tests d'appareil n'exposent jamais le journal original, les adresses IP, les e-mails, les noms d'utilisateur ni les identifiants de compte : uniquement des données techniques et le journal sanitisé. Ce sont des observations de la communauté, et non un benchmark ni une exigence officielle.

Filtres, pagination, tri et champs

Pagination : page (à partir de 1) et limit (20 par défaut, 50 maximum). Les listes répondent {"data": [...], "pagination": {page, limit, total, pages}}.
Tri : sort = reports, recent, name, latest_test ou issues ; order = asc ou desc.
Le paramètre optionnel fields=name,slug,type ne conserve que ces champs de premier niveau pour chaque élément. La réponse par défaut est déjà complète.
Les filtres d'enum sont insensibles à la casse et acceptent des listes séparées par des virgules (platform=ANDROID,WINDOWS).
Lorsque des filtres de rapport (platform, result, openomsi_version, issue_category) sont utilisés dans la recherche de contenus, les compteurs se rapportent aux rapports correspondants.

Paramètres

Paramètre	Description
`q`	Recherche textuelle dans les noms et alias des contenus.
`type`	Type de contenu. Liste séparée par des virgules acceptée.
`platform`	Plateforme du rapport. Liste séparée par des virgules acceptée.
`result`	Résultat signalé par le testeur. Liste séparée par des virgules acceptée.
`openomsi_version`	Version d'openOMSI sur laquelle le test a été exécuté.
`issue_category`	Catégorie de problème associée au rapport (AUDIO est accepté comme alias de SOUND). Liste séparée par des virgules acceptée.
`author`	Auteur du contenu (correspondance partielle).
`has_reports`	true : uniquement les contenus testés ; false : uniquement les contenus que personne n'a encore testés.
`sort`	Champ de tri.
`order`	Sens du tri.
`page`	Numéro de page, à partir de 1.
`limit`	Éléments par page (maximum 50).
`fields`	Champs de premier niveau à conserver dans chaque élément, séparés par des virgules (facultatif ; par défaut, l'élément complet).
`content`	Slug ou id du contenu (exact), ou partie de son nom.
`architecture`	Architecture CPU du rapport. Liste séparée par des virgules acceptée.
`device`	Texte contenu dans le nom de l'appareil.
`has_fps`	Uniquement les rapports avec (true) ou sans (false) valeur de FPS.
`from`	reports: testé à cette date ISO ou après. compare/regressions: version d'openOMSI plus ancienne.
`to`	reports: testé à cette date ISO ou avant. compare/regressions: version d'openOMSI plus récente.
`startup_stage`	Jusqu'où openOMSI est allé sur l'appareil. Liste séparée par des virgules acceptée.
`graphics_backend`	API graphique choisie par le testeur. Liste séparée par des virgules acceptée.
`gpu`	Texte contenu dans le nom du GPU.
`cpu`	Texte contenu dans le nom du CPU.
`manufacturer`	Fabricant de l'appareil (correspondance partielle).
`device_model`	Modèle de l'appareil (correspondance partielle).
`os_version`	Version du système (correspondance partielle).
`media_indexing_observed`	Android : le testeur a indiqué que la galerie ou le scanner multimédia indexait les images d'OMSI (true) ou non (false).
`has_log`	Uniquement les tests avec (true) ou sans (false) journal sanitisé.
`include_log`	Inclut sanitized_log dans chaque élément (par défaut false : la liste n'indique que has_sanitized_log).

Enums / Taxonomies

Généré à partir des listes de l'application elle-même. AUDIO est accepté comme alias de SOUND dans les filtres.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Données de performance

Les FPS et les temps de chargement sont des données DÉCLARÉES PAR LES UTILISATEURS, pas un benchmark contrôlé. Les statistiques utilisent d'abord la médiane et incluent toujours la taille de l'échantillon (samples), ainsi que le minimum et le maximum.

Cache, CORS et versionnage

Les réponses contiennent Cache-Control, ETag et Last-Modified. Les navigateurs peuvent les réutiliser pendant quelques minutes ; les caches partagés doivent revalider afin que le quota soit toujours appliqué.
CORS n'est ouvert que pour GET, HEAD et OPTIONS. Il n'existe aucune méthode d'écriture.
L'API est versionnée dans le chemin (/api/public/v1). Les anciens chemins sans version redirigent (308) vers v1. Les changements incompatibles ne seront publiés que sous forme de nouvelle version.
Le site openOMSI Compatibility lit directement sa propre base de données et ne consomme jamais cette API ni son quota.

Bonnes pratiques d'intégration

Mettez les données en cache localement.
Évitez le polling ; n'effectuez des requêtes que lorsque c'est nécessaire.
Utilisez les endpoints agrégés (détail du contenu, compatibility, issues, platforms).
Respectez Retry-After et les en-têtes RateLimit-*.
Ne faites pas de scraping HTML lorsque l'API fournit les données équivalentes.
Ne déduisez pas de bugs confirmés du moteur à partir des rapports de la communauté.
Conservez toujours la version d'openOMSI dans vos analyses.

À propos des données

Les rapports de la communauté sont des observations, pas une certification de compatibilité faisant autorité. Un seul rapport ne signifie ni "ce mod est compatible" ni "il s'agit d'un bug d'openOMSI". Tenez compte du nombre d'échantillons, de la version d'openOMSI, de la plateforme, du matériel, de la version du contenu, de la catégorie du problème et de la cohérence entre les rapports.

Confidentialité

Les réponses n'incluent jamais d'ID Discord, d'e-mails, d'adresses IP, de sessions, d'abonnements aux notifications, de données de modération ni d'identifiants d'appareil. Les rapports n'affichent que le nom public et le matériel que le testeur a choisi de publier. Dans un rapport, issue_categories est structuré tandis que issue_description est la description libre unique du testeur pour l'ensemble du rapport.

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