API

The API allows you to execute workflows in the system programmatically. For information about execution costs, see the credit usage documentation.

Endpoints

Execute Endpoint

Currently, only HTTP POST requests are supported:

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

Example Usage

JavaScript (using fetch)

const apiKey = "your-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 (using requests)

import requests

api_key = 'your-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'])

Description

This endpoint executes a workflow based on the provided workflow ID and version. It processes your input data according to the workflow's configuration and returns the results. For details on configuring workflow inputs and outputs, see the input/output configuration guide.

Input Parameters

Parameter	Type	Description
workflowId	string	The ID of the workflow to execute
version	number	The version of the workflow to execute
input	WorkflowInput	Object containing input values for each workflow input component
conversationId	string (optional)	ID of an existing conversation to continue. If omitted, creates a new conversation

WorkflowInput Type

The WorkflowInput is an object where:

• Each key is the identifier of an input component configured in your workflow
• Each value is the corresponding input data, matching the type specified in the component's configuration

For example, if your workflow has input components labeled "First Name" (text) and "Age" (number), your input might look like:

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

Output Parameters

Parameter	Type	Description
conversationId	string	ID of the conversation. Use this for subsequent related requests
output	WorkflowOutput	Object containing output values from each workflow output component
creditUsage	number	Number of credits consumed by this execution

WorkflowOutput Type

The WorkflowOutput is an object where:

• Each key is the identifier of an output component configured in your workflow
• Each value is the corresponding output data, matching the type specified in the component's configuration

Example response:

{
  "conversationId": "67890",
  "output": {
    "Analysis Results": "Detailed findings from the analysis",
    "Risk Score": 85
  },
  "creditUsage": 10
}

Background Execution Endpoint

For long-running workflows or when you don't need immediate results, you can use the background execution endpoint:

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

Example Usage

JavaScript (using fetch)

const apiKey = "your-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: {
        "First Name": "John",
        Age: 30,
      },
    }),
  }
);

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

Python (using requests)

import requests

api_key = 'your-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': {
            'First Name': 'John',
            'Age': 30
        }
    }
)

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

Description

This endpoint initiates a workflow execution in the background and returns immediately with a conversation ID. The workflow will continue processing asynchronously. This is useful for:

• Long-running workflows that might exceed typical HTTP timeout limits
• Workflows that don't require immediate results
• Scenarios where you want to start processing and check results later

Input Parameters

Parameter	Type	Description
workflowId	string	The ID of the workflow to execute
version	number	The version of the workflow to execute
input	WorkflowInput	Object containing input values for each workflow input component
conversationId	string (optional)	ID of an existing conversation to continue. If omitted, creates a new conversation

The input parameters are identical to the synchronous execution endpoint.

Output Parameters

Parameter	Type	Description
conversationId	string	ID of the conversation. Use this to check execution status and results
creditUsage	number	Initial credit usage (typically 0 as execution is not complete)

Example response:

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

Authentication

Include your API key in the x-api-key header with each request, just like the synchronous endpoint.

Checking Execution Status

To check the status and results of a background execution, you have two options:

Option 1: Using the Platform UI

1. Navigate to your workflow in the platform
2. Open the workflow's playground
3. Find the conversation using the provided ID
4. View the complete execution details, including:
   • Input values
   • Output results
   • Execution path
   • Any errors or warnings
   • Final credit usage

Option 2: Using the API

You can programmatically retrieve conversation details using the getConversationById endpoint:

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

Example request:

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

The response will include the complete conversation details, including execution status and results.

Authentication

Include your API key in the x-api-key header with each request.

Error Responses

All endpoints may return the following error responses:

Status Code	Description
400	Invalid parameters or insufficient credits
401	Invalid API key
403	Insufficient permissions to execute the workflow or to retrieve the information
404	Workflow not found

Error Body Response Format

{
  "error": "Error message"
}

Debugging

All API executions are saved as conversations and can be viewed in the playground or retrieved via the API. To debug API calls:

1. For synchronous executions, check the immediate response
2. For background executions, use the conversationId to:
   • View the conversation in the platform UI
   • Retrieve conversation details via the getConversationById endpoint
3. Review the complete execution details, including:
   • Input values
   • Output results
   • Execution path
   • Any errors or warnings
   • Credit usage

This makes it easy to debug API calls and verify the workflow behaves as expected.

Best Practices

• Use background execution for workflows that might take longer than 30 seconds to complete
• Store the conversationId to check results later
• Consider implementing a polling mechanism to check execution status if needed
• Monitor credit usage through the conversation view in the platform