L2 MOG API — Documentação para desenvolvedores

Esta página descreve o contrato da API pública do L2 MOG: Base URL, autenticação, versionamento, deprecação, limites de requisição e formato de erros.

Base URL

https://api.l2mog.com/api/v1 — o prefixo /api/ sem número de versão é mantido como alias.

Especificação OpenAPI

A especificação completa (OpenAPI) fica disponível em https://l2mog.com/openapi.json e também em https://api.l2mog.com/openapi.json.

Autenticação

Os seguintes endpoints são públicos, sem autenticação:

/api/v1/server/status
/api/v1/home/*
/api/v1/news/*
/api/v1/players/*
/api/v1/clans/*
/api/v1/castles/*
/api/v1/events/*
/api/v1/raidbosses/*
/api/v1/pvp/status
/api/v1/pvp/ranking*

Endpoints privados exigem login via POST /api/v1/auth/login, que retorna um JWT a ser enviado no cabeçalho Authorization: Bearer <jwt> nas requisições seguintes.

Versionamento

A API é versionada por caminho: /api/v{n}. Toda resposta inclui o cabeçalho API-Version indicando a versão efetivamente atendida. O cliente pode opcionalmente enviar o cabeçalho de requisição API-Version para pedir uma versão específica; se a versão pedida não existir, a resposta é 400 com o código UNSUPPORTED_API_VERSION.

Política de deprecação

Endpoints deprecados recebem um aviso mínimo de 90 dias antes da remoção, sinalizado por três cabeçalhos de resposta:

Deprecation (RFC 9745)
Sunset (RFC 8594)
Link com rel="deprecation"

Endpoints deprecados: nenhum no momento.

A política completa (versionamento, o que conta como mudança incompatível e o changelog de deprecações) está em /deprecation-policy.

Limites de requisição (rate limits)

O limite padrão é de 600 requisições por minuto por IP. As respostas incluem os cabeçalhos padronizados:

RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=598;t=57

Por compatibilidade, também são enviados os cabeçalhos legados RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Ao exceder o limite, a API responde 429 com o cabeçalho Retry-After.

Erros

Erros são retornados como JSON no formato ApiError:

{
  "timestamp": "2026-09-06T12:00:00Z",
  "status": 400,
  "code": "UNSUPPORTED_API_VERSION",
  "message": "A versão de API solicitada não é suportada.",
  "hint": "Use /api/v1 ou omita o cabeçalho API-Version.",
  "path": "/api/v1/server/status",
  "fields": null
}

Códigos estáveis de code (o schema ApiError do OpenAPI é a referência):

code	status	quando
`UNAUTHORIZED`	401	sem JWT válido em rota protegida
`FORBIDDEN`	403	autenticado sem permissão
`NOT_FOUND`	404	rota ou recurso inexistente
`METHOD_NOT_ALLOWED`	405	método HTTP não suportado
`BAD_REQUEST`	400	corpo ilegível, parâmetro faltando ou tipo errado
`UNSUPPORTED_API_VERSION`	400	header API-Version com versão inexistente
`NOT_ACCEPTABLE`	406	Accept não atendido
`UNSUPPORTED_MEDIA_TYPE`	415	Content-Type não suportado
`RATE_LIMITED`	429	limite de requisições excedido; ver Retry-After
`INSUFFICIENT_BALANCE`	400	saldo insuficiente na loja
`CHAR_ONLINE`	406	operação exige personagem offline
`INVENTORY_ITEM_NOT_FOUND`	410	item não está mais no inventário
`SERVER_ERROR`	500	erro interno

O campo fields é opcional e só aparece em erros de validação, com o detalhe por campo. O código UNSUPPORTED_API_VERSION (status 400) é retornado quando o cabeçalho API-Version pede uma versão inexistente. A lista completa de códigos de erro por endpoint está no schema ApiError da especificação OpenAPI (/openapi.json).

Conteúdo para agentes

Além do JSON da API, as páginas do site respondem em Markdown puro para clientes que enviam Accept: text/markdown na mesma URL (sem sufixo). Veja também /llms.txt e /agents.md para um guia estruturado voltado a agentes e LLMs, e /.well-known/api-catalog (RFC 9727) para o catálogo de APIs em linkset.

Exemplos

curl https://api.l2mog.com/api/v1/server/status

curl https://api.l2mog.com/api/v1/pvp/status

curl -X POST https://api.l2mog.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"seu_login","password":"sua_senha"}'

English summary

The L2 MOG public API is versioned by path (/api/v{n}, base URL https://api.l2mog.com/api/v1, unversioned /api/ kept as an alias) and documented via OpenAPI at /openapi.json. Public endpoints need no auth; private ones use a JWT obtained from POST /api/v1/auth/login. Responses carry an API-Version header; deprecated endpoints get at least 90 days notice via Deprecation, Sunset and Link rel="deprecation" headers. The default rate limit is 600 requests/minute per IP (RateLimit-Policy/RateLimit headers, plus legacy RateLimit-Limit/Remaining/Reset; 429 with Retry-After when exceeded). Errors use a JSON ApiError shape with a stable code field.