API Run

HTTP API Reference for AgenticFlow – How to run and monitor workflows via API

Base URL:
https://api.agenticflow.ai/

This page documents the HTTP API for running and monitoring workflows in AgenticFlow.

Authentication

All API requests require an API key. Find your API key and Workspace ID at: https://agenticflow.ai/app/workspaces/{WORKSPACE_ID}/settings/api-keys

Authorization Header Example:

Authorization: Bearer {API_KEY}

Python Example:

headers = {
    "Authorization": f"Bearer {api_key}",
}

Endpoints

1. Trigger a Workflow (Async)

POST /v1/workflow_runs/

Description: Start a workflow run. Returns a workflow run ID to check status later.
Headers:
- Authorization: Bearer {API_KEY}
- Content-Type: application/json
Body:
- workflow_id (string): Input your Workflow ID
- input (object): Input parameters for the workflow. This object should contain key-value pairs that correspond to the variables or fields expected by your workflow. Each key should match the name of an input variable defined in your workflow, and the value should be the data you want to provide for that variable.

Input Example:

Suppose your workflow expects two variables: text_prompt (string) and max_tokens (integer). Your request body would look like this:

{
  "workflow_id": "YOUR_WORKFLOW_ID",
  "input": {
    "text_prompt": "Write a short story about a robot.",
    "max_tokens": 200
  }
}

You can include as many fields in the input object as your workflow requires.
The names and types of these fields must match what your workflow expects.
If you are unsure what inputs are required, check your workflow's configuration or documentation.

Example cURL:

curl -X POST "https://api.agenticflow.ai/v1/workflow_runs/" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "YOUR_WORKFLOW_ID",
    "input": {
      "text_prompt": "Write a short story about a robot.",
      "max_tokens": 200
    }
  }'

Example Python:

import requests

url = "https://api.agenticflow.ai/v1/workflow_runs/"
payload = {
    "workflow_id": workflow_id,
    "input": {
        "text_prompt": "Write a short story about a robot.",
        "max_tokens": 200
    }
}
response = requests.post(url, headers=headers, json=payload)
workflow_run_id = response.json()["id"]

2. Check Workflow Run Status

GET /v1/workflow_runs/{workflow_run_id}

Description: Get the status and result of a workflow run.
Headers:
- Authorization: Bearer {API_KEY}

Example cURL:

curl -X GET "https://api.agenticflow.ai/v1/workflow_runs/{workflow_run_id}" \
  -H "Authorization: Bearer $API_KEY"

Example Python:

status_url = f"https://api.agenticflow.ai/v1/workflow_runs/{workflow_run_id}"
status_response = requests.get(status_url, headers=headers)
print(status_response.json())

Parameters

workflow_id (string): The ID of the workflow to run.
workflow_run_id (string): The ID of the workflow run to check.
input (object): Input parameters for the workflow.

Status Values

queued: Workflow is waiting to be started.
running: Workflow is currently in progress.
success: Workflow completed successfully.
failed: Workflow failed to complete.
cancelled: Workflow was cancelled before completion.

Error Codes

Code

Meaning

401

Unauthorized

404

Not Found

429

Rate Limit Exceeded

500

Internal Server Error

Rate Limits

600 requests per minute for workflow runs.
3000 requests per minute for status checks.