Flujo verificable

Publicaciones y API

Tu tablero se convierte en un servicio invocable.

Construye un flujo visual, publica una versión e invócala desde tu aplicación, un script o tu asistente de IA.

Un flujo, varios puntos de entrada

Un tablero conecta entradas, modelos y salidas. Una publicación fija una versión y define lo que se puede enviar y recuperar. El canal API REST permite ejecutar esa versión por HTTP.

Tablero → Publicación → Versión → Llamada HTTP → Resultados

Construye un flujo visual, publica una versión e invócala desde tu aplicación, un script o tu asistente de IA.

Preparar la publicación

1

Construir y verificar el tablero

Conecta entradas, tratamientos y salidas. Comprueba el resultado en Naquada antes de ofrecerlo a tus herramientas.

2

Elegir las entradas y salidas

Pulsa Publicar. Define en la publicación los campos expuestos, sus alias y las salidas. Estos alias serán las claves del objeto inputs.

3

Activar la API y publicar una versión

En Activación, activa API REST. Publica la versión deseada para ese canal. Los cambios del tablero original no alteran una versión ya fijada.

4

Autorizar una clave

En Publicaciones → Claves, crea una clave y dale acceso a esta publicación. Deben estar activados tanto el canal como el acceso de la clave.

Probar y pasar a producción

Una clave Sandbox (ctr_sbx_…) devuelve resultados de prueba sin ejecutar modelos ni gastar créditos. Una clave Production (ctr_prd_…) ejecuta el flujo y consume los créditos del propietario.

Mantén la clave en el servidor

Guárdala en tu gestor de secretos, aquí como NAQUADA_PUBLICATION_KEY. El navegador o asistente llama a tu servicio, que autentica la petición a Naquada. No pongas la clave en el código público del sitio.

Invocar el flujo

Sustituye my-workflow por el slug de la publicación y version=1 por una versión publicada para la API. El parámetro version es obligatorio. El alias brief es ilustrativo: usa los alias de tu publicación.

Petición HTTP
curl --request POST \
  "https://api.naquada.tech/api/v1/generate/my-workflow?version=1" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY" \
  --header "Content-Type: application/json" \
  --data '{"inputs":{"brief":"A short product introduction"},"async_response":true}'

Con async_response: true, la API devuelve HTTP 202 y un resultId. Conserva el identificador para seguir la ejecución. Los valores de respuesta son ilustrativos.

Respuesta 202 · ejemplo
{
  "resultId": "12345678-1234-4234-8234-123456789abc",
  "status": "processing",
  "version": 1
}

Recuperar resultados

Consulta esta URL con la misma clave de publicación. La respuesta incluye status; las salidas expuestas aparecen en outputs al terminar el procesamiento. En el ejemplo, asigna a NAQUADA_RESULT_ID el resultId recibido.

Seguimiento del resultado
curl "https://api.naquada.tech/api/v1/generate/results/$NAQUADA_RESULT_ID" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"

processing: en curso · waiting_for_approval: espera validación humana · completed: terminado · partially_completed: resultados parciales · failed: error. Espacia las consultas y define un tiempo máximo en tu aplicación.

Sin async_response: true, la llamada espera hasta dos minutos. Puede devolver 202 si el trabajo continúa: la integración debe gestionar también este caso.

Archivos, notificaciones y límites

Para campos de archivo, envía URL HTTPS en inputs. Un campo múltiple acepta un array de URL. También puedes usar multipart/form-data: la parte data contiene el sobre JSON y cada archivo se llama file_<alias>.

Para recibir una notificación al terminar, configura un webhook autorizado. Verifica X-Naquada-Signature sobre el cuerpo original de la petición. Las entregas pueden reintentarse: procesa las notificaciones de forma idempotente.

Los límites diarios y mensuales son independientes y solo se aplican cuando están activos con un valor positivo. Los resultados de producción consumen el presupuesto del propietario.

Dar un flujo a tu asistente de IA

Expón una función en tu servicio: recibe los campos, llama a la versión publicada, sigue resultId y devuelve las salidas. Tu asistente decide cuándo llamarla; Naquada ejecuta el tablero preparado.

Descubrir los contratos disponibles

Lista las publicaciones autorizadas y recupera el contrato detallado con el identificador de publicación, no el del tablero original. Usa los campos para describir la herramienta al asistente.

Descubrimiento de publicaciones
curl "https://api.naquada.tech/api/v1/generate/boards" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"

curl "https://api.naquada.tech/api/v1/generate/discovery/$NAQUADA_PUBLICATION_ID" \
  --header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"

Las claves de cuenta nqk_acc_… son distintas de las claves de publicación. La invocación delegada requiere externalizations:invoke, acceso a la publicación y X-Naquada-Externalization-Key-Id con el identificador de una clave Production autorizada.

Ver la guía CLI y MCP