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 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:

{
  "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

{
  "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:

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 · governance: governance.md