API

La API te permite ejecutar flujos de trabajo en el sistema de forma programática. Para información sobre los costos de ejecución, consulta la documentación de uso de créditos.

Endpoints

Endpoint de Ejecución

Actualmente, solo se admiten solicitudes HTTP POST:

POST https://api.arkai.app/api/executeWorkflow

Ejemplo de Uso

JavaScript (usando fetch)

const apiKey = "tu-api-key";
const workflowId = "12345";

const response = await fetch(
  "https://api.arkai.app/api/executeWorkflow",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
    },
    body: JSON.stringify({
      workflowId: workflowId,
      version: 1,
      input: {
        "First Name": "John",
        Age: 30,
      },
    }),
  }
);

const result = await response.json();
console.log(result.output);

Python (usando requests)

import requests

api_key = 'tu-api-key'
workflow_id = '12345'

response = requests.post(
    'https:/api.arkai.app/api/executeWorkflow',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': api_key
    },
    json={
        'workflowId': workflow_id,
        'version': 1,
        'input': {
            'First Name': 'John',
            'Age': 30
        }
    }
)

result = response.json()
print(result['output'])

Descripción

Este endpoint ejecuta un flujo de trabajo basado en el ID y versión proporcionados. Procesa tus datos de entrada según la configuración del flujo de trabajo y devuelve los resultados. Para detalles sobre cómo configurar entradas y salidas de flujos de trabajo, consulta la guía de configuración de entradas/salidas.

Parámetros de Entrada

Parámetro	Tipo	Descripción
`workflowId`	`string`	El ID del flujo de trabajo a ejecutar
`version`	`number`	La versión del flujo de trabajo a ejecutar
`input`	`WorkflowInput`	Objeto que contiene valores de entrada para cada componente de entrada del flujo de trabajo
`conversationId`	`string` (opcional)	ID de una conversación existente para continuar. Si se omite, crea una nueva conversación

Tipo WorkflowInput

El WorkflowInput es un objeto donde:

Cada clave es el identificador de un componente de entrada configurado en tu flujo de trabajo
Cada valor es el dato de entrada correspondiente, coincidiendo con el tipo especificado en la configuración del componente

Por ejemplo, si tu flujo de trabajo tiene componentes de entrada etiquetados como "Nombre" (texto) y "Edad" (número), tu entrada podría verse así:

{
  "workflowId": "12345",
  "version": 1,
  "input": {
    "First Name": "John",
    "Age": 30
  },
  "conversationId": "67890"
}

Parámetros de Salida

Parámetro	Tipo	Descripción
`conversationId`	`string`	ID de la conversación. Úsalo para solicitudes relacionadas posteriores
`output`	`WorkflowOutput`	Objeto que contiene valores de salida de cada componente de salida
`creditUsage`	`number`	Número de créditos consumidos por esta ejecución

Tipo WorkflowOutput

El WorkflowOutput es un objeto donde:

Cada clave es el identificador de un componente de salida configurado en tu flujo de trabajo
Cada valor es el dato de salida correspondiente, coincidiendo con el tipo especificado en la configuración del componente

Ejemplo de respuesta:

{
  "conversationId": "67890",
  "output": {
    "Resultados del Análisis": "Hallazgos detallados del análisis",
    "Puntuación de Riesgo": 85
  },
  "creditUsage": 10
}

Endpoint de Ejecución en Segundo Plano

Para flujos de trabajo de larga duración o cuando no necesitas resultados inmediatos, puedes usar el endpoint de ejecución en segundo plano:

POST https://api.arkai.app/api/executeWorkflowBackground

Ejemplo de Uso

JavaScript (usando fetch)

const apiKey = "tu-api-key";
const workflowId = "12345";

const response = await fetch(
  "https://api.arkai.app/api/executeWorkflowBackground",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
    },
    body: JSON.stringify({
      workflowId: workflowId,
      version: 1,
      input: {
        "Nombre": "John",
        "Edad": 30,
      },
    }),
  }
);

const result = await response.json();
console.log(result.conversationId);

Python (usando requests)

import requests

api_key = 'tu-api-key'
workflow_id = '12345'

response = requests.post(
    'https://api.arkai.app/api/executeWorkflowBackground',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': api_key
    },
    json={
        'workflowId': workflow_id,
        'version': 1,
        'input': {
            'Nombre': 'John',
            'Edad': 30
        }
    }
)

result = response.json()
print(result['conversationId'])

Descripción

Este endpoint inicia una ejecución de flujo de trabajo en segundo plano y devuelve inmediatamente con un ID de conversación. El flujo de trabajo continuará procesando de forma asíncrona. Esto es útil para:

Flujos de trabajo de larga duración que podrían exceder los límites típicos de tiempo de espera HTTP
Flujos de trabajo que no requieren resultados inmediatos
Escenarios donde quieres iniciar el procesamiento y verificar los resultados más tarde

Parámetros de Entrada

Parámetro	Tipo	Descripción
`workflowId`	`string`	El ID del flujo de trabajo a ejecutar
`version`	`number`	La versión del flujo de trabajo a ejecutar
`input`	`WorkflowInput`	Objeto que contiene valores de entrada para cada componente de entrada del flujo de trabajo
`conversationId`	`string` (opcional)	ID de una conversación existente para continuar. Si se omite, crea una nueva conversación

Los parámetros de entrada son idénticos al endpoint de ejecución síncrona.

Parámetros de Salida

Parámetro	Tipo	Descripción
`conversationId`	`string`	ID de la conversación. Úsalo para verificar el estado y resultados
`creditUsage`	`number`	Uso inicial de créditos (típicamente 0 ya que la ejecución no está completa)

Ejemplo de respuesta:

{
  "conversationId": "67890",
  "creditUsage": 0
}

Autenticación

Incluye tu API key en el encabezado x-api-key con cada solicitud, igual que en el endpoint síncrono.

Verificación del Estado de Ejecución

Para verificar el estado y resultados de una ejecución en segundo plano, tienes dos opciones:

Opción 1: Usando la UI de la Plataforma

Navega a tu flujo de trabajo en la plataforma
Abre el playground del flujo de trabajo
Encuentra la conversación usando el ID proporcionado
Ver los detalles completos de la ejecución, incluyendo:
- Valores de entrada
- Resultados de salida
- Ruta de ejecución
- Cualquier error o advertencia
- Uso final de créditos

Opción 2: Usando la API

Puedes recuperar los detalles de la conversación programáticamente usando el endpoint getConversationById:

POST https://api.arkai.app/api/getConversationById

Ejemplo de solicitud:

{
  "workflowId": "12345",
  "conversationId": "67890"
}

La respuesta incluirá los detalles completos de la conversación, incluyendo el estado de ejecución y resultados.

Autenticación

Incluye tu API key en el encabezado x-api-key con cada solicitud.

Respuestas de Error

Todos los endpoints pueden devolver las siguientes respuestas de error:

Código de Estado	Descripción
400	Parámetros inválidos o créditos insuficientes
401	API key inválida
403	Permisos insuficientes para ejecutar el flujo de trabajo o recuperar la información
404	Flujo de trabajo no encontrado

Formato de Respuesta de Error

{
  "error": "Mensaje de error"
}

Depuración

Todas las ejecuciones de API se guardan como conversaciones y pueden verse en el playground o recuperarse a través de la API. Para depurar llamadas API:

Para ejecuciones síncronas, verifica la respuesta inmediata
Para ejecuciones en segundo plano, usa el conversationId para:
- Ver la conversación en la UI de la plataforma
- Recuperar detalles de la conversación a través del endpoint getConversationById
Revisa los detalles completos de la ejecución, incluyendo:
- Valores de entrada
- Resultados de salida
- Ruta de ejecución
- Cualquier error o advertencia
- Uso de créditos

Esto facilita la depuración de llamadas API y verificar que el flujo de trabajo se comporta como se espera.

Mejores Prácticas

Usa ejecución en segundo plano para flujos de trabajo que puedan tardar más de 30 segundos en completarse
Almacena el conversationId para verificar resultados más tarde
Considera implementar un mecanismo de sondeo para verificar el estado de ejecución si es necesario
Monitorea el uso de créditos a través de la vista de conversación en la plataforma

Endpoints

Endpoint de Ejecución​

Ejemplo de Uso​

JavaScript (usando fetch)​

Python (usando requests)​

Descripción​

Parámetros de Entrada​

Tipo WorkflowInput​

Parámetros de Salida​

Tipo WorkflowOutput​

Endpoint de Ejecución en Segundo Plano​

Ejemplo de Uso​

JavaScript (usando fetch)​

Python (usando requests)​

Descripción​

Parámetros de Entrada​

Parámetros de Salida​

Autenticación​

Verificación del Estado de Ejecución​

Opción 1: Usando la UI de la Plataforma​

Opción 2: Usando la API​

Autenticación​

Respuestas de Error​

Formato de Respuesta de Error​

Depuración​

Mejores Prácticas​

Endpoint de Ejecución

Ejemplo de Uso

JavaScript (usando fetch)

Python (usando requests)

Descripción

Parámetros de Entrada

Tipo WorkflowInput

Parámetros de Salida

Tipo WorkflowOutput

Endpoint de Ejecución en Segundo Plano

Ejemplo de Uso

JavaScript (usando fetch)

Python (usando requests)

Descripción

Parámetros de Entrada

Parámetros de Salida

Autenticación

Verificación del Estado de Ejecución

Opción 1: Usando la UI de la Plataforma

Opción 2: Usando la API

Autenticación

Respuestas de Error

Formato de Respuesta de Error

Depuración

Mejores Prácticas