Documentação da API

A API do Regunow usa HTTPS, autenticação Bearer e o prefixo versionado /api/v1. Você pode consultar esta documentação sem uma conta. As solicitações à API exigem acesso Pro ativo e aceitação das políticas vigentes.

1. Entre no Regunow e crie uma chave em Configurações → Chaves de API.
2. Guarde o segredo com segurança. Ele é exibido apenas uma vez, ao criar a chave.
3. Configure o host e a chave e envie sua primeira pergunta por um backend ou uma automação confiável.

# Use your Regunow host and a key from Settings → API Keys.
export REGUNOW_BASE_URL="https://YOUR_REGUNOW_HOST"
export REGUNOW_API_KEY="YOUR_API_KEY"

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-question-001" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Which EU product-safety obligations apply to a connected consumer device?"
    }],
    "mode": "jurisdiction",
    "jurisdiction": "eu"
  }'

A resposta está em output.content. As referências às fontes e os créditos cobrados estão incluídos. Esta solicitação consome créditos. Use uma nova chave de idempotência para cada nova pergunta.

// Node.js: set REGUNOW_BASE_URL and REGUNOW_API_KEY in your environment.
// Generate one key per operation; keep it unchanged when retrying that operation.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
const response = await fetch(
  process.env.REGUNOW_BASE_URL + "/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.REGUNOW_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Summarize EU product-safety obligations." }],
      mode: "jurisdiction",
      jurisdiction: "eu",
    }),
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.code + ": " + result.error.message);
}
console.log(result.output.content);

Envie a chave de API no cabeçalho HTTP Authorization de cada solicitação. Chaves em URLs, cookies ou corpos de solicitação não são aceitas.

Authorization: Bearer rgn_live_...

Armazene as chaves em uma variável de ambiente ou em um gerenciador de segredos. Não as inclua em código do navegador, pacotes de aplicativos móveis, repositórios públicos ou logs. O acesso por navegadores de outras origens não está habilitado; envie as solicitações pelo seu servidor.

Chaves desativadas, excluídas ou expiradas deixam de autenticar imediatamente. O Regunow armazena apenas um hash do segredo e não pode exibi-lo novamente. Crie uma chave substituta quando precisar.

O acesso Pro e a aceitação das políticas são verificados em cada solicitação. Se receber legal_acceptance_required, o titular da chave deve entrar e abrir Aceitação legal. Uma chave de API não pode aceitar políticas.

GET/api/v1/models

Consulte modelos, níveis de esforço, jurisdições, idiomas de resposta e recursos disponíveis. Este endpoint autenticado não cobra créditos separadamente e permite verificar uma chave antes de solicitar uma resposta de chat.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Use os valores retornados pelo catálogo da sua implantação. No modo Jurisdição, omita model e effort para usar os padrões aceitos. Se os informar, devem corresponder a Sonnet 4.6 / Alto. Sem anexos, o serviço de recuperação gerencia o modelo de resposta; o campo de modelo descreve a seleção validada.

POST/api/v1/chat/completions

Envie um corpo JSON contendo um array messages. Por padrão, a API retorna a resposta completa em JSON. Defina stream como true para receber texto incrementalmente.

{
  "messages": [{
    "role": "user",
    "content": "What retention period does this policy specify? Cite the document."
  }],
  "mode": "freestyle",
  "web_search": "off",
  "response_language": "en",
  "file_ids": ["YOUR_FILE_ID"]
}

Substitua YOUR_FILE_ID pelo UUID retornado após um envio bem-sucedido. Em cada pergunta seguinte, envie o histórico relevante do usuário e do assistente e inclua novamente os file_ids desejados. A API não memoriza automaticamente o histórico nem os anexos.

Mensagens de sistema e campos desconhecidos são rejeitados. A API não oferece geração de imagens ou relatórios, entrada de áudio nem acesso a memórias salvas. Imagens enviadas podem ser usadas como entrada para perguntas.

Uma solicitação bem-sucedida retorna object: "regunow.chat.completion", a resposta, metadados das fontes, uso e tempos. Os valores a seguir são ilustrativos.

{
  "id": "request-uuid",
  "request_id": "request-uuid",
  "object": "regunow.chat.completion",
  "created": 1790812800,
  "model": "jp.anthropic.claude-sonnet-4-6",
  "latency": {
    "time_to_first_token_ms": 2345,
    "time_to_answer_completion_ms": 9876
  },
  "output": {
    "input_files": [],
    "role": "assistant",
    "content": "The complete answer...",
    "finish_reason": "end_turn",
    "citations": [],
    "sources": [],
    "web_search": false
  },
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 456,
    "charged_microcredits": 789000,
    "charged_credits": 0.789
  }
}

• output.content contém o texto definitivo da resposta. As posições das citações se referem a essa string final; sourceIndexes identifica entradas em output.sources.
• As fontes incluem título, nome do arquivo, tipo MIME, URI e trecho recuperado. Exiba trechos e citações junto da resposta.
• Uma URI de fonte indica uma localização e pode apontar para armazenamento privado. Somente URLs públicas dos editores devem ser apresentadas como links acessíveis. A API não oferece download nem tradução de arquivos de fontes regulatórias.
• Com anexos, output.input_files identifica os arquivos fornecidos. Fontes de anexos têm file_id; fontes regulatórias e da web têm file_id: null. As URIs dos anexos são null.
• A presença de um arquivo de entrada não prova que ele sustente todas as afirmações. Modelos podem omitir citações no texto; imagens ou digitalizações podem ter trechos vazios.

As contagens de tokens podem ser null quando o serviço de recuperação não as informa; isso significa desconhecido, não zero. charged_credits é a cobrança registrada ao cliente. created é um timestamp Unix em segundos; as latências são em milissegundos.

Toda resposta dos endpoints contém um cabeçalho X-Request-Id. Guarde o identificador para diagnóstico. O JSON das respostas de chat e erros também contém request_id.

Defina "stream": true. A resposta usa text/event-stream. Com cURL, adicione -N para desativar o buffer de saída.

curl --fail-with-body -N \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: streaming-question-001" \
  -d '{
    "messages": [{"role":"user","content":"Summarize EU product-safety obligations."}],
    "mode": "jurisdiction",
    "jurisdiction": "eu",
    "stream": true
  }'

Leia eventos SSE completos separados por linhas em branco; um bloco de rede pode conter parte de um evento ou vários eventos. Acrescente choices[0].delta.content conforme chegar. Ignore os comentários de manutenção da conexão que começam com :.

data: {"choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"The answer begins..."},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":1234,"completion_tokens":456,"total_tokens":1690},"regunow":{"output":{},"latency":{},"usage":{"charged_credits":0.789,"charged_microcredits":789000}}}

data: [DONE]

O evento final de metadados tem um array choices vazio. Leia resposta definitiva, citações e fontes em regunow.output, tempos em regunow.latency e créditos em regunow.usage. As contagens de tokens usam usage.prompt_tokens e usage.completion_tokens.

A recuperação e o processamento de citações podem causar pausas. Trate o texto como provisório até os metadados finais. Um erro após o início da transmissão chega como um objeto error seguido de [DONE]; HTTP 200 sozinho não confirma sucesso. Falhas anteriores de autenticação ou validação retornam erros JSON comuns.

A repetição de uma operação concluída continua em SSE e retorna a resposta salva em um único bloco de texto com X-Idempotent-Replayed: true.

Envie documentos ou imagens e anexe seus IDs a uma solicitação de chat. Os arquivos compartilham a Biblioteca e a cota de armazenamento do titular da chave. Documentos podem ter até 10 MiB e imagens até 5 MiB.

Envio direto (recomendado)

Este fluxo de três etapas envia os bytes originais diretamente ao armazenamento, evitando os limites do corpo de solicitação da aplicação. Use-o em integrações hospedadas, especialmente com arquivos maiores.

POST/api/v1/files/upload-intents

Envie apenas name, mime_type e bytes (o tamanho exato). Uma solicitação bem-sucedida retorna HTTP 201 com o ID de um arquivo pendente e uma URL assinada válida por 300 segundos.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/upload-intents" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-intent-001" \
  -d '{"name":"policy.txt","mime_type":"text/plain","bytes":16384}'

{
  "id": "YOUR_FILE_ID",
  "status": "pending",
  "upload_method": "PUT",
  "upload_url": "SIGNED_UPLOAD_URL",
  "upload_headers": {"Content-Type": "text/plain"},
  "expires_in": 300
}

Defina FILE_ID com o id retornado. Use os upload_method, upload_url e upload_headers recebidos para enviar os bytes originais exatos. Defina a Content-Length exata. Não envie a chave de API do Regunow à URL de envio nem registre URLs assinadas nos logs.

# Set UPLOAD_URL from the intent response. Use its returned upload_headers.
# This example assumes policy.txt is exactly 16,384 bytes.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -H "Content-Length: 16384" \
  --data-binary @./policy.txt

POST/api/v1/files/{fileId}/complete

Envie {} com uma chave de idempotência diferente. A finalização valida os bytes e retorna HTTP 200 com um arquivo disponível. O ID só pode ser usado em file_ids após a conclusão bem-sucedida.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-complete-001" \
  -d '{}'

Se a URL expirar, exclua o arquivo pendente não utilizado e prepare outro envio com uma nova chave. Repetir a preparação não prolonga a validade da URL. Se o resultado da finalização for incerto, consulte primeiro o estado do arquivo. Se ainda estiver pendente, tente finalizar com uma nova chave de idempotência; a antiga retorna seu resultado salvo. Finalizar um arquivo já disponível retorna seus metadados.

Envio multipart

POST/api/v1/files

Para arquivos menores, envie um campo multipart/form-data chamado file. Envie bytes originais, não base64 nem uma URL remota. Seu gateway de hospedagem pode impor um limite de corpo menor que o tamanho de arquivo permitido pela API.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Idempotency-Key: policy-upload-001" \
  -F "file=@./policy.pdf;type=application/pdf"

Um envio bem-sucedido retorna HTTP 201 com um arquivo disponível; não é necessária uma chamada de finalização separada.

{
  "id": "YOUR_FILE_ID",
  "object": "regunow.file",
  "name": "policy.pdf",
  "mime_type": "application/pdf",
  "category": "file",
  "bytes": 16384,
  "status": "available",
  "created_at": "2026-10-01T00:00:00Z",
  "request_id": "request-uuid",
  "usage": {"charged_microcredits":500,"charged_credits":0.0005}
}

Listar, consultar e excluir arquivos

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files?limit=20" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Chaves da mesma conta acessam os arquivos disponíveis da sua Biblioteca. Arquivos inexistentes e de outras contas retornam 404. Se atender vários usuários por uma conta, aplique suas próprias permissões antes de anexar ou excluir arquivos.

Envios pendentes ou com falha ocupam a cota até a limpeza bem-sucedida. Envios incompletos com mais de 24 horas podem ser limpos. Um arquivo disponível passou pela validação de envio; a extração ocorre quando você faz uma pergunta, portanto documentos corrompidos, criptografados ou ilegíveis ainda podem falhar na análise.

Solicitações de chat, envios e exclusões registram uso medido. O catálogo de modelos e leituras de metadados não cobram créditos separadamente. Extração de documentos e análise de imagens são cobradas na solicitação de chat.

Consulte a cobrança de uma operação em usage.charged_credits. Um crédito equivale a 1.000.000 de microcréditos. Os limites das chaves são separados dos créditos da conta; ambos podem impedir solicitações. Confira o uso e configure os limites em Configurações → Chaves de API.

Os limites de contexto e visão do modelo continuam válidos mesmo que cada mensagem e anexo respeite os limites da API. Os orçamentos das chaves são redefinidos em períodos móveis diários, semanais ou mensais, desde a criação da chave ou o reinício do período anterior.

Uma solicitação iniciada com orçamento disponível pode ultrapassar ligeiramente um pequeno saldo restante, pois o custo final só é conhecido após a geração. Ao atingir o limite, novas solicitações de chat e alterações de arquivos param. Reservas impedem solicitações simultâneas de gastar o mesmo orçamento disponível.

Envie um Idempotency-Key para cada solicitação de chat, envio, finalização e exclusão. É opcional, mas altamente recomendado para evitar trabalho e cobranças repetidos após falhas de conexão.

Idempotency-Key: a-unique-key-for-this-operation

• Gere uma chave única para cada nova operação e salve-a com a solicitação original.
• Tente novamente com a mesma chave de API, chave de idempotência e entradas inalteradas. Após a liquidação, estado e resposta salvos podem ser reproduzidos por 24 horas sem outra chamada ao provedor nem cobrança.
• Uma repetição inclui X-Idempotent-Replayed: true. Reutilizar a chave com entradas diferentes ou durante a primeira solicitação retorna 409.
• Resultados em cache podem incluir erros. Repetir a mesma chave pode retornar a mesma falha em vez de executar novamente. Verifique o resultado antes de iniciar outra operação.
• Depois que a janela de repetição expira, reutilizar uma chave inicia uma nova solicitação que pode gerar outra cobrança.

Use esperas exponenciais para falhas temporárias de rede, limite de frequência ou serviço. Mantenha a chave de idempotência enquanto resolve uma solicitação de resultado incerto. Corrija primeiro entradas inválidas, credenciais expiradas ou créditos esgotados.

Excluir um arquivo não apaga uma resposta de chat ou envio em cache durante a janela de repetição. Repetir um envio após a exclusão retorna a resposta original e não recria o arquivo.

Os erros usam uma estrutura JSON estável. Consulte error.code para tratá-los e guarde request_id ou o cabeçalho X-Request-Id ao contatar o suporte.

{
  "error": {
    "type": "request_error",
    "code": "invalid_request",
    "message": "messages must contain 1 to 20 alternating user/assistant messages, end with a user message, and stay within 64,000 characters."
  },
  "request_id": "request-uuid"
}