Documentación de la API

La API de Regunow utiliza HTTPS, autenticación Bearer y el prefijo versionado /api/v1. Puede consultar esta documentación sin una cuenta. Las solicitudes a la API requieren acceso Pro activo y la aceptación de las políticas vigentes.

1. Inicie sesión en Regunow y cree una clave en Configuración → Claves de API.
2. Guarde el secreto de forma segura. Solo se muestra una vez, al crear la clave.
3. Configure el host y la clave y envíe su primera pregunta desde un backend o una automatización de confianza.

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

La respuesta está en output.content. La respuesta incluye las referencias a fuentes y los créditos cobrados. Esta solicitud consume créditos. Utilice una clave de idempotencia nueva para cada pregunta nueva.

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

Envíe la clave de API en la cabecera HTTP Authorization en cada solicitud. No se aceptan claves en las URL, las cookies ni los cuerpos de las solicitudes.

Authorization: Bearer rgn_live_...

Guarde las claves en una variable de entorno o un gestor de secretos. No las incluya en código del navegador, paquetes de aplicaciones móviles, repositorios públicos ni registros. El acceso desde navegadores de otros orígenes no está habilitado; haga las solicitudes a través de su servidor.

Las claves desactivadas, eliminadas o caducadas dejan de autenticar inmediatamente. Regunow solo almacena un hash del secreto, por lo que no puede volver a mostrarlo. Cree una clave de reemplazo cuando la necesite.

El acceso Pro y la aceptación de las políticas se comprueban en cada solicitud. Si recibe legal_acceptance_required, el titular de la clave debe iniciar sesión y abrir Aceptación legal. Una clave de API no puede aceptar políticas.

GET/api/v1/models

Consulte los modelos, niveles de esfuerzo, jurisdicciones, idiomas de respuesta y capacidades disponibles. Este endpoint autenticado no cobra créditos por separado y permite verificar una clave antes de solicitar una respuesta.

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

Utilice los valores del catálogo de su despliegue. En el modo Jurisdicción, omita model y effort para usar los valores predeterminados aceptados. Si los indica, deben corresponder a Sonnet 4.6 / Alto. En respuestas sin adjuntos, el servicio de recuperación gestiona el modelo de respuesta; el campo de modelo describe la selección validada.

POST/api/v1/chat/completions

Envíe un cuerpo JSON con un array messages. Por defecto, la API devuelve una respuesta completa en JSON. Establezca stream en true para recibir el texto de forma incremental.

{
  "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"]
}

Sustituya YOUR_FILE_ID por el UUID devuelto tras una carga correcta. En cada seguimiento, envíe el historial pertinente del usuario y el asistente, y vuelva a incluir los file_ids deseados. La API no recuerda automáticamente el historial ni los adjuntos.

Se rechazan los mensajes de sistema y los campos desconocidos. Esta API no ofrece generación de imágenes o informes, entrada de audio ni acceso a memorias guardadas. Las imágenes cargadas pueden utilizarse como entrada para preguntas.

Una solicitud correcta devuelve object: "regunow.chat.completion", la respuesta, metadatos de fuentes, uso y tiempos. Los valores siguientes son 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 contiene el texto definitivo de la respuesta. Las posiciones de las citas se refieren a esta cadena final; sourceIndexes identifica entradas en output.sources.
• Las fuentes incluyen título, nombre de archivo, tipo MIME, URI y fragmento recuperado. Muestre los fragmentos y las citas junto a la respuesta.
• Una URI de fuente indica una ubicación y puede apuntar a almacenamiento privado. Solo las URL públicas de los editores deben ofrecerse como enlaces accesibles. La API no permite descargar ni traducir archivos fuente regulatorios.
• Cuando se usan adjuntos, output.input_files identifica los archivos proporcionados. Las fuentes de adjuntos tienen file_id; las regulatorias y web tienen file_id: null. Las URI de adjuntos son null.
• La presencia de un archivo de entrada no prueba que respalde cada afirmación. Los modelos pueden omitir citas en línea; las imágenes o escaneos pueden tener fragmentos vacíos.

Los recuentos de tokens pueden ser null si el servicio de recuperación no los proporciona; significa desconocido, no cero. charged_credits es el cargo registrado al cliente. created es una marca Unix en segundos; las latencias se expresan en milisegundos.

Todas las respuestas de los endpoints llevan una cabecera X-Request-Id. Conserve el identificador para diagnosticar problemas. El JSON de respuestas de chat y errores también contiene request_id.

Establezca "stream": true. La respuesta usa text/event-stream. En cURL, añada -N para desactivar el almacenamiento en búfer de la salida.

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

Lea eventos SSE completos separados por líneas en blanco; un bloque de red puede contener parte de un evento o varios eventos. Añada choices[0].delta.content según llegue. Ignore los comentarios de mantenimiento de conexión que empiezan por :.

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]

El evento final de metadatos tiene un array choices vacío. Lea la respuesta definitiva, las citas y las fuentes en regunow.output, los tiempos en regunow.latency y los créditos en regunow.usage. Los tokens usan usage.prompt_tokens y usage.completion_tokens.

La recuperación y el procesamiento de citas pueden causar pausas. Trate el texto como provisional hasta recibir los metadatos finales. Un error posterior al inicio de la transmisión llega como un objeto error seguido de [DONE]; HTTP 200 por sí solo no confirma el éxito. Los errores previos de autenticación o validación devuelven respuestas JSON normales.

La repetición de una operación completada sigue usando SSE y devuelve la respuesta guardada en un único bloque de texto con X-Idempotent-Replayed: true.

Cargue documentos o imágenes y adjunte sus ID a una solicitud de chat. Comparten la Biblioteca y la cuota de almacenamiento del titular de la clave. Los documentos admiten hasta 10 MiB y las imágenes hasta 5 MiB.

Carga directa (recomendada)

Este flujo de tres pasos envía los bytes originales directamente al almacenamiento y evita los límites del cuerpo de solicitud de la aplicación. Úselo en integraciones alojadas, especialmente con archivos grandes.

POST/api/v1/files/upload-intents

Envíe solo name, mime_type y bytes (el tamaño exacto). Si tiene éxito, recibirá HTTP 201 con el ID de un archivo pendiente y una URL de carga firmada válida durante 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
}

Establezca FILE_ID con el id devuelto. Utilice los upload_method, upload_url y upload_headers recibidos para cargar los bytes originales exactos. Indique la Content-Length exacta. No envíe la clave de API de Regunow a la URL de carga ni registre las URL firmadas.

# 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

Envíe {} con otra clave de idempotencia. La finalización valida los bytes y devuelve HTTP 200 con un archivo disponible. Solo después de finalizar correctamente puede usar su ID en file_ids.

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

Si caduca la URL, elimine el archivo pendiente no utilizado y prepare otra carga con una clave nueva. Repetir la preparación no amplía la vigencia de la URL. Si el resultado de la finalización es incierto, consulte primero el estado del archivo. Si sigue pendiente, reintente finalizarlo con una clave de idempotencia nueva; la anterior reproduce el resultado guardado. Finalizar un archivo ya disponible devuelve sus metadatos.

Carga multiparte

POST/api/v1/files

Para archivos pequeños, envíe un campo multipart/form-data llamado file. Envíe bytes originales, no base64 ni una URL remota. La pasarela de alojamiento puede imponer un límite de cuerpo menor que el permitido por la 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"

Una carga correcta devuelve HTTP 201 con un archivo disponible; no hace falta una llamada de finalización adicional.

{
  "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 y eliminar archivos

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

Las claves de una misma cuenta acceden a sus archivos disponibles en la Biblioteca. Tanto los archivos inexistentes como los de otras cuentas devuelven 404. Si atiende a varios usuarios mediante una cuenta, aplique sus propios permisos antes de adjuntar o eliminar archivos.

Las cargas pendientes y fallidas ocupan cuota hasta que se limpian correctamente. Las incompletas de más de 24 horas pueden limpiarse. Un archivo disponible ha superado la validación de carga; la extracción ocurre al hacer una pregunta, por lo que documentos dañados, cifrados o ilegibles aún pueden fallar durante el análisis.

Las respuestas de chat, cargas y eliminaciones registran uso medido. El catálogo de modelos y las lecturas de metadatos no cobran créditos por separado. La extracción de documentos y el análisis de imágenes se cobran a través de la solicitud de chat.

Consulte el cargo de una operación en usage.charged_credits. Un crédito equivale a 1.000.000 de microcréditos. Los límites de la clave son independientes de los créditos de la cuenta; ambos pueden impedir una solicitud. Revise el uso y configure los límites en Configuración → Claves de API.

Siguen aplicándose los límites de contexto y visión del modelo aunque cada mensaje y adjunto cumpla los límites de la API. Los presupuestos de las claves se restablecen en períodos móviles diarios, semanales o mensuales, desde la creación de la clave o el cambio del período anterior.

Una solicitud que empieza con presupuesto puede superar ligeramente un pequeño saldo restante de la clave, porque el coste final se conoce tras la generación. Al alcanzar el límite se detienen nuevas solicitudes de chat y modificaciones de archivos. Las reservas evitan que solicitudes simultáneas gasten el mismo presupuesto disponible.

Envíe un Idempotency-Key para cada solicitud de chat, carga, finalización de carga y eliminación. Es opcional, pero muy recomendable para evitar trabajo y cargos repetidos tras fallos de conexión.

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

• Genere una clave única para cada operación nueva y guárdela junto a la solicitud original.
• Reintente la operación con la misma clave de API, clave de idempotencia y entradas sin cambios. Una vez liquidada, el estado y la respuesta guardados pueden reproducirse durante 24 horas sin otra llamada al proveedor ni otro cargo.
• Una repetición incluye X-Idempotent-Replayed: true. Reutilizar la clave con entradas diferentes o mientras la primera solicitud sigue en curso devuelve 409.
• Los resultados guardados pueden incluir errores. Repetir la clave puede devolver el mismo fallo en lugar de ejecutar otra vez. Compruebe el resultado antes de iniciar una operación nueva.
• Tras expirar la ventana de repetición, reutilizar una clave inicia una solicitud nueva que puede generar otro cargo.

Use esperas exponenciales ante fallos temporales de red, límites de frecuencia o servicio. Conserve la clave de idempotencia mientras resuelve una solicitud de resultado incierto. No reintente entradas inválidas, credenciales caducadas ni créditos agotados hasta corregir la causa.

Eliminar un archivo no borra una respuesta de chat o carga guardada durante su ventana de repetición. Repetir una carga tras eliminarla devuelve la respuesta original y no recrea el archivo.

Los errores usan una estructura JSON estable. Consulte error.code para gestionarlos y conserve request_id o la cabecera X-Request-Id al contactar con soporte.

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