Quickstart

This quickstart is the direct runtime path.

It is for developers and platform teams who want to see how Hyphen works at the API and workflow level without starting in a guided authoring surface.

If you want guided process design instead, start with Process Studio. If you want browser-safe product embedding, start with SDK Quickstart and Gateway Quickstart.

What you'll build

A small workflow that demonstrates the core Hyphen runtime pattern:

  1. deterministic matching handles the clear cases
  2. a bounded agent investigates exceptions
  3. a human approval step handles the edge cases
  4. the result is written to durable storage

We'll use invoice reconciliation because it is easy to follow, but the same structure applies to many other operating processes.

Before you start

For this quickstart, you need:

  • a Hyphen runtime endpoint
  • an org ID if you are calling the engine directly
  • curl or Postman

If you are using the public gateway instead of the direct engine, see Embedding Hyphen for the gateway path.

The runtime pattern

flowchart TD A["Operational input"] --> B["Deterministic step"] B -->|"clear cases"| E["Complete"] B -->|"exceptions"| C["Bounded agent"] C -->|"resolved"| E C -->|"needs review"| D["Human approval"] D --> E E --> F["Audit + storage"]

This is the basic Hyphen runtime shape:

  • clear work is handled quickly
  • ambiguous work moves into a bounded reasoning step
  • uncertain or high-stakes outcomes pause for a human
  • the run leaves behind a durable trace

Step 1: Prepare example data

Invoices

json
[
  { "invoice_id": "INV-001", "vendor": "Acme Corp", "amount": 10000.00, "date": "2026-01-15" },
  { "invoice_id": "INV-002", "vendor": "Globex Inc", "amount": 4500.00, "date": "2026-01-18" },
  { "invoice_id": "INV-003", "vendor": "Initech", "amount": 7250.00, "date": "2026-01-20" },
  { "invoice_id": "INV-004", "vendor": "Umbrella Ltd", "amount": 15000.00, "date": "2026-01-22" },
  { "invoice_id": "INV-005", "vendor": "Stark Industries", "amount": 3200.00, "date": "2026-01-25" }
]

Payments

json
[
  { "invoice_id": "INV-001", "vendor": "Acme Corp", "amount": 10000.00, "date": "2026-01-16" },
  { "invoice_id": "INV-002", "vendor": "Globex Inc", "amount": 4480.00, "date": "2026-01-19" },
  { "invoice_id": "INV-004", "vendor": "Umbrela Ltd", "amount": 15000.00, "date": "2026-01-23" },
  { "invoice_id": "INV-006", "vendor": "Wayne Enterprises", "amount": 8800.00, "date": "2026-01-27" }
]

This dataset gives us a few useful cases:

  • one exact match
  • one amount discrepancy inside tolerance
  • one fuzzy vendor-name match
  • two unmatched invoices
  • one unmatched payment

Step 2: Create a workflow

POST/workflows

Create a workflow with matching, agent investigation, human approval, and audit logging.

bash
curl -X POST https://your-hyphen.example.com/workflows \
  -H "X-Org-Id: your-org" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice_payment_reconciliation",
    "definition": {
      "actions": [
        {
          "type": "matcher",
          "properties": {
            "left": "@input.invoices",
            "right": "@input.payments",
            "matchOn": ["invoice_id"],
            "tolerance": 50,
            "dateWindowDays": 3,
            "fuzzyThreshold": 85,
            "descriptionKey": "vendor",
            "outputMatched": "matched",
            "outputUnmatchedLeft": "unmatched_invoices",
            "outputUnmatchedRight": "unmatched_payments"
          }
        },
        {
          "type": "loop",
          "filter": {
            "condition": {
              "greaterThan": [{ "length": "@unmatched_invoices" }, 0]
            }
          },
          "properties": {
            "mode": "react",
            "objective": "Investigate these unmatched invoices. For each, determine the most likely reason and recommend the next action.",
            "tools": [
              { "type": "action", "name": "lookup_vendor_history" }
            ],
            "max_iterations": 10,
            "on_stuck": { "iterations": 3, "action": "escalate" },
            "result_key": "investigation"
          }
        },
        {
          "type": "PbotApproval",
          "filter": {
            "condition": {
              "greaterThan": [{ "length": "@unmatched_invoices" }, 0]
            }
          },
          "properties": {
            "comment": "Review the investigation findings and approve the recommended action.",
            "request_payload": {
              "matched_count": "@matched.length",
              "unmatched_invoices": "@unmatched_invoices",
              "ai_investigation": "@investigation"
            }
          }
        },
        {
          "type": "custom-table",
          "properties": {
            "table": "reconciliation_log",
            "operation": "write",
            "keys": ["run_id", "timestamp"],
            "values": ["@__run_id", "@now"],
            "fields": {
              "matched_count": "@matched.length",
              "exception_count": "@unmatched_invoices.length",
              "status": "completed"
            }
          }
        }
      ]
    }
  }'

What this workflow does

Step Purpose
matcher Matches invoices to payments using exact, tolerance, and fuzzy comparison rules
loop in react mode Lets a bounded agent investigate the unmatched invoices
PbotApproval Pauses for human review when unresolved exceptions remain
custom-table Logs the run summary into durable storage

Built-in agent tools such as __complete__, __pause_for_human__, __store_memory__, __retrieve_memory__, and __log_progress__ are automatically available to every ReAct agent. Only declare your custom tools and workflow tools.

---

Step 3: Execute the workflow

POST/workflows/:id/execute

Run the workflow with your invoice and payment data.

bash
curl -X POST https://your-hyphen.example.com/workflows/{workflow_id}/execute \
  -H "X-Org-Id: your-org" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "invoices": [
        { "invoice_id": "INV-001", "vendor": "Acme Corp", "amount": 10000.00, "date": "2026-01-15" },
        { "invoice_id": "INV-002", "vendor": "Globex Inc", "amount": 4500.00, "date": "2026-01-18" },
        { "invoice_id": "INV-003", "vendor": "Initech", "amount": 7250.00, "date": "2026-01-20" },
        { "invoice_id": "INV-004", "vendor": "Umbrella Ltd", "amount": 15000.00, "date": "2026-01-22" },
        { "invoice_id": "INV-005", "vendor": "Stark Industries", "amount": 3200.00, "date": "2026-01-25" }
      ],
      "payments": [
        { "invoice_id": "INV-001", "vendor": "Acme Corp", "amount": 10000.00, "date": "2026-01-16" },
        { "invoice_id": "INV-002", "vendor": "Globex Inc", "amount": 4480.00, "date": "2026-01-19" },
        { "invoice_id": "INV-004", "vendor": "Umbrela Ltd", "amount": 15000.00, "date": "2026-01-23" },
        { "invoice_id": "INV-006", "vendor": "Wayne Enterprises", "amount": 8800.00, "date": "2026-01-27" }
      ]
    }
  }'

Response

json
{ "id": "run-123e4567-e89b-12d3-a456-426614174000", "status": "running" }

Step 4: Check status

:::api GET /runs/:runId/status Poll for status. The run pauses at PbotApproval if human review is needed. :::

bash
curl https://your-hyphen.example.com/runs/run-123e4567-e89b-12d3-a456-426614174000/status \
  -H "X-Org-Id: your-org"

You should expect:

Record Result
INV-001 matched
INV-002 matched within tolerance
INV-004 matched via fuzzy vendor name
INV-003 unmatched
INV-005 unmatched
INV-006 unmatched payment

The clear matches are handled without human review. The unresolved records move into the agent step.

Step 5: Approve the exception path

POST/approvals/:runId/:stepId

Submit the human decision. The decision becomes part of the permanent run history.

bash
curl -X POST https://your-hyphen.example.com/approvals/run-123e4567-e89b-12d3-a456-426614174000/2 \
  -H "X-Org-Id: your-org" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "comment": "Agree with the recommendation. Follow up in 30 days if still unresolved."
  }'

At that point the workflow resumes, writes its final log entry, and completes.

What this quickstart proved

You just exercised the core Hyphen runtime pattern:

  • deterministic matching
  • bounded AI reasoning
  • human review where needed
  • durable state and audit history

That is the foundation beneath higher-level authoring and embedded product surfaces.

Where to go next