API Reference

Base URL: https://willowriverautomation.com/relay/v1

Set this in your shell for the examples below:

export BASE="https://willowriverautomation.com/relay/v1"

All responses are JSON. Errors:

{ "error": { "code": "string", "message": "string", "details": {} } }

Authentication & account

Plan limits and enforcement

Limits match the Intake Relay pricing page. Full breakdown: billing & quotas.

Usage snapshot (GET /account)

{
  "plan": "starter",
  "plan_status": "active",
  "allow_overage": false,
  "usage_period_start": "2026-05-01T00:00:00+00:00",
  "usage_period_end": "2026-06-01T00:00:00+00:00",
  "submissions": { "used": 42, "limit": 2000, "remaining": 1958 },
  "flows": { "used": 2, "limit": 5 },
  "webhooks": { "used": 1, "limit": 3 }
}

limit: null means unlimited (Growth/Scale flows, Scale submissions/webhooks). Starter and Growth can opt in to submission overage via PATCH /account/billing.

Version pinning

Intake submit and file presign require ?version=N pointing at a published flow version unless the flow explicitly allows latest intake. Missing version returns version_required (400). See Intake flows.

Webhook retries and delivery log

All plans include automatic retries (5 attempts, exponential backoff) and GET /flows/{flow_id}/webhooks/deliveries. See Webhooks.

Authentication (requests)

Management API — Authorization: Bearer <api_key>

Public intake — X-Embed-Key: <embed_key> (per-flow, safe for frontend)

Intake flows

Flow versions

Intake submissions

Submit intake

curl -X POST "$BASE/flows/$FLOW_ID/intake?version=1" \
  -H "X-Embed-Key: $EMBED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: user-abc-signup" \
  -d '{"data":{"email":"dev@acme.com","plan":"pro"}}'

Idempotency: Pass Idempotency-Key header. Duplicate keys return the original submission with idempotent_replay: true.

File uploads

Plan requirement: File uploads require Starter, Growth, or Scale. Free accounts receive uploads_not_available (403) if presign or intake submission includes file attachments.

Pass ?version=N matching your pinned published flow version. The field_id must refer to a file type field on that version.

On paid plans, presigned uploads are capped at 10 MB per file (UPLOAD_MAX_BYTES). The blob must exist in GCS before intake submission accepts the file reference. Files are stored in Google Cloud Storage under your organization prefix. Uploaded objects are automatically deleted after 60 days via bucket lifecycle policy — Intake Relay is not long-term file archival. Download or copy files to your own systems via webhooks if you need longer retention.

Scale plan: Larger per-file limits (for example video) are available by special request only, subject to custom pricing and manual configuration. Contact Willow River Automation before building flows that depend on higher limits.

Presign example

curl -X POST "$BASE/flows/$FLOW_ID/uploads/presign?version=1" \
  -H "X-Embed-Key: $EMBED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_id":"resume","filename":"cv.pdf","content_type":"application/pdf"}'

Success (200):

{
  "storage_key": "uploads/{org_id}/{flow_id}/{uuid}/cv.pdf",
  "upload_url": "https://storage.googleapis.com/...",
  "expires_at": "2026-05-21T12:00:00Z"
}

Free plan (403):

{
  "error": {
    "code": "uploads_not_available",
    "message": "File uploads are not available on the free plan. Upgrade to Starter or Growth.",
    "details": { "plan": "free", "...": "..." }
  }
}

Webhooks

System

Common errors