Workflow Run API

Version requirement: Pro and above

Introduction

This is an advanced API for workflow execution. Compared to workflow execution through the General Chat API, it offers these additional features:

1. Support for passing custom variables defined in the start node
2. Support for image and file type parameter inputs
3. Support for context memory enabled in workflow nodes

Online API testing: API Debug Console

API Definition

Endpoint

POST https://api.linkai.cloud/v1/workflow/run

Request Headers

Parameter	Value	Description
Authorization	Bearer YOUR_API_KEY	Create an API Key following Authentication
Content-Type	application/json	Indicates JSON format request

Request Body

Parameter	Type	Required	Description
app_code	string	Yes	The unique code of the Workflow
args	dict	No	Workflow input variables, including system variables and custom variables, defined in the workflow's start node
session_id	string	No	Session ID, each session_id has independent context memory storage, usable when memory is enabled in LLM, Agent, or intent recognition nodes. If not provided, the system will automatically assign a unique identifier and return it in the response for future requests

Workflow Variable Notes:

1. System variables supported in the start node include text input, image input, file input, with parameter names as follows:

input_text    # Text input
input_image   # Image URL (must be publicly accessible)
input_file    # File URL (must be publicly accessible)

You can enable system variables in the workflow's start node. Once enabled, pass variable values in the args parameter. If system variables are not enabled, these parameters can be omitted:

2. In addition to system variables, custom variables are also supported:

When adding custom variables, you can set the English name of the variable, and pass the variable value through the args parameter in the API call:

Request Example:

{
    "app_code": "G7z6vKwp",
    "args": {
        "input_text": "",          # System default variable
        "height": "1.8",           # Custom variable
        "weight": "75"             # Custom variable
    }
}

Notes:

• app_code: The code of your created workflow
• args: Values for system variables or custom variables needed in the workflow

Example workflow URL: https://linkai.cloud/app/T8kjAqQw7o

Response

The output_text field contains the text output of the workflow:

{
    "success": true,
    "code": 200,
    "message": "success",
    "data": {
        "output_text": "Hello! Your BMI is 23.15, which is within the normal range (between 18.5-23.9). Congratulations, maintaining this range is a sign of good health!\n\nTo further maintain your health, I recommend continuing with a balanced diet and moderate exercise. Consider increasing your intake of fiber-rich foods like fruits, vegetables, and whole grains, while reducing consumption of high-sugar and high-fat foods. Additionally, aim for at least 150 minutes of moderate-intensity exercise per week, such as brisk walking, swimming, or cycling, which are all very beneficial."
    }
}

Error Handling

When an error occurs, the API returns the following structure:

{
    "success": false,
    "code": 408,
    "message": "No API access permission for current version",
    "data": null
}

Determine the error type based on the HTTP status code and error message:

HTTP Status Code	Description
400	Invalid request format
401	Authentication failed, please check if your API Key is correct
402	Agent does not exist, please check if the app_code parameter is correct
403	No access permission, for private Agents, only the creator account can call
406	Insufficient account credits
408	No API access permission, this API supports Pro version and above
409	Content moderation failed, sensitive content may exist in the question, answer, or knowledge base
503	API call exception, please contact customer service

Example Code

1. CURL Request

curl -X POST "https://api.linkai.cloud/v1/workflow/run" \
    -H "Content-Type: application/json" \
    -H "authorization: Bearer YOUR_API_KEY" \
    -d '{
        "app_code": "T8kjAqQw7o",
        "args": {
            "height": "1.8",
            "weight": "75"
        }
    }'

Note: Replace YOUR_API_KEY with your created API Key, and fill in your workflow code in the app_code field.

Example workflow URL: https://linkai.cloud/app/T8kjAqQw7o

2. Python Code

import requests

url = "https://api.linkai.cloud/v1/workflow/run"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
body = {
    "app_code": "T8kjAqQw7o",
    "args": {
        "height": "1.8",
        "weight": "75"
    }
}
res = requests.post(url, json=body, headers=headers)
if res.status_code == 200:
    res_json = res.json()
    reply_text = res_json.get("data").get("output_text")
    print(f"result={reply_text}")
else:
    error = res.json()
    print(f"Request error, status code={error.get('code')}, error message={error.get('message')}")

Note: Replace YOUR_API_KEY with your created API Key, fill in your workflow code in the app_code field, and provide values for system variables or custom variables you've set in args.