RunOCR

RunOCR documentation

Everything you need to build, test and integrate visual intelligence workflows.

Concepts

  • Workflow: a directed graph of steps on the canvas. Each workflow has exactly one trigger.
  • Step: a configured node. Steps have typed outputs and one or more outcomes (ports), for example true/false or found/not_found. A connection from an outcome decides which step runs next.
  • Draft and versions: the builder edits a draft. Publish freezes an immutable version, and triggers always run the published version. Test runs use the draft.
  • Run: one execution. Each step's input, output, outcome, attempts and duration are stored for the inspector and the audit trail.
  • Validation rules: workflow-level checks that each run's input must pass before any step executes (for example employee.email is required and must be an email).
  • Collections: your business records and reference data (employees, shipments, price lists). Import them from CSV or the API, and read and write them from steps.
  • Components: saved groups of steps you can insert into any workflow.

Variables & mapping

Every text field accepts variables in double braces. Use the { } picker next to a field to insert them.

{{trigger.file}}              the uploaded file
{{trigger.fields.email}}      an extra input value
{{extract.full_name}}         output of the step with ID "extract"
{{products.products.0.price}} list items by index
{{previous}}                  the output of the step that led here
{{item.price}}                the current item inside "Filter list"
{{run.id}} {{workflow.name}} {{now}}

If a field contains only one variable, its original type is kept (a list stays a list and a number stays a number). Otherwise the values are inserted as text.

Step reference

Triggers

Image uploaded, Video uploaded (frames are sampled in your browser), Website captured (full-page screenshot), Scheduled execution, API request received, Webhook received, New record.

Visual Intelligence

Extract text (OCR), Extract structured fields, Detect objects, Identify products, Read barcodes & QR codes, Analyze image or video, Compare images, Detect visual changes. Each returns typed fields plus a confidence between 0 and 1. Required fields that are not found fail the step.

Data & Lookup

Find existing record, Search database, Match customer or employee (fuzzy score with a threshold), Query reference dataset (enrich a list, optionally with diff_pct against a reference value), Lookup historical observations, Retrieve API data, Fetch file from URL.

Conditions & Validation

If / Else (condition groups combined with all/any), Switch, Compare values (with tolerance %), Threshold validation, Confidence validation, Required field validation, Duplicate detection, Filter list. These steps are fully deterministic.

AI Tasks

Classify information, Infer attributes, Summarize findings, Evaluate against instructions, Detect anomalies, Generate recommendations, Map to schema. AI steps produce data. Route on their output with a condition step.

Actions & Integrations

Create record, Update existing record, Send email, Send notification, Call API, Trigger webhook, Generate report, Create exception, Stop workflow.

Step settings

Every step has retries (0–3), a timeout and an on error behaviour: stop the run, continue on the normal outcome, or follow a dedicated error outcome.

Human review

Request approval, Manual verification, Accept or reject result, Assign to team member, Request additional evidence and Escalate exception. Review steps pause the run. If you set a reviewer email, that person gets a private link and can decide, correct values or upload files without an account. Open reviews also appear in the app's Reviews inbox. When someone decides, the run continues from that step.

REST API

Create an API key in Settings → API. Send it as a bearer token. Base URL: https://api.runocr.com.

Start a run

POST /v1/workflows/{id}/runs[?wait=30]
Authorization: Bearer rk_...

# JSON
{ "employee": { "name": "Maria Gonzalez", "email": "maria@example.com" } }

# or multipart: file=@photo.jpg plus any form fields

The run uses the published version. With wait (max 60 seconds) the response is returned when the run finishes or pauses. Otherwise poll the run.

Get a run

GET /v1/runs/{id}[?wait=30]

{ "id": 812, "status": "succeeded", "output": { "label": {...} },
  "steps": [ { "step": "label", "status": "succeeded", "port": "out" } ] }

Statuses: queued, running, waiting (human review), succeeded, failed, canceled.

Other endpoints

GET  /v1/workflows                      list workflows
POST /v1/files                          upload files (multipart "file")
POST /v1/collections/{name}/records     add a record (starts "New record" workflows)

Webhooks

Incoming: each workflow has a secret URL, https://api.runocr.com/hooks/<token>. POST JSON or multipart to start the published version. If the body contains image_url, the image is fetched for you. You can also require an X-RunOCR-Secret header.

Outgoing: the Trigger webhook step POSTs JSON. If you set a signing secret, each request carries X-RunOCR-Signature: sha256=<hmac> computed over the raw body.

Limits

  • Files up to 25 MB each (images, PDF, video), up to 20 per run.
  • Up to 150 steps per workflow. Loops are not supported yet; branches and merges are.
  • Outbound HTTP steps cannot reach private network addresses.
  • 200 workflow emails per account per day.