# cortex airflow api Reference

Direct REST API access for Airflow endpoints not covered by high-level commands.

## Endpoint Discovery

```bash
# List all available endpoints
cortex airflow api ls

# Filter endpoints by pattern
cortex airflow api ls --filter variable
cortex airflow api ls --filter xcom

# Get full OpenAPI spec (for detailed method/parameter info)
cortex airflow api spec

# Get details for specific endpoint
cortex airflow api spec | jq '.paths["/api/v2/variables"]'
```

## HTTP Methods

```bash
# GET (default) - retrieve resources
cortex airflow api dags
cortex airflow api dags/my_dag
cortex airflow api dags -F limit=10 -F only_active=true

# POST - create resources
cortex airflow api variables -X POST -F key=my_var -f value="my value"

# PATCH - update resources
cortex airflow api dags/my_dag -X PATCH -F is_paused=false

# DELETE - remove resources
cortex airflow api variables/old_var -X DELETE
```

## Field Syntax

| Flag | Behavior | Use When |
|------|----------|----------|
| `-F key=value` | Auto-converts: `true`/`false` → bool, numbers → int/float, `null` → null | Most cases |
| `-f key=value` | Keeps value as raw string | Values that look like numbers but should be strings |
| `--body '{}'` | Raw JSON body | Complex nested objects |
| `-F key=@file` | Read value from file | Large values, configs |

```bash
# Type conversion examples
cortex airflow api dags -F limit=10 -F only_active=true
# Sends: params limit=10 (int), only_active=true (bool)

# Raw string (no conversion)
cortex airflow api variables -X POST -F key=port -f value=8080
# Sends: {"key": "port", "value": "8080"} (string, not int)
```

## Common Endpoints

### XCom Values
```bash
cortex airflow api xcom-entries -F dag_id=my_dag -F dag_run_id=manual__2024-01-15 -F task_id=my_task
```

### Event Logs / Audit Trail
```bash
cortex airflow api event-logs -F dag_id=my_dag -F limit=50
cortex airflow api event-logs -F event=trigger
```

### Backfills (Airflow 2.10+)
```bash
# Create backfill
cortex airflow api backfills -X POST --body '{
  "dag_id": "my_dag",
  "from_date": "2024-01-01T00:00:00Z",
  "to_date": "2024-01-31T00:00:00Z"
}'

# List backfills
cortex airflow api backfills -F dag_id=my_dag
```

### Task Instances for a Run
```bash
cortex airflow api dags/my_dag/dagRuns/manual__2024-01-15/taskInstances
```

### Connections (passwords exposed)
```bash
# Warning: Use 'cortex airflow config connections' for filtered output
cortex airflow api connections
cortex airflow api connections/my_conn
```

## Debugging

```bash
# Include HTTP status and headers
cortex airflow api dags -i

# Access non-versioned endpoints
cortex airflow api health --raw
```

## When to Use cortex airflow api

| Task | Use |
|------|-----|
| List/get DAGs, runs, tasks | `cortex airflow dags`, `cortex airflow runs`, `cortex airflow tasks` |
| Trigger and monitor runs | `cortex airflow runs trigger-wait` |
| Diagnose failures | `cortex airflow runs diagnose` |
| XCom, event logs, backfills | `cortex airflow api` |
| Create/update variables, connections | `cortex airflow api` |
| Any endpoint not in high-level CLI | `cortex airflow api` |
