Runs

A run represents a single payload submission to a gate. Each run goes through validation, optional rendering, optional approval, and optional delivery.

Submitting a Run

Submit a payload to a gate's validate endpoint:

curl -X POST https://api.rynko.dev/api/flow/gates/GATE_ID/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldA": "value",
    "fieldB": 42
  }'

You can also submit via the runs endpoint with explicit payload wrapping:

curl -X POST https://api.rynko.dev/api/flow/gates/GATE_ID/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "fieldA": "value",
      "fieldB": 42
    },
    "metadata": {
      "agentId": "agent-001",
      "sessionId": "sess-abc"
    }
  }'

The metadata field is stored on the run for your reference but is not validated.

---

Validation Pipeline

When a payload is submitted, it passes through these checks in order:

1. Gate status — must be active
2. Rate limit — per-gate submissions/minute threshold
3. Circuit breaker — rejects if the gate's circuit is open
4. Quota — checks remaining run allocation for the billing period
5. Body size — 1 MB hard limit on payload size
6. Schema validation — type checking, required fields, constraints
7. Business rules — cross-field expression evaluation (only if schema passes)

If any step fails, the run is created with validation_failed status and the error details are returned.

---

Response Format

Successful Validation

{
  "success": true,
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "shortId": "frun_a1b2c3d4",
  "status": "validated",
  "validation_id": "v_abc123...",
  "validated_payload": { ... },
  "layers": {
    "schema": "pass",
    "business_rules": "pass"
  }
}

Validation Failure

{
  "success": false,
  "status": "validation_failed",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Payload failed schema validation",
    "layer": "schema",
    "details": [
      { "field": "email", "message": "Invalid email format", "code": "format" },
      { "field": "amount", "message": "Must be at least 0", "code": "minimum" }
    ]
  },
  "layers": {
    "schema": "fail",
    "business_rules": "skipped"
  }
}

Business Rule Failure

{
  "success": false,
  "status": "validation_failed",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Payload failed business rule validation",
    "layer": "business_rules",
    "details": [
      {
        "field": null,
        "message": "End date must be after start date",
        "code": "business_rule",
        "rule_id": "rule_date_order"
      }
    ]
  },
  "layers": {
    "schema": "pass",
    "business_rules": "fail"
  }
}

Rate Limited (HTTP 429)

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for this gate"
  },
  "retryAfter": 12
}

---

Run Status Lifecycle

A run progresses through these statuses:

validated → rendering → rendered → pending_approval → approved → delivering → delivered → completed

Each step is optional — if rendering is disabled, approval is auto, and no delivery channels are configured, a run goes directly from validated to completed.

Terminal Statuses

Status	Meaning
completed	All steps succeeded
validation_failed	Schema or business rule validation failed
render_failed	Document rendering failed
rejected	An approver rejected the run
delivery_failed	All delivery channels failed

All Statuses

Status	Description
validating	Validation in progress (reserved)
validated	Passed all validation layers
rendering	Document rendering queued or in progress
rendered	Document rendered successfully
pending_approval	Waiting for approver decision
approved	Approved by an approver
delivering	Webhook delivery in progress
delivered	Delivery completed (all or partial success)
completed	Terminal success
validation_failed	Terminal — validation failed
render_failed	Terminal — rendering failed
rejected	Terminal — approval rejected
delivery_failed	Terminal — all delivery channels failed

---

Check-and-Lock Verification

The validation_id returned on successful validation is a tamper-proof token. Downstream systems can verify that a payload was validated and hasn't been modified:

# This is available via the MCP verify_validation tool
# or programmatically by comparing the validation_id

The validation_id is deterministic — it's derived from the payload content. If the payload changes, the validation ID won't match.

---

Listing Runs

All Runs in Workspace

curl "https://api.rynko.dev/api/flow/runs?page=1&limit=25&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Runs for a Specific Gate

curl "https://api.rynko.dev/api/flow/gates/GATE_ID/runs?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	25	Results per page (1-100)
status	string	—	Filter by status
source	string	—	Filter by source: mcp or rest
sortBy	string	createdAt	Sort field: createdAt or status
sortOrder	string	desc	Sort direction: asc or desc

---

Get Run Details

curl https://api.rynko.dev/api/flow/runs/RUN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes the full run record: status, input payload, validation result, render artefact URL (if rendered), approval status, and delivery status.

---

Run Sources

Every run is tagged with its source:

Source	Description
mcp	Submitted via MCP tools (AI agent)
rest	Submitted via REST API

Filter by source in run listings to separate agent-initiated runs from programmatic submissions.

---

Important Notes

• Validation failures are billable — a run record is created even when validation fails, and it counts toward your quota
• Payload size limit — 1 MB maximum per submission (HTTP 413 if exceeded)
• Archived runs — older runs may be archived with inputPayload and renderArtefactUrl cleared, but metadata and status are preserved