Run Workflow API

Overview

This endpoint allows you to execute a specific workflow by providing its ID and required input parameters. The response is returned after the model finishes generating — ideal for server-side integrations where you don’t need real-time streaming.

Endpoint

HTTP Method: POST
URL: /api/v1/run/{workflow_id}

Replace {workflow_id} with the actual workflow ID (e.g. wf_abc123).

Features

Full Response

Receive the complete generated output in a single JSON response.

Bearer Key Auth

Authenticate with your API secret key via the Authorization header.

Web Search Citations

Automatically receive source citations when the model uses web search.

Rate Limit Headers

Monitor your usage with rate limit headers in every response.

Authentication

Requires a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request

Path Parameters

Name	Required	Type	Description
workflow_id	Yes	string	The ID of the workflow to run (e.g. `wf_abc123`)

Request Body Content-Type: application/json Pass your workflow’s input variables as key/value pairs. The keys must match the variable names defined in your workflow template.

{
  "story": "a story about a dog named charlie"
}

Example Request

curl --request POST \
     --url https://aitutor-api.vercel.app/api/v1/run/wf_abc123 \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{"story": "a story about a dog named charlie"}'

Response

A successful response returns the full generated text and optional citations:

{
  "success": true,
  "result": "Once upon a time, there was a friendly dog named Charlie...",
  "citations": ["https://example.com/source"]
}

Field	Type	Description
success	boolean	Always `true` on success
result	string	The generated text output
citations	string[]	Optional. Web sources if the model used web search

Response Headers

Header	Description
x-ratelimit-limit	Your rate limit per window
x-ratelimit-remaining	Remaining requests in window

Error Responses

401 Unauthorized

Missing or invalid API key.

{
  "error": "Unauthorized. Please provide a valid secret key.",
  "success": false
}

402 Payment Required

No credits remaining on the account.

{
  "error": "No credits remaining. Please add credits to continue using the service.",
  "success": false,
  "code": "invalid_billing"
}

404 Not Found

Workflow not found or not published.

{
  "error": "Workflow not found",
  "success": false,
  "code": "workflow_not_found"
}

429 Too Many Requests

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "success": false
}

500 Internal Server Error

Something went wrong during execution.

{
  "error": "Failed to run workflow",
  "success": false,
  "code": "internal_server_error"
}

Code Examples

Python

import requests

url = "https://aitutor-api.vercel.app/api/v1/run/wf_abc123"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
data = {
    "story": "a story about a dog named charlie",
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Node.js

const response = await fetch(
  "https://aitutor-api.vercel.app/api/v1/run/wf_abc123",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      story: "a story about a dog named charlie",
    }),
  }
);

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

cURL

curl --request POST \
     --url https://aitutor-api.vercel.app/api/v1/run/wf_abc123 \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{"story": "a story about a dog named charlie"}'

Additional Notes

Input Variables: The request body keys must exactly match the variable names in your workflow template (e.g. {{story}}).
Max Duration: Requests can run for up to 300 seconds before timing out.
Credits: Each successful run deducts credits from your organization’s balance based on token usage.
Streaming Alternative: If you need real-time output as it’s generated, use the Streaming Workflow endpoint instead.

Get Started

Create

Library & Sharing

Models

Model Families

Advanced

Teams & Account

Pixio Canvas for iPad

Pixio Integrations

Pixio Project API

Pixio ComfyUI

AI Tutor

Machine

AI Tutor RAG API Endpoint

AI Tutor API Endpoint

Overview

Endpoint

Features

Full Response

Bearer Key Auth

Web Search Citations

Rate Limit Headers

Authentication

Request

Example Request

Response

Error Responses

Code Examples

Additional Notes

​Overview

​Endpoint

​Features

Full Response

Bearer Key Auth

Web Search Citations

Rate Limit Headers

​Authentication

​Request

​Example Request

​Response

​Error Responses

​Code Examples

​Additional Notes

Overview

Endpoint

Features

Authentication

Request

Example Request

Response

Error Responses

Code Examples

Additional Notes