# KnotAPI — referência completa para modelos e agentes

Base URL: https://knotapi.online
Versão do contrato: v1
Formato: JSON UTF-8

## Autenticação

Envie a API Key no header `x-api-key`. Para MCP, também é aceito `Authorization: Bearer CHAVE`.
Nunca envie a chave em query string. Nunca exponha a chave no navegador.

### Onboarding obrigatório da API Key

`KNOT_API_KEY` é o nome recomendado da variável de ambiente; não é uma chave pronta e não é criada automaticamente pelo código.

Se o usuário ainda não tiver configurado a chave:
1. Oriente-o a entrar no portal KnotAPI, abrir a área de API Keys, criar uma chave para o projeto e guardar o valor completo quando ele for exibido.
2. Não invente uma chave e não peça que o segredo seja colado em chat, issue, commit ou mensagem pública.
3. Em desenvolvimento, use o arquivo de ambiente já suportado pelo projeto e confirme que ele está ignorado pelo Git. Adicione somente `KNOT_API_KEY=` ao arquivo de exemplo, quando existir.
4. Em produção, configure `KNOT_API_KEY` no secret manager ou painel de variáveis da hospedagem. Se o projeto não usa `.env`, respeite o mecanismo nativo de segredos.
5. A aplicação deve falhar de forma segura quando a variável estiver ausente, sem tentar uma chave padrão e sem revelar detalhes internos.

Uma IA deve explicar quais arquivos o usuário precisa editar e quais comandos deve executar para a stack detectada. Antes de alterar o projeto, deve inspecionar a autenticação, autorização, configuração, rate limit e testes existentes e preservá-los.

## Consultar CPF

GET /api?modulo=cpf&consulta=CPF

Parâmetros:
- modulo: deve ser `cpf`
- consulta: CPF brasileiro matematicamente válido, com 11 dígitos; pontuação é aceita e removida

Headers:
- x-api-key: obrigatório
- accept: application/json

Resposta 200:
{"sucesso":true,"dados":{"CPF":"12345678909","NOME":"NOME DO TITULAR","NASCIMENTO":"15-01-1990","MAE":"NOME DA MAE"},"meta":{"quota_remaining":998,"quota_reset":"05-09-2026 09:00:00","quota_reset_iso":"2026-09-05T12:00:00.000Z","timezone":"America/Sao_Paulo"}}

Códigos:
- 200: consulta processada
- 400 INVALID_CPF ou API_KEY_IN_QUERY_NOT_ALLOWED
- 401 API_KEY_REQUIRED ou API_KEY_INVALID
- 403 ACCOUNT_SUSPENDED, SUBSCRIPTION_INACTIVE, IP_NOT_ALLOWED ou ORIGIN_NOT_ALLOWED
- 404 CPF_NOT_FOUND
- 429 RATE_LIMITED ou QUOTA_EXHAUSTED
- 500 QUERY_FAILED
- 503 DATA_SOURCE_UNAVAILABLE

Headers de quota e velocidade:
- X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset
- RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After

## Segurança da integração

O navegador deve chamar uma rota do próprio projeto. Essa rota backend lê `KNOT_API_KEY` de uma variável de ambiente e chama a KnotAPI. Não use variáveis públicas como NEXT_PUBLIC_*, VITE_* ou REACT_APP_* para a chave. CORS e restrição por domínio não tornam um segredo exposto seguro. Prefira uma chave por ambiente e IP fixo quando disponível.

Normalize o CPF e valide também os dígitos verificadores antes da chamada. Aplique timeout de conexão e resposta. Trate timeout/conexão e 400, 401, 403, 404, 429, 500 e 503. Não confunda 401/403 da KnotAPI com a sessão local do usuário. Preserve `Retry-After` em 429; retry deve ser limitado a GET idempotente, falhas de conexão ou 5xx, nunca 400/401/403/404.

Testes de integração devem usar o mock HTTP nativo da stack e nunca chamar a KnotAPI real. Cubra configuração ausente, rota sem autenticação, CPF inválido, sucesso, erros documentados, `Retry-After` e timeout com uma chave fictícia somente no ambiente de teste.

## MCP

Endpoint: POST https://knotapi.online/mcp
Transport: Streamable HTTP stateless com resposta application/json
Autenticação: Authorization Bearer ou x-api-key
Protocol version: 2025-11-25
Capabilities: tools
Tool: consultar_cpf
Input: {"cpf":"12345678909"}
Efeito: somente leitura; consome uma requisição da franquia

Métodos suportados: initialize, ping, tools/list, tools/call e notifications/initialized.

## Agent Skill

Arquivo: https://knotapi.online/skills/knotapi/SKILL.md
Referência: https://knotapi.online/skills/knotapi/references/API.md
Script opcional: https://knotapi.online/skills/knotapi/scripts/consult-cpf.js

## Privacidade

CPF e dados cadastrais são dados pessoais. Consulte apenas com base legal e finalidade legítima, minimize retenção, restrinja acesso, registre auditoria e não use o resultado para decisão automatizada discriminatória. A integração técnica não concede base legal por si só.