Run Workflow

After enabling the Workflow API and creating an API Key, you can invoke the workflow via API inputs and obtain the workflow execution results.

Method

POST

URL

https://api-${endpoint}.gptbots.ai/v1/workflow/invoke

Authentication

For details, refer to the authentication method in the API Overview.

Request

Example

curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/workflow/invoke' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "userId": "<your_user_id>", "input": { <your_workflow_input_params> }, "isAsync": true, "webhook": [ { "method": "POST", "url": "https://example-1.com", "headers": { "Accept": "application/json", "Authorization": "Bearer <your_token>" } }, { "method": "GET", "url": "https://example-2.com?fr=google", "headers": { "Accept": "application/json", "Authorization": "Bearer <your_token>" } } ] }'

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/workflow/invoke' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "userId": "<your_user_id>",
    "input": {
        <your_workflow_input_params>
    },
    "isAsync": true,
    "webhook": [
        {
            "method": "POST",
            "url": "https://example-1.com",
            "headers": {
                "Accept": "application/json",
                "Authorization": "Bearer <your_token>"
            }
        },
        {
            "method": "GET",
            "url": "https://example-2.com?fr=google",
            "headers": {
                "Accept": "application/json",
                "Authorization": "Bearer <your_token>"
            }
        }
    ]
}'

Este bloque de código en una ventana flotante

Headers

Field	Type	Required	Description
Authorization	Bearer ${API Key}	Y	Validate calls using `Authorization: Bearer ${API Key}`; obtain the key on the API keys page as the `API Key`.
Content-Type	application/json	Y	Data type, fixed value is `application/json`.

Body

Field	Type	Required	Description
userId	String	N	Used to tag the user ID of this request.
input	Object	Y	The workflow's "start" node. This object must contain an input parameter structure exactly matching what is configured in the workflow's "start" node.
isAsync	Boolean	N	Defines whether this request runs asynchronously. - `true`: asynchronous execution. - `false` (default): synchronous execution. Note: If `true`, you can either use "Query workflow run result" to retrieve the result, or send the result to the address defined by "Webhook". These two methods do not conflict.
webhook	Array Object	N	When performing asynchronous operation, the workflow execution result can be sent to the specified Webhook. Up to 5 Webhook entries can be defined.
webhook[].method	String	Y	Webhook request method.
webhook[].url	String	Y	Webhook URL (address).
webhook[].headers	Object	N	Headers for the Webhook request, can be defined as needed.

Response

Example

If the run is synchronous, the result is shown below:

{ "workflowId": "xxxxxxxx", "workflowName": "todayNews", "workflowVersion": "1.0.1", "workflowRunId": "xxxxxxxx", "input": { "topic": "News" }, "output": { "news": [ { "summary": "Fatal crash shuts down major highway in Haleiwa. According to Emergency Medical Services, paramedics responded to the scene of the crash Wednesday morning.", "media": "Hawaii News Now", "title": "Hawaii News Now - Breaking News, Latest News, Weather & Traffic" }, { "summary": "Hawaii Crime: Man, 65, critically injured in Waikīkī assault. Jamil Hart found guilty in Mililani murder case. HPD busts illegal gambling room in Nanakuli.", "media": "KHON2", "title": "KHON2: Hawaii News, Weather, Sports, Breaking News & Live" } ] }, "workflowExecutionTime": 8347, "status": "SUCCEED", "totalCost": 0.6928, "totalTokens": 1745, "startTime": 1758765323024, "endTime": 1758765331373 }

                      
                      {
    "workflowId": "xxxxxxxx",
    "workflowName": "todayNews",
    "workflowVersion": "1.0.1",
    "workflowRunId": "xxxxxxxx",
    "input": {
        "topic": "News"
    },
    "output": {
        "news": [
            {
                "summary": "Fatal crash shuts down major highway in Haleiwa. According to Emergency Medical Services, paramedics responded to the scene of the crash Wednesday morning.",
                "media": "Hawaii News Now",
                "title": "Hawaii News Now - Breaking News, Latest News, Weather & Traffic"
            },
            {
                "summary": "Hawaii Crime: Man, 65, critically injured in Waikīkī assault. Jamil Hart found guilty in Mililani murder case. HPD busts illegal gambling room in Nanakuli.",
                "media": "KHON2",
                "title": "KHON2: Hawaii News, Weather, Sports, Breaking News & Live"
            }
        ]
    },
    "workflowExecutionTime": 8347,
    "status": "SUCCEED",
    "totalCost": 0.6928,
    "totalTokens": 1745,
    "startTime": 1758765323024,
    "endTime": 1758765331373
}

Este bloque de código en una ventana flotante

If the run is asynchronous, this API will return the result immediately as follows:

{ "workflowId": "xxxxxxxx", "workflowName": "todayNews", "workflowVersion": "1.0.1", "workflowRunId": "xxxxxxxx", "status": "PENDING" }

                      
                      {
    "workflowId": "xxxxxxxx",
    "workflowName": "todayNews",
    "workflowVersion": "1.0.1",
    "workflowRunId": "xxxxxxxx",
    "status": "PENDING"
}

Este bloque de código en una ventana flotante

You can asynchronously query the run result using the obtained workflowRunId.

Body

Field	Type	Description
workflowId	String	Workflow ID.
workflowName	String	Workflow name.
workflowVersion	String	Workflow version number.
workflowRunId	String	Workflow run ID, used to uniquely identify this execution.
input	Object	Input for the "start" node, identical to the input in the request.
output	Object	Output for the "end" node, containing the results of the workflow execution.
workflowExecutionTime	Number	Time spent executing the workflow, in milliseconds.
status	String	Workflow invocation status, possible values include: - SUCCEED: success - FAILED: failure - PENDING: in queue - RUNNING: running
totalCost	Number	Total cost credits for this run.
totalTokens	Number	Total tokens consumed for this run.
startTime	Number	Start timestamp, in milliseconds.
endTime	Number	End timestamp, in milliseconds.