API quickstart

Step 1

Create a key in the dashboard.

Create an account, generate a key mmk_… and store the secret in an environment variable. The full secret is shown only once.

export ROTA_API_KEY="mmk_..."

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"

/v1/chat/completions

Chat through a worker using model: "rota/local". stream: true returns SSE after the job completes; in the MVP, content arrives in a single chunk.

/v1/embeddings

Text vectors through a worker advertising rn.embeddings.

/v1/audio/speech

Speech synthesis and voice cloning. Send JSON with text, with optional voice and engine.

/v1/audio/music

Background music generation through an asynchronous job, with controllable style, duration and seed.

/v1/audio/compositions

Mix voice and background audio. Send multipart with voice and background.

/v1/ocr

Local image or PDF OCR, with the result processed again by the privacy barrier.

/v1/documents/fidelity/jobs

Asynchronous document OCR for workflows that need to preserve structure and pages.

/v1/documents/review/jobs

Structured document review through a job, with instructions and a JSON Schema for the result.

/v1/moderations

Messages checked against the organization policy, with the score of each category.

/v1/images/generations and /v1/images/edits

Image generation and editing through asynchronous jobs when rn.images.* is available.

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.

The balance is the house credit: the cred_ code bought in any of our products also pays here, sent in Authorization: Bearer or in X-Credito; what is left stays in it.

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.

Try it free in the lab

Optional

List available models.

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

Current catalog IDs:

• rota/resumo
• rota/analise
• rota/codigo
• rota/agentes
• rota/rapido
• rota/raciocinio
• rota/instrucao
• rota/contexto-longo
• rota/local
• rota/auto

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

Compare models and connect your application.

In API → Tools, send a prompt to one or two models. Check the response, time and tokens. Each model uses one call from the organization's quota or credit.

In Connect an application, copy a curl, JavaScript, Python or JSON example. Set ROTA_API_KEY to an account key. The example uses the current environment's URL.

Open tools

In administration, check provider keys, balance and models. Add routes, set organization permissions and select a routing strategy. Failover uses only authorized routes with the same customer price.

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.

model

Required. Catalog ID (rota/codigo, rota/auto etc.).

messages

Required. Non-empty list of { role, content }, roles system/user/assistant/tool.

max_tokens

Optional. Output token limit.

temperature

Optional. Response randomness.

stream

Optional. true for SSE (see Streaming).

tools / tool_choice

Optional. See Tool calling below.

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

400

invalid_json, missing_privacy_input, model_not_found or invalid_messages — malformed request.

401

invalid_api_key — missing or invalid key.

402

insufficient_balance — the balance does not cover the call to an rn.*capability; the body carries the accepts list for x402 and where to buy credit.

403 · model

model_disabled — model disabled for this account.

403 · account

account_suspended, trial_expired or account_pending_approval — account access has not been enabled.

404

not_found — route not found.

413

privacy_text_too_large — text above 256 KB per request for name detection.

422

pii_blocked — organization policy blocked the sensitive payload.

429

rate_limited, quota_requests_exceeded or quota_tokens_exceeded — per-minute or monthly limit.

502

upstream_error — model request failed.

503

audit_archive_key_not_configured — auditing temporarily unavailable (administrative configuration).

503 · worker

capability_unavailable — no worker serves the capability right now; nothing was charged.

503 · names

person_engine_unavailable or person_engine_daily_limit — name detection unavailable; nothing was forwarded.