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

Inference through the RN fleet

Use one API for text, audio, documents and images.

Rota selects an available worker; your application never receives a GPU address or needs to know the fleet topology. Check /v1/capabilities to discover what connected workers can run at that time.

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

Asynchronous routes return 202, status_url and result_url. Check GET /v1/jobs/{id} and GET /v1/jobs/{id}/result. Payloads and results remain encrypted and expire automatically after 24 hours.

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"

Policy moderation

Apply your company policy to each message.

Write up to 16 categories in plain text: the name, when to flag and, if you want, what does not count and the exception. Each message comes back with the decision and a score from 0 to 1 for each category. To change the policy, change the text: there is no model to train. Without a policy, the general safety rules apply, such as violence, hate and fraud.

curl https://rota-nacional.ia.br/v1/moderations \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["Sua conta foi bloqueada. Faça um Pix de R$ 1 para liberar."],
    "categories": [{
      "name": "Golpe",
      "violation": "Pedir Pix ou código fingindo ser o banco.",
      "not_violation": "Dúvida comum sobre pagamento ou boleto."
    }]
  }'

{
  "object": "moderation",
  "model": "rota/moderacao",
  "mode": "policy",
  "results": [{
    "flagged": true,
    "score": 0.97,
    "cutoff": 0.335,
    "categories": { "Golpe": true },
    "category_scores": { "Golpe": 0.97 },
    "category_cutoffs": { "Golpe": 0.335 }
  }]
}

The format is the OpenAI moderation format, and the policy goes in the extra field categories. The barrier removes the personal data before the model, and the response does not repeat the text. The score is an estimate: test the policy with real messages before you block a person. The first message after a pause takes a few seconds more, because the model starts at that time.

Pricing

Pay in reais, per use, only for what the API delivers.

Each call to the rn.* capabilities with an API key pays for its units from the organization balance. The balance comes in by Pix in the dashboard, in packages of R$ 10, R$ 25, R$ 50 or R$ 100. Without balance, a call can pay for itself by x402: send X-PAYMENT with USDC on Base, from US$ 0.001 per call. The dashboard lab stays free, with a daily usage limit.

Without balance or payment, the response is 402, with the accepts list for x402, the preco_brl and the buy_credit_url. The balance charge comes back if the job fails, is cancelled or expires in the queue. OCR reserves the maximum number of pages (max_pages, default 40) and returns the pages it did not read. An x402 payment covers the accepted call and is not refunded automatically.

Without a key or an account, the API also accepts x402: a paid route answers 402 with the price and the accepts, and you repeat the request with X-PAYMENT. The wallet that pays becomes your account here: usage, jobs and the balance left over stay in it. To use that balance, send X-Carteira with the address; the 402 asks only for the difference. In chat, the price is the request ceiling (max_tokens, default 1,024), and what is left stays in the wallet. An async job is followed with the token in the URLs of the 202.

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.

Person names first go through the neural engine rn-privacy-0.2.0, which runs in São Paulo and returns only positions. Then rules-v1 applies text patterns and numeric CPF/CNPJ checksums. 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 engine uses MiniLM, DistilBERT, ONNX and Unicode projection. If it is unavailable, the request fails with 503 and nothing is forwarded; texts above 256 KB receive 413. Detector scores are not a guarantee of 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" } }.