Flow + Extract Pipeline

When you enable Extract on a Flow gate, it adds Stage 0 to the pipeline. Files uploaded to the gate are first processed by AI to extract structured data, which is then validated against the gate's schema.

How It Works

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Stage 0     │ →  │  Stage 1     │ →  │  Stage 2     │ →  │  Stage 3+    │
│  Extract     │    │  Validate    │    │  Render      │    │  Approve     │
│  (AI)        │    │  (Schema     │    │  (PDF/Excel) │    │  & Deliver   │
│              │    │   + Rules)   │    │              │    │              │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘

Structured inputs skip Stage 0: If an agent submits JSON, YAML, or XML directly, Stage 0 is bypassed — no extraction needed, no extract credit consumed.

Enable Stage 0

Via Dashboard

1. Open your gate in the Flow dashboard
2. Click the Extract Source step (Step 0)
3. Toggle Enable file extraction
4. A linked Extract config is created automatically

Via API

curl -X PATCH https://api.rynko.dev/api/flow/gates/GATE_ID/extract/enable \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "extractEnabled": true,
  "extractId": "uuid",
  "extractShortId": "extr_abc12345",
  "extractName": "Invoice Validator (Extract)"
}

Submit a File Run

Once Stage 0 is enabled, submit files via the pipeline endpoint:

cURL

curl -X POST https://api.rynko.dev/api/flow/gates/GATE_ID/runs/file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@invoice.pdf" \
  -F "instructions=Focus on the totals section"

Node.js

const result = await rynko.flow.submitFileRun('GATE_ID', {
  files: ['./invoice.pdf'],
  instructions: 'Focus on the totals section',
});

Run Lifecycle

A file-based run goes through these statuses:

Status	Stage	Description
extracting	0	AI is processing the file
extract_review	0	Waiting for human review (if configured)
validating	1	Extracted data is being validated
validated	1	Schema + rules passed
rendering	2	Document being generated (if configured)
pending_approval	3	Waiting for approval (if configured)
delivered	4	Result sent via webhook
completed	-	Pipeline finished

Failure Statuses

Status	Description
extraction_failed	AI could not extract data (file unreadable, provider error)
extract_rejected	Reviewer rejected the extracted data
extract_review_expired	Review window expired (5 days)
validation_failed	Extracted data failed schema validation

Schema Ownership

The gate's schema is the extraction schema — there's no separate schema to maintain. When you edit the gate's schema, the extraction target updates automatically.

Credits

Each file-based run costs:

• 1 extract credit (for Stage 0)
• 1 flow run (for Stage 1+)

Structured input (JSON/YAML/XML) costs only 1 flow run — no extract credit.

Disable Stage 0

curl -X PATCH https://api.rynko.dev/api/flow/gates/GATE_ID/extract/disable \
  -H "Authorization: Bearer YOUR_API_KEY"

The linked Extract config is archived (not deleted). Re-enabling Stage 0 reactivates it.