Quickstart da API

Passo 1

Crie uma chave no painel.

Crie uma conta pública, gere uma chave sk-rota-* e guarde o segredo como variável de ambiente. O segredo completo aparece uma única vez.

export ROTA_API_KEY="sk-rota-..."

Passo 2

Limpe um payload antes de qualquer destino.

Use /v1/privacy/clean para textos, JSON curto ou itens pequenos. A resposta traz cleaned, findings, contagens por categoria e audit_id, sem expor valores detectados.

curl https://rota-nacional.ia.br/v1/privacy/clean \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Paciente com CPF 452.198.736-28, CNS 898001160093761 e CRM-SP 123456.",
    "policy": "placeholder"
  }'

{
  "object": "privacy.clean",
  "action": "pseudonymized",
  "clean_text": "Paciente com CPF [CPF_1], [CNS_1] e [CRM_1].",
  "privacy": {
    "categories": ["cns", "cpf", "crm"],
    "counts": { "cns": 1, "cpf": 1, "crm": 1 },
    "total": 3
  },
  "audit_id": "aud_..."
}

Batch MVP

Envie lotes como jobs de privacidade.

O MVP processa o lote de forma síncrona e já retorna status: completed. O contrato está preparado para fila assíncrona e worker médico sem quebrar clientes.

curl https://rota-nacional.ia.br/v1/privacy/jobs \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "1", "text": "Prontuário ABC-123 com contato pessoa@example.invalid." },
      { "id": "2", "text": "Convênio SAUDE-4455 e consulta 09/07/2026." }
    ]
  }'

Depois consulte metadados do job, sem conteúdo bruto:

curl https://rota-nacional.ia.br/v1/privacy/jobs/privjob_... \
  -H "Authorization: Bearer $ROTA_API_KEY"

Áudio

Transcreva áudio e receba o texto já limpo.

Envie um arquivo de áudio (multipart, até 25 MB) para /v1/audio/transcriptions. A Rota transcreve, passa o texto pela mesma barreira de privacidade e devolve a transcrição já sanitizada, com privacy, findings e audit_id. O áudio bruto nunca é armazenado fora da auditoria cifrada. Contrato compatível com SDKs de transcrição OpenAI.

curl https://rota-nacional.ia.br/v1/audio/transcriptions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -F "file=@consulta.mp3" \
  -F "model=rota/transcricao" \
  -F "language=pt"

{
  "object": "audio.transcription",
  "text": "Paciente [PESSOA_1] no endereço [ENDERECO_1].",
  "privacy": { "categories": ["endereco", "nome"], "total": 2 },
  "audit_id": "aud_..."
}

Documentos

Extraia texto de PDF ou imagem — já limpo.

Envie um documento (multipart, até 25 MB) para /v1/privacy/extract. A Rota extrai o texto, aplica a barreira e devolve o resultado sanitizado com audit_id. PDF nato-digital tem extração determinística; imagem (PNG/JPEG/TIFF/WEBP) usa OCR marcado como beta — melhor-esforço, com notice na resposta. Documento ilegível falha com erro claro, sem devolver conteúdo bruto.

curl https://rota-nacional.ia.br/v1/privacy/extract \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -F "file=@encaminhamento.pdf"

{
  "object": "document.extraction",
  "source": "pdf",
  "pages": 2,
  "text": "Paciente com CPF [CPF_1] e [CNS_1].",
  "privacy": { "categories": ["cns", "cpf"], "total": 2 },
  "audit_id": "aud_..."
}

Inferência pela frota RN

Use uma API para texto, áudio, documentos e imagem.

A Rota escolhe o worker disponível; sua aplicação não recebe endereço de GPU nem precisa conhecer a topologia da frota. Consulte /v1/capabilities para descobrir o que os workers conectados podem executar naquele momento.

curl https://rota-nacional.ia.br/v1/capabilities \
  -H "Authorization: Bearer $ROTA_API_KEY"

Rotas assíncronas retornam 202, status_url e result_url. Consulte GET /v1/jobs/{id} e GET /v1/jobs/{id}/result. Payloads e resultados ficam cifrados e expiram automaticamente depois de 24 horas.

curl https://rota-nacional.ia.br/v1/audio/compositions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -F "voice=@narracao.mp3" \
  -F "background=@trilha.mp3" \
  -F "background_gain_db=-18"

Opcional

Liste modelos disponíveis.

curl https://rota-nacional.ia.br/v1/models \
  -H "Authorization: Bearer $ROTA_API_KEY"

IDs atuais do catálogo:

Inferência opcional

Use chat completion quando a Rota também for o destino de IA.

curl https://rota-nacional.ia.br/v1/chat/completions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rota/resumo",
    "messages": [
      { "role": "user", "content": "Explique a Rota Nacional em uma frase." }
    ],
    "max_tokens": 80
  }'

Usando o SDK OpenAI.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROTA_API_KEY,
  baseURL: "https://rota-nacional.ia.br/v1"
});

const resposta = await client.chat.completions.create({
  model: "rota/resumo",
  messages: [
    { role: "user", content: "ping" }
  ]
});

console.log(resposta.choices[0]?.message?.content);

Parâmetros

O que o corpo da requisição aceita.

Streaming

Receba SSE ponta a ponta.

curl -N https://rota-nacional.ia.br/v1/chat/completions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rota/resumo",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Responda em tópicos curtos." }
    ]
  }'

Tool calling

Defina ferramentas e receba chamadas estruturadas.

Envie tools no formato OpenAI (function com name, description e parameters em JSON Schema). O suporte real de execução depende do modelo escolhido — rota/agentes e rota/codigo são curados para esse uso; rota/auto direciona automaticamente pra rota/agentes quando detecta uso de ferramentas na conversa.

curl https://rota-nacional.ia.br/v1/chat/completions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rota/agentes",
    "max_tokens": 300,
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Retorna o clima de uma cidade",
        "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
      }
    }],
    "messages": [{ "role": "user", "content": "Qual o clima em Recife?" }]
  }'

Privacidade

PII vira marcador antes de seguir.

A política padrão substitui dados pessoais por marcadores por request. O painel mostra categorias e contagens tratadas; conteúdo bruto e payload limpo ficam em arquivo cifrado de auditoria quando a retenção está habilitada, com purge definido pela administração.

Categorias médicas básicas já entram na camada determinística: cns, crm, prontuario, convenio e data_clinica.

{
  "entrada": "Meu CPF é 452.198.736-28",
  "limpo": "Meu CPF é [CPF_1]"
}

Método e evidência

Conheça o detector antes de integrar.

O motor ativo rules-v1 aplica padrões textuais, checksum de CPF/CNPJ numérico e nomes configurados. Valores de texto em objetos e arrays são percorridos; chaves JSON e números não são tratados como strings. CNS e CRM usam contexto e formato, sem a mesma validação matemática.

O candidato neural da demonstração ainda não está ativo na API. Sua avaliação usa MiniLM, DistilBERT, ONNX e projeção Unicode. Os escores do detector não são garantia de anonimização.

Consulte a documentação de engenharia para conhecer os efeitos de cada política, o contrato de spans, os limites, o formato cifrado e as referências científicas. Os benchmarks e dados para download permitem recalcular precisão, recall e cobertura de nomes em 46 textos sintéticos.

Roadmap · ainda indisponível

Proteção local, agentes e integrações.

Extensão e aplicativo desktop, substituição contextual, restauração autorizada, ferramentas e proxy MCP, CLI, SDK, conectores empresariais, SSO e implantação dedicada estão planejados. Esses recursos ainda não têm contrato público de API nem data de lançamento.

As rotas documentadas acima continuam sendo o contrato disponível. A conexão de agentes pela API de inferência não equivale a um servidor MCP de privacidade. Consulte a apresentação da plataforma e seu roadmap ou baixe o PDF comercial.

Erros

Formato JSON estável: { "error": { "message", "type", "code" } }.