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
Preparar la publicación
Construir y verificar el tablero
Conecta entradas, tratamientos y salidas. Comprueba el resultado en Naquada antes de ofrecerlo a tus herramientas.
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.
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.
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
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.
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.
{
"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.
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.
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