Core concepts

This page explains the mental model behind FetchCatch — useful before diving into the console or CLI.

Multi-tenancy

Every FetchCatch account belongs to a tenant. Tenants are fully isolated:

• Flows, API sources, and runs never leak across tenants
• Secrets use envelope encryption per tenant
• API keys are scoped to a tenant

Within a tenant you can have multiple workspaces — think of them as projects or environments grouping related flows.

When you run fcc init --workspace payments, you bind a local repo folder to that workspace slug. After fcc login, tenant and workspace IDs are written to project.json.

Flows

A flow is a directed graph of nodes connected by edges. Each flow has:

• Slug — used in /v1/evaluate/{slug} (e.g. approve-expense)
• Name — human label in the console
• Draft — work-in-progress graph (editable)
• Published version — immutable snapshot callable via the API

You edit the draft in the designer or in .fetchcatch/flows/{slug}.json. Publishing makes a version live for evaluate calls.

Node types (summary)

→ Full reference: Node types

Runs

When something calls /v1/evaluate/{slug}, FetchCatch starts a run:

1. Validates input against the start node's schema
2. Walks the graph node by node
3. Either completes with a response, or pauses at a wait_for_event node

Paused runs stay in SQL (Durable Task). Resume with:

POST /v1/runs/{runId}/resume
{ "event": "user_confirmed", "payload": { ... } }

Inspect runs in the console under Runs — see step-by-step output, errors, and timing.

→ Runs & debugging

Response types

A response type is a named schema (flat fields) for flow output. Bind one on the start node so that:

• Defaults are seeded at run start
• Each decision node merges responseValues
• The end node validates required fields and types

This gives callers a stable JSON contract without ad-hoc payloads per branch.

→ Response types

API sources

An API source is an ingested OpenAPI (Swagger) document. Operations become draggable HTTP nodes in the designer. FetchCatch handles SSRF-safe outbound calls and attaches auth profiles (API keys, OAuth) per source.

→ API sources

Auth profiles

Auth profiles store credentials for calling your backends — not for calling FetchCatch. Link a profile to an API source so HTTP nodes authenticate correctly (Bearer token, OAuth refresh, etc.).

Configure in the console under Auth profiles.

Sync model (CLI)

The CLI treats your repo as the authoring surface:

fcc pull downloads. fcc apply uploads (including flow deletions when a local file is removed). Hashes detect conflicts if someone else changed the server.

→ Sync & CI

Console vs CLI — when to use which

Most teams use both: design in the console, pull to git, then iterate via PRs.

Security summary

→ API keys