API Reference

Overview

The Felix API lets you:

Create workflows from a natural language prompt — the planning agent designs and builds them
List and view workflows in your account
Run workflows with custom inputs (single or batch)
Monitor executions and retrieve results

Base URL

https://felix.so/api/v1

Authentication

All endpoints require an API key passed in the x-api-key header. Get your API key from Profile.

curl https://felix.so/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY"

Quick Start

1. List your workflows

curl https://felix.so/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Send welcome email",
      "description": "Sends a personalized welcome email to new users",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "cursor": null
}

2. Create a workflow

Describe what you want and the planning agent will build it:

curl -X POST https://felix.so/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Scrape Hacker News front page and extract the top 30 stories with title, URL, points, and author",
    "name": "HN Scraper"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "HN Scraper",
  "description": "",
  "url": "https://felix.so/app/workflows-v3/550e8400-e29b-41d4-a716-446655440000",
  "status": "planning",
  "created_at": "2024-01-15T10:32:00Z"
}

Open the url in your browser to watch the planning agent design your workflow in real time.

3. Get workflow details (optional)

Retrieve a workflow to see its input schema:

curl https://felix.so/api/v1/workflows/{workflowId} \
  -H "x-api-key: YOUR_API_KEY"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Send welcome email",
  "description": "Sends a personalized welcome email to new users",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": { "type": "string" },
      "name": { "type": "string" }
    },
    "required": ["email"]
  }
}

4. Run a workflow

curl -X POST https://felix.so/api/v1/workflows/{workflowId}/executions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"email": "john@example.com", "name": "John"}}'

{
  "execution_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "initial",
  "created_at": "2024-01-15T10:35:00Z"
}

5. Check execution status and get results

Poll the execution endpoint until status is finished. Use the retry_after_seconds hint to know when to poll again.

curl https://felix.so/api/v1/workflows/{workflowId}/executions/{executionId} \
  -H "x-api-key: YOUR_API_KEY"

While processing:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created_at": "2024-01-15T10:35:00Z",
  "url": "https://felix.so/app/workflows-v3/550e8400-.../execution/7c9e6679-...",
  "results": null,
  "retry_after_seconds": 5
}

Open the url to view execution progress in the Felix UI. When finished, text-based results include inline content so you can read them directly:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "finished",
  "created_at": "2024-01-15T10:35:00Z",
  "url": "https://felix.so/app/workflows-v3/550e8400-.../execution/7c9e6679-...",
  "results": [
    {
      "filename": "summary.md",
      "url": "https://storage.felix.so/results/abc123?token=xyz",
      "content": "# Email Summary\n\nWelcome email sent to john@example.com..."
    }
  ]
}

content is included for text files (.md, .json, .txt, .csv, .html, etc.) under 100KB
url is always a presigned download link (expires in 1 hour)
For binary files (PDFs, images), only url is returned

Batch Executions

Run a workflow multiple times with different inputs in a single request:

curl -X POST https://felix.so/api/v1/workflows/{workflowId}/executions/batch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"email": "alice@example.com", "name": "Alice"},
      {"email": "bob@example.com", "name": "Bob"}
    ],
    "concurrency": "medium"
  }'

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "total": 2,
  "executions": [
    { "execution_id": "aaa-111", "index": 0 },
    { "execution_id": "bbb-222", "index": 1 }
  ]
}

Concurrency levels: low (1), medium (5), high (15).

Execution Status

Status	Description
`initial`	Execution created, not yet started
`processing`	Currently running
`human_in_the_loop`	Waiting for human approval
`finished`	Completed successfully
`error`	Execution failed

Pagination

List endpoints return paginated results with a cursor field:

# First page
curl "https://felix.so/api/v1/workflows?limit=10"

# Next page (URL-encode the cursor value)
curl "https://felix.so/api/v1/workflows?limit=10&cursor=2024-01-15T10%3A30%3A00Z"

When cursor is null, there are no more results.

Limitations

Limit	Value	Description
Request body size	4 MB	Maximum size for request payloads
Rate limiting	100/min	Requests per minute per API key
Pagination limit	100 items	Maximum items returned per list request
Execution timeout	15 minutes	Maximum runtime for a single workflow execution
Concurrent executions	10	Maximum concurrent executions per workflow
Batch size	10,000	Maximum items per batch execution request

Errors

Code	Description
400	Bad request — check your parameters
401	Unauthorized — invalid or missing API key
404	Not found — resource doesn’t exist
429	Rate limited — slow down
500	Server error — try again later

Error responses include a message:

{
  "error": "Workflow not found"
}

Overview

MCP

Workflows

Executions

Overview

Base URL

Authentication

Quick Start

1. List your workflows

2. Create a workflow

3. Get workflow details (optional)

4. Run a workflow

5. Check execution status and get results

Batch Executions

Execution Status

Limitations

Errors

​Overview

​Base URL

​Authentication

​Quick Start

​1. List your workflows

​2. Create a workflow

​3. Get workflow details (optional)

​4. Run a workflow

​5. Check execution status and get results

​Batch Executions

​Execution Status

​Pagination

​Limitations

​Errors

Overview

Base URL

Authentication

Quick Start

1. List your workflows

2. Create a workflow

3. Get workflow details (optional)

4. Run a workflow

5. Check execution status and get results

Batch Executions

Execution Status

Pagination

Limitations

Errors