# Desenvolvedores · API e MCP

A API pública de conteúdo da Uranus Technologies. Somente leitura, sem autenticação, sem cadastro. A mesma superfície é exposta como servidor MCP para agentes chamarem direto.

- Base da API: https://uranus.com.br/api/v1
- Especificação OpenAPI 3.1: https://uranus.com.br/openapi.json
- Servidor MCP (Streamable HTTP, POST): https://uranus.com.br/mcp
- Verificação de saúde: https://uranus.com.br/healthz

## Endpoints

| Método | Caminho | Descrição |
|--------|---------|-----------|
| GET | /api/v1 | Índice da API, com link para a especificação e o endpoint MCP |
| GET | /api/v1/health | Verificação de saúde |
| GET | /api/v1/company | Razão social, CNPJ, endereço, contatos e perfis oficiais |
| GET | /api/v1/products | Todos os produtos, com status e links |
| GET | /api/v1/products/{slug} | Um produto, com o corpo em markdown |
| GET | /api/v1/posts | Artigos publicados; filtra por category e locale |
| GET | /api/v1/posts/{slug} | Um artigo, com metadados e corpo em markdown |
| GET | /api/v1/pages | Páginas institucionais disponíveis em markdown |
| GET | /api/v1/pages/{slug} | Uma página, em markdown |
| GET | /api/v1/search?q= | Busca em produtos, páginas e artigos |
| POST | /mcp | Servidor MCP, JSON-RPC 2.0 sobre Streamable HTTP |

## Erros

Falhas respondem `application/problem+json` (RFC 9457) com `code`, `detail` e `hint`. Nenhum caminho sob /api devolve HTML, inclusive os que nenhum recurso atende.

## Limites de uso

600 requisições por 60 segundos, por endereço de origem. Toda resposta traz `RateLimit`, `RateLimit-Policy` e o trio `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`. Ao estourar: `429` com `Retry-After`.

## Versionamento e depreciação

A versão fica no caminho da URL (`/api/v1`). Mudança que quebra contrato vira caminho novo; o antigo continua respondendo. Uma versão que vai sair é anunciada com no mínimo 180 dias de antecedência, e a partir do anúncio toda resposta dela carrega `Deprecation` (RFC 9745), `Sunset` (RFC 8594) e `Link` com `rel="deprecation"` e `rel="successor-version"`. A política também está em JSON, no bloco `versioning` de `GET /api/v1`.

## Autenticação

Não há. Nenhum recurso exige token, e isso está declarado em formato legível por máquina: https://uranus.com.br/.well-known/oauth-protected-resource (RFC 9728), https://uranus.com.br/.well-known/oauth-authorization-server (RFC 8414, com o bloco `agent_auth`) e https://uranus.com.br/auth.md em prosa.

## Markdown

Qualquer rota do site responde markdown quando a requisição envia `Accept: text/markdown`. Os mesmos arquivos ficam sob `/md/`, com os espelhos em inglês sob `/md/en/`. As respostas trazem `Vary: Accept, Accept-Encoding`.

Versão em HTML: https://uranus.com.br/developers