> ## Documentation Index
> Fetch the complete documentation index at: https://felix.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Trigger workflows programmatically, manage executions, and integrate Felix into your applications.

## 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](https://felix.so/app/profile).

```bash theme={null}
curl https://felix.so/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY"
```

## Quick Start

### 1. List your workflows

```bash theme={null}
curl https://felix.so/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "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:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "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

```bash theme={null}
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"}}'
```

```json theme={null}
{
  "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.

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

While processing:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```json theme={null}
{
  "error": "Workflow not found"
}
```