Extract API Reference

All Extract endpoints require authentication via API key (Authorization: Bearer YOUR_API_KEY).

Base URL: https://api.rynko.dev/api

Jobs

Create Extraction Job

POST /extract/jobs
Content-Type: multipart/form-data

Upload files and extract structured data using a schema or existing config.

Form Fields:

Field	Type	Required	Description
files	File[]	Yes	One or more files to extract from
schema	string (JSON)	Conditional	JSON Schema defining fields to extract. Required if no schemaId.
schemaId	string	Conditional	ID of an existing Extract config. Required if no schema.
gateId	string	No	Flow gate ID (uses gate's published schema)
instructions	string	No	Additional instructions for the AI provider
conflictResolution	string	No	flag_conflicts (default), prefer_first_file, prefer_highest_confidence
provider	string	No	AI provider override: google, anthropic, openai, openrouter

Response: 201 Created

{
  "id": "uuid",
  "shortId": "ejob_abc12345",
  "status": "QUEUED",
  "schemaSource": "custom",
  "fileCount": 1,
  "createdAt": "2026-03-25T10:00:00.000Z"
}

Get Extraction Job

GET /extract/jobs/:id

Returns the full job including result (when completed).

Response: 200 OK

{
  "id": "uuid",
  "shortId": "ejob_abc12345",
  "status": "COMPLETED",
  "schemaSource": "custom",
  "fileCount": 1,
  "result": {
    "data": { "invoiceNumber": "INV-001", "total": 1250.00 },
    "fields": [
      { "field": "invoiceNumber", "confidence": "HIGH", "score": 0.98 },
      { "field": "total", "confidence": "HIGH", "score": 0.99 }
    ]
  },
  "metadata": {
    "provider": "google",
    "model": "gemini-2.0-flash",
    "tokensUsed": 1250,
    "costEstimate": 0.002
  },
  "durationMs": 3200,
  "createdAt": "2026-03-25T10:00:00.000Z",
  "completedAt": "2026-03-25T10:00:03.200Z"
}

Job Statuses: QUEUED | PROCESSING | COMPLETED | FAILED | CANCELLED

List Extraction Jobs

GET /extract/jobs?status=COMPLETED&limit=20&offset=0

Query Parameters:

Param	Type	Description
status	string	Filter by status
limit	number	Max results (default 20, max 100)
offset	number	Pagination offset

Cancel Extraction Job

DELETE /extract/jobs/:id

Cancels a queued or processing job.

Get Extract Usage

GET /extract/usage

Returns current extraction credit usage.

{
  "used": 42,
  "limit": 100,
  "remaining": 58,
  "isBeta": true
}

Discovery

Create Discovery Job

POST /extract/discover
Content-Type: multipart/form-data

Upload files without a schema — the AI discovers what fields exist.

Form Fields:

Field	Type	Required	Description
files	File[]	Yes	Files to analyze
instructions	string	No	Hints about what to look for
gateId	string	No	Gate ID for reference extraction storage

Response: Same as Create Extraction Job. The result includes a discovered schema.

Extract Configs

Reusable extraction configurations with versioning.

Create Config

POST /extract/configs
Content-Type: application/json

{
  "name": "Invoice Extractor",
  "description": "Extracts standard invoice fields",
  "schemaMode": "json",
  "schema": {
    "type": "object",
    "properties": {
      "invoiceNumber": { "type": "string" },
      "total": { "type": "number" }
    }
  },
  "provider": "google",
  "instructions": "Focus on the header section for invoice metadata"
}

Get Config

GET /extract/configs/:id

List Configs

GET /extract/configs?status=active&limit=20

Update Config

PATCH /extract/configs/:id

Creates a draft version. Changes don't affect running jobs until published.

Publish Config

POST /extract/configs/:id/publish

{
  "versionName": "v2",
  "changeNotes": "Added line items field"
}

Get Version History

GET /extract/configs/:id/versions

Restore Version

POST /extract/configs/:id/versions/:versionId/restore

Creates a new draft from a historical version.

Run Config

POST /extract/configs/:id/run
Content-Type: multipart/form-data

Run extraction using a config's published version.

Field	Type	Required	Description
files	File[]	Yes	Files to extract from
instructions	string	No	Override instructions

Delete Config

DELETE /extract/configs/:id

warning

Gate-linked configs cannot be deleted directly. Disable Stage 0 on the gate first.

Gate Integration (Stage 0)

Enable Extract on Gate

PATCH /flow/gates/:gateId/extract/enable

Auto-creates a linked Extract config.

Disable Extract on Gate

PATCH /flow/gates/:gateId/extract/disable

Archives the linked Extract config (reversible).

Submit File Run

POST /flow/gates/:gateId/runs/file
Content-Type: multipart/form-data

Upload files for the full pipeline: Extract → Validate → Render → Approve → Deliver.

Field	Type	Required	Description
files	File[]	Yes	Files to process
instructions	string	No	Extraction instructions

Error Codes

Code	HTTP	Description
ERR_EXTRACT_001	400	No files provided
ERR_EXTRACT_002	400	Invalid schema
ERR_EXTRACT_003	400	Unsupported file type
ERR_EXTRACT_004	400	File too large (max 100MB)
ERR_EXTRACT_005	404	Job not found
ERR_EXTRACT_006	429	Rate limited
ERR_EXTRACT_007	402	No extraction credits remaining
ERR_EXTRACT_008	404	Config not found
ERR_EXTRACT_009	422	Cannot delete gate-linked config
ERR_EXTRACT_010	400	Config has no published version