Skip to main content

Quick Start

This guide walks you through creating a gate, submitting payloads, and seeing validation in action.

Prerequisites​

  • A Rynko account (free tier includes 500 Flow runs/month)
  • An API key — create one in Settings > API Keys in the dashboard

Step 1: Create a Gate​

A gate defines what data you expect and how to validate it.

curl -X POST https://api.rynko.dev/api/flow/gates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Ticket",
    "schema": {
      "type": "object",
      "properties": {
        "ticketId": { "type": "string", "required": true },
        "priority": { "type": "string", "required": true, "allowedValues": ["low", "medium", "high", "critical"] },
        "summary": { "type": "string", "required": true, "minLength": 10, "maxLength": 500 },
        "estimatedHours": { "type": "number", "required": false, "min": 0.5, "max": 100 }
      }
    },
    "businessRules": [
      {
        "id": "rule_critical_estimate",
        "name": "Critical tickets need estimates",
        "expression": "priority != \"critical\" || estimatedHours > 0",
        "errorMessage": "Critical tickets must include an estimated hours value",
        "enabled": true
      }
    ]
  }'

The response includes the gate's id, shortId (e.g., fgate_a1b2c3d4), and slug (e.g., support-ticket). You can use any of these to reference the gate.

Dashboard Alternative

You can also create gates in the Flow dashboard using the visual gate configurator with a schema builder, business rule editor, and live preview.

Step 2: Submit a Valid Payload​

Submit a payload to validate it against the gate's schema and rules:

curl -X POST https://api.rynko.dev/api/flow/gates/support-ticket/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ticketId": "TICK-001",
    "priority": "high",
    "summary": "Login page returns 500 error for SSO users",
    "estimatedHours": 4
  }'

Successful response:

{
  "success": true,
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "shortId": "frun_a1b2c3d4",
  "status": "validated",
  "validation_id": "v_abc123...",
  "validated_payload": {
    "ticketId": "TICK-001",
    "priority": "high",
    "summary": "Login page returns 500 error for SSO users",
    "estimatedHours": 4
  },
  "layers": {
    "schema": "pass",
    "business_rules": "pass"
  }
}

The validation_id is a tamper-proof token. Pass it to downstream systems so they can verify the payload hasn't been modified.

Step 3: Submit an Invalid Payload​

See what happens when validation fails. This payload violates the business rule (critical priority without estimated hours) and has an invalid priority value:

curl -X POST https://api.rynko.dev/api/flow/gates/support-ticket/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ticketId": "TICK-002",
    "priority": "urgent",
    "summary": "Too short"
  }'

Failure response (HTTP 422):

{
  "success": false,
  "status": "validation_failed",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Payload failed schema validation",
    "layer": "schema",
    "details": [
      {
        "field": "priority",
        "message": "Value must be one of: low, medium, high, critical",
        "code": "invalid_enum"
      },
      {
        "field": "summary",
        "message": "Must be at least 10 characters",
        "code": "min_length"
      }
    ]
  },
  "layers": {
    "schema": "fail",
    "business_rules": "skipped"
  }
}
info

Validation failures still create a run record and count toward your usage quota. This is intentional — it provides an audit trail of all submission attempts.

Step 4: Dry-Run Test​

Use the test endpoint to validate a payload without creating a run or consuming quota:

curl -X POST https://api.rynko.dev/api/flow/gates/support-ticket/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ticketId": "TICK-003",
    "priority": "critical",
    "summary": "Payment processing is down for all users",
    "estimatedHours": 8
  }'

Test response:

{
  "valid": true,
  "durationMs": 4.2,
  "steps": [
    {
      "name": "Schema Validation",
      "status": "pass",
      "durationMs": 1.1,
      "errors": null
    },
    {
      "name": "Critical tickets need estimates",
      "ruleId": "rule_critical_estimate",
      "status": "pass",
      "durationMs": 0.3,
      "expression": "priority != \"critical\" || estimatedHours > 0"
    }
  ]
}

The test endpoint runs the same validation pipeline but returns detailed step-by-step results. Step status values: pass, fail, error, skipped.

Next Steps​

  • Gates — Learn about schema types, constraints, business rule syntax, and advanced configuration
  • Runs — Understand the full run lifecycle and status flow
  • Approvals — Add human review before delivery
  • MCP Integration — Let AI agents validate through natural conversation
  • API Reference — Complete endpoint documentation