API pública

Acesso estruturado e somente leitura aos testes comunitários de compatibilidade de mapas, ônibus, veículos, mods, objetos, plugins e ferramentas rodando no openOMSI. Feita para desenvolvedores do openOMSI, ferramentas de análise, bots e integrações.

Esta NÃO é uma API para reportar bugs do openOMSI. Bugs da própria engine pertencem aos canais oficiais do projeto. Aqui você apenas consulta o que a comunidade testou.

⚠ LIMITE DA API PÚBLICA

6 requisições por IP a cada 60 minutos

Esta API é propositalmente muito limitada porque é pública e não exige autenticação.

Projete as integrações para guardar as respostas em cache local.
Não consulte a API continuamente (polling).
Use endpoints agregados sempre que possível: uma chamada responde à maioria das perguntas.

O limite é compartilhado por todos os endpoints públicos e vale só para consumidores externos; o próprio site não usa essa cota.

Começando

URL base: https://openomsi.omsimods.com.br/api/public/v1. Tudo é JSON, apenas GET, sem autenticação. Comece pelo endpoint meta para descobrir os valores exatos aceitos pelos 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)

Limite, cabeçalhos e erros

Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Ao estourar o limite, a API responde 429 com Retry-After (segundos).
Requisições condicionais (If-None-Match / If-Modified-Since) retornam 304 sem corpo, mas o 304 também consome cota.
Os erros sempre usam o formato {"error": código, "message": texto}; status 400, 404, 429 e 500. Nunca é devolvido stack trace.

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áticos

Os valores dos exemplos são ilustrativos; o formato das respostas é real.

1. O Grand Paris Moulon funciona no Windows?

Uma chamada devolve o resumo por plataforma, categorias de problema, distribuição de FPS, versões testadas e os relatórios mais recentes. Leia compatibility.by_platform.WINDOWS.

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

Resposta (resumida)

{
  "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 mapas testados no Android

Filtre por tipo e plataforma. Cada item já traz totais, plataformas testadas e a última versão do openOMSI testada.

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

Resposta (resumida)

{
  "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. Sou desenvolvedor do openOMSI e quero ver problemas de textura na versão atual

Filtre os relatórios por versão do openOMSI e categoria de problema. Cada relatório traz issue_categories estruturado e a descrição do testador.

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

Resposta (resumida)

{
  "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 possível regressão entre versões

compare mostra um conteúdo lado a lado em duas versões; regressions lista todo conteúdo que funcionava antes e agora relata problemas. O resultado é apenas possível regressão, nunca confirmada.

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

Resposta (resumida)

{
  "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 um bot do Discord

Busque pelo nome e monte a resposta com o primeiro item: nome, plataforma, resultado, última versão testada e número de relatórios. Guarde em cache do seu lado.

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

Resposta (resumida)

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

Resposta sugerida para o bot

Grand Paris Moulon
Windows
⚠ Funciona com problemas
Última versão testada: 0.1.126
Relatórios: 4

6. Quais problemas mais aparecem no Android?

O endpoint issues agrega categorias com número de relatórios e de conteúdos distintos; o endpoint de plataforma acrescenta os aparelhos mais reportados e o 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

Resposta (resumida)

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

7. Release atual e downloads

releases/latest devolve a versão, a data de publicação, a URL do GitHub e os arquivos oficiais de download por plataforma e arquitetura.

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

Resposta (resumida)

{
  "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 conteúdos que ainda não foram testados

has_reports=false lista conteúdos aprovados sem relatórios; combine com type ou q.

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

Resposta (resumida)

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

Endpoints

Todos os caminhos começam com https://openomsi.omsimods.com.br/api/public/v1. A descrição completa, legível por máquina, é o documento OpenAPI.

Endpoint	O que devolve
`GET /meta`	Taxonomias, limites e versão da API.
`GET /status`	Verificação operacional (também limitada: não use para polling).
`GET /content`	Busca de conteúdos com totais de relatórios, plataformas testadas e última versão testada por item.
`GET /content/{slug}`	Um conteúdo em uma só chamada: fontes, compatibilidade, problemas, desempenho, versões testadas, aparelhos e últimos relatórios.
`GET /reports`	Relatórios individuais com categorias de problema estruturadas, FPS, hardware e datas.
`GET /compatibility`	Agregado por versão do openOMSI, plataforma ou tipo de conteúdo.
`GET /compatibility/compare`	Um conteúdo comparado entre duas versões do openOMSI.
`GET /compatibility/regressions`	Possíveis regressões entre versões testadas consecutivas.
`GET /issues`	Categorias de problema ordenadas por relatórios e conteúdos afetados.
`GET /platforms/{platform}`	Agregado de uma plataforma (android, windows, linux, macos).
`GET /devices`	Hardware informado pelos testadores, agrupado e contado.
`GET /runtime-reports`	Testes de equipamento do próprio openOMSI (a sessão pode nunca ter começado): hardware, sistema, até onde chegou, API gráfica, texto de erro sanitizado e log sanitizado opcional. Sem conteúdo envolvido.
`GET /runtime-reports/{id}`	Um teste de equipamento, com o log sanitizado quando houver.
`GET /releases/latest`	Release atual e arquivos oficiais de download.
`GET /releases`	Histórico paginado de releases.

Os testes de equipamento nunca expõem o log original, IPs, e-mails, nomes de usuário nem identificadores de conta: só dados técnicos e o log sanitizado. São observações da comunidade, e não benchmark nem requisito oficial.

Filtros, paginação, ordenação e campos

Paginação: page (a partir de 1) e limit (padrão 20, máximo 50). As listas respondem {"data": [...], "pagination": {page, limit, total, pages}}.
Ordenação: sort = reports, recent, name, latest_test ou issues; order = asc ou desc.
O parâmetro opcional fields=name,slug,type mantém só esses campos de primeiro nível em cada item. A resposta padrão já é completa.
Filtros de enum não diferenciam maiúsculas de minúsculas e aceitam listas separadas por vírgula (platform=ANDROID,WINDOWS).
Quando filtros de relatório (platform, result, openomsi_version, issue_category) são usados na busca de conteúdos, as contagens se referem aos relatórios que correspondem.

Parâmetros

Parâmetro	Descrição
`q`	Busca de texto em nomes e apelidos dos conteúdos.
`type`	Tipo de conteúdo. Aceita lista separada por vírgulas.
`platform`	Plataforma do relatório. Aceita lista separada por vírgulas.
`result`	Resultado informado pelo testador. Aceita lista separada por vírgulas.
`openomsi_version`	Versão do openOMSI em que o teste foi feito.
`issue_category`	Categoria de problema ligada ao relatório (AUDIO é aceito como apelido de SOUND). Aceita lista separada por vírgulas.
`author`	Autor do conteúdo (correspondência parcial).
`has_reports`	true: só conteúdos testados; false: só conteúdos que ninguém testou ainda.
`sort`	Campo de ordenação.
`order`	Direção da ordenação.
`page`	Número da página, a partir de 1.
`limit`	Itens por página (máximo 50).
`fields`	Campos de primeiro nível, separados por vírgula, a manter em cada item (opcional; o padrão é o item completo).
`content`	Slug ou id do conteúdo (exato), ou parte do nome.
`architecture`	Arquitetura de CPU do relatório. Aceita lista separada por vírgulas.
`device`	Texto contido no nome do aparelho.
`has_fps`	Só relatórios com (true) ou sem (false) valor de FPS.
`from`	reports: testados a partir desta data ISO. compare/regressions: versão mais antiga do openOMSI.
`to`	reports: testados até esta data ISO. compare/regressions: versão mais nova do openOMSI.
`startup_stage`	Até onde o openOMSI chegou no equipamento. Aceita lista separada por vírgulas.
`graphics_backend`	API gráfica escolhida por quem testou. Aceita lista separada por vírgulas.
`gpu`	Texto contido no nome da GPU.
`cpu`	Texto contido no nome da CPU.
`manufacturer`	Fabricante do aparelho (busca parcial).
`device_model`	Modelo do aparelho (busca parcial).
`os_version`	Versão do sistema (busca parcial).
`media_indexing_observed`	Android: quem testou informou que a galeria ou o scanner de mídia estava indexando imagens do OMSI (true) ou não (false).
`has_log`	Somente testes com (true) ou sem (false) log sanitizado.
`include_log`	Inclui sanitized_log em cada item (padrão false: a lista só informa has_sanitized_log).

Enums / Taxonomias

Gerado a partir das listas da própria aplicação. AUDIO é aceito nos filtros como apelido de SOUND.

ContentType

ADDONMAPBUSVEHICLEMODSCENERYOBJECTSPLINEPLUGINTOOLOTHER

CompatibilityResult

WORKSWORKS_WITH_ISSUESDOES_NOT_WORKINCONCLUSIVE

Platform

ANDROIDWINDOWSLINUXMACOS

Architecture

X86X64ARM64UNKNOWN

IssueCategory

GRAPHICSTEXTURESPHYSICSSCRIPTSSOUNDCOLLISIONSPERFORMANCELOADINGCONTROLSMULTIPLAYERINTERFACECRASHOTHER

Dados de desempenho

FPS e tempos de carregamento são dados INFORMADOS PELOS USUÁRIOS, não um benchmark controlado. As estatísticas usam a mediana como principal e sempre trazem o tamanho da amostra (samples), além de mínimo e máximo.

Cache, CORS e versionamento

As respostas trazem Cache-Control, ETag e Last-Modified. Navegadores podem reaproveitá-las por alguns minutos; caches compartilhados precisam revalidar para a cota ser sempre aplicada.
O CORS é aberto apenas para GET, HEAD e OPTIONS. Não existem métodos de escrita.
A API é versionada no caminho (/api/public/v1). Os caminhos antigos sem versão redirecionam (308) para v1. Mudanças incompatíveis só serão publicadas como uma nova versão.
O site openOMSI Compatibility lê o próprio banco diretamente e nunca consome esta API nem a sua cota.

Boas práticas para integrações

Guarde os dados em cache local.
Evite polling; consulte só quando necessário.
Use endpoints agregados (detalhe do conteúdo, compatibility, issues, platforms).
Respeite o Retry-After e os cabeçalhos RateLimit-*.
Não faça scraping de HTML quando a API tem o dado equivalente.
Não conclua que há bug confirmado da engine a partir de relatórios da comunidade.
Mantenha sempre a versão do openOMSI nas suas análises.

Sobre os dados

Relatórios da comunidade são observações, não certificação oficial de compatibilidade. Um único relatório não significa "este mod é compatível" nem "isto é um bug do openOMSI". Considere a quantidade de amostras, a versão do openOMSI, a plataforma, o hardware, a versão do conteúdo, a categoria do problema e a consistência entre relatórios.

Privacidade

As respostas nunca incluem IDs do Discord, e-mails, endereços IP, sessões, inscrições de notificação, dados de moderação nem identificadores de dispositivo. Os relatórios mostram apenas o nome público e o hardware que o testador escolheu publicar. Em um relatório, issue_categories é estruturado, enquanto issue_description é a descrição livre única do testador para o relatório inteiro.

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