CPSP-PMDF · API pública · Vercel
Recursos para desenvolvedores e agentes
O CPSP-PMDF é uma aplicação Next.js hospedada na Vercel. Esta página concentra a superfície técnica pública destinada a mecanismos de busca, agentes de inteligência artificial e integrações que precisam identificar o produto programaticamente. A documentação é intencionalmente restrita a dados públicos: endpoints autenticados, estruturas internas de banco, credenciais, permissões e operações administrativas não são publicados como API.
A API REST pública utiliza versionamento por caminho em /api/v1. Ela oferece somente leituras de identidade, recursos de descoberta e políticas de compatibilidade. O contrato completo está em /openapi.json, com operationId único, parâmetros e respostas tipados para uso por clientes tradicionais e ferramentas de function calling.
Clientes HTTP também podem solicitar Accept: text/markdown em páginas públicas negociáveis. O servidor MCP em /.well-known/mcp usa Streamable HTTP sem estado e implementa o protocolo 2026-07-28; o Server Card de descoberta é publicado separadamente e não concede qualquer acesso adicional às áreas protegidas.
API REST pública v1
O ponto de entrada é /api/v1. Os recursos estáveis são /api/v1/site, /api/v1/resources e /api/v1/policies. Todos são somente leitura e retornam JSON. Uma rota desconhecida sob /api/v1 retorna HTTP 404 estruturado, nunca uma página HTML da aplicação.
Erros estruturados
Erros da API REST seguem RFC 9457 e usam Content-Type: application/problem+json. Além dos campos padronizados type, title, status, detail e instance, o CPSP-PMDF publica code para tratamento determinístico e hint com uma orientação de resolução. Códigos públicos incluem RESOURCE_NOT_FOUND, METHOD_NOT_ALLOWED, NOT_ACCEPTABLE, RATE_LIMIT_EXCEEDED e INTERNAL_ERROR.
Versionamento e depreciação
Alterações incompatíveis exigem uma nova versão principal no caminho, como /api/v2. Adições retrocompatíveis podem permanecer em v1. Toda resposta inclui API-Version: 1.
A versão v1 não está depreciada. Quando uma versão entrar em depreciação, o CPSP-PMDF usará o header Deprecation conforme RFC 9745; havendo data definida de retirada, também enviará Sunset conforme RFC 8594. A política padrão prevê ao menos 90 dias entre aviso e retirada, exceto quando uma exigência urgente de segurança, privacidade ou legalidade tornar necessária uma remoção mais rápida.
Rate limits
A API pública adota uma cota de referência de 60 requisições por minuto por identificador de cliente. As respostas informam RateLimit-Policy e RateLimit, além dos campos de compatibilidade RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Quando a cota é excedida, a resposta é HTTP 429 em application/problem+json e inclui Retry-After.
MCP e descoberta
O transporte MCP permanece em /.well-known/mcp. O documento /.well-known/mcp/server-card.json segue o formato experimental de MCP Server Card acompanhado pelo SEP-2127 e descreve somente identidade e conexão. Ferramentas, capacidades e resultados efetivos continuam sujeitos ao protocolo MCP em tempo de execução.
Índice técnico público
- REST API v1
API pública versionada, somente leitura, com respostas JSON tipadas.
- OpenAPI 3.1
contrato tipado da API REST pública do CPSP-PMDF.
- llms.txt
instruções de descoberta e quando usar o CPSP-PMDF.
- MCP
endpoint Streamable HTTP público, sem estado e informativo.
- MCP Server Card
cartão experimental SEP-2127 para descoberta do servidor MCP.
- sitemap.xml
URLs públicas indexáveis.
- robots.txt
orientação de rastreamento e áreas restritas.
- Markdown
representação Markdown da página inicial por URL explícita.
Limite de integração
A API, o OpenAPI e o MCP publicados aqui não concedem acesso aos módulos SAD, SPOI, DEGC, CPTED ou a qualquer outra área autenticada. Para um agente, ausência de uma operação na documentação pública significa que ela não está disponível como integração pública. Esse comportamento preserva as regras de autenticação, autorização e escopo já existentes no produto.