# Evaluate API

Runtime HTTP API for executing published flows. Authenticated with **tenant API keys** (not console session tokens).

Base URL: `https://api.fetchcatch.com`

> **.NET shop?** Skip the curl and use the [official .NET SDK](dotnet-sdk.md):
> ```bash
> dotnet add package FetchCatch.Client
> ```
> Typed `EvaluateAsync<TInput, TDecision>`, structured exceptions, retries, and OpenTelemetry tracing — same API, no boilerplate.

## Start a flow run

```
POST /v1/evaluate/{flowSlug}
Authorization: Bearer {apiKey}
Content-Type: application/json
```

### Request body

Prefer **flat JSON** matching the start node's `inputSchema`:

```json
{
  "userId": "u-123",
  "amount": 499.99
}
```

Optional envelope keys (may coexist with flat input):

| Field | Type | Description |
|-------|------|-------------|
| `correlationKey` | string | Idempotency / tracing |
| `dryRun` | boolean | Validate without side effects where supported |
| `input` | object | Legacy wrapped input |

### Response

Returns run result or paused state (when flow hits `wait_for_event`). Exact shape depends on flow completion vs pause; includes run id for resume.

Errors: `400` with `{ "error": "message" }` for validation failures.

## Resume a paused run

```
POST /v1/runs/{runId}/resume
Authorization: Bearer {apiKey}
Content-Type: application/json
```

```json
{
  "event": "user_confirmed",
  "payload": { "confirmed": true }
}
```

| Field | Description |
|-------|-------------|
| `event` | Must match the waiting node's `eventName` |
| `payload` | JSON merged into run state for the resume handler |

## Rate limiting

Evaluate endpoints use the `evaluate` rate limit policy. Handle `429` with backoff.

## Inspect a run

After evaluate returns a `runId`, fetch the full step trace:

```
GET /v1/runs/{runId}
Authorization: Bearer {apiKey}
```

From a repo or CI session with the CLI logged in:

```bash
fcc run <runId> --json
```

Useful for debugging paused runs (`waiting`), step errors, and final output. The
`--json` payload matches the REST response (run metadata + ordered steps with
outputs/errors).

## Console vs API auth

| Context | Auth |
|---------|------|
| `fcc` CLI / sync | Console login or `FETCHCATCH_TOKEN` |
| `/v1/evaluate` | API key from console → API Keys |

## Publishing

Only **published** flow versions are callable via evaluate.

| Surface | How to ship |
|---------|-------------|
| **CLI + git (recommended)** | `fcc apply` (sync drafts) → `fcc publish` (callable version with provenance) |
| **Console** | Publish button in the designer or flows list |
| **Legacy** | `"publish": true` in flow JSON on apply — still works but discouraged; use `fcc publish` in CI |

→ CI setup: [Sync & CI](sync-and-ci.md) · governance: [governance.md](governance.md)