API quickstart

Step 1

Create a key in the dashboard.

Create an account, generate a key sk-rota-* and store the secret in an environment variable. The full secret is shown only once.

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

Step 2

Sanitize a payload before sending it anywhere.

Use /v1/privacy/clean for text, short JSON or small items. The response includes cleaned, findings, category counts and audit_id, without exposing detected values.

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

Submit batches as privacy jobs.

The MVP processes batches synchronously and returns status: completed. The contract is prepared for an asynchronous queue and a medical worker without breaking clients.

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." }
    ]
  }'

Then retrieve job metadata, without raw content:

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

Audio

Transcribe audio and receive sanitized text.

Send an audio file (multipart, up to 25 MB) to /v1/audio/transcriptions. Rota transcribes it, applies the same privacy barrier and returns the transcript already sanitized, with privacy, findings and audit_id. Raw audio is never stored outside the encrypted audit archive. Compatible with OpenAI transcription SDKs.

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_..."
}

Documents

Extract text from PDFs or images, already sanitized.

Send a document (multipart, up to 25 MB) to /v1/privacy/extract. Rota extracts the text, applies the privacy barrier and returns the result sanitized with audit_id. Digital PDFs use deterministic extraction; images (PNG/JPEG/TIFF/WEBP) use OCR marked as beta — best effort, with notice in the response. Unreadable documents fail with a clear error, without returning raw content.

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_..."
}

Optional

List available models.

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

Current catalog IDs:

Optional inference

Use chat completion when Rota Nacional is also your AI destination.

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
  }'

Using the OpenAI SDK.

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);

Parameters

What the request body accepts.

Streaming

Receive end-to-end SSE.

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

Define tools and receive structured calls.

Send tools in OpenAI format (function with name, description and parameters in JSON Schema). Execution support depends on the selected model — rota/agentes and rota/codigo are curated for this use; rota/auto automatically routes to rota/agentes when it detects tool use in the conversation.

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?" }]
  }'

Privacy

PII becomes a placeholder before proceeding.

The default policy replaces personal data with request-scoped placeholders. The dashboard displays processed categories and counts; raw content and sanitized payloads are held in encrypted audit archives when retention is enabled, with an administrator-defined purge policy.

Basic medical categories are already part of the deterministic layer: cns, crm, prontuario, convenio and data_clinica.

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

Method and evidence

Understand the detector before integrating.

The active engine rules-v1 applies text patterns, numeric CPF/CNPJ checksums and configured names. Text values in objects and arrays are traversed; JSON keys and numbers are not treated as strings. CNS and CRM use context and format, without the same mathematical validation.

The demo's neural candidate is not yet active in the API. Its evaluation uses MiniLM, DistilBERT, ONNX and Unicode projection. Detector scores do not guarantee anonymization.

See the engineering documentation for the effects of each policy, the span contract, limits, encryption format and scientific references. The benchmarks and downloadable data let you recalculate precision, recall and name coverage across 46 synthetic texts.

Roadmap · not yet available

Device protection, agents and integrations.

Browser extensions and desktop apps, contextual substitution, authorized restoration, MCP tools and proxy, CLI, SDK, enterprise connectors, SSO and dedicated deployment are planned. These features do not yet have a public API contract or a launch date.

The routes documented above remain the available API contract. Connecting agents through the inference API is different from a privacy MCP server. See the platform overview and roadmap or download the Product PDF.

Errors

Stable JSON format: { "error": { "message", "type", "code" } }.