Workflows

A Workflow names an HTTPS handler that your own service exposes. A Run is one execution of it: Sylphx calls the handler with a signed request, records what it answers, and retries it with backoff until the Run closes. A Run survives deploys and restarts, and a delayed start is a durable timer.

Everything is under https://api.sylphx.com/v1/orgs/{org}/projects/{project}/envs/{env}/, and an environment outside the key's scope answers 404.

#1. Declare the Workflow

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows?workflow_id=hire-screening" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"handlerUri":"https://app.example.com/api/sylphx/workflows","retryPolicy":{"maxAttempts":5},"timeouts":{"invocationTimeout":"120s"}}}'

The handler must be https:// on port 443 and resolve to a public address. By default a call is retried up to 10 times with a 1 second backoff that doubles to 600 seconds, and a Run may last 30 days. A Run pins the handler it started with, so later edits affect new Runs only.

#2. Start a Run

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/hire-screening/runs?run_id=applicant-8f2c" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"input":{"applicantId":"8f2c"},"startDelay":"900s"}'

const run = await sylphx.workflows.runs.create({
  parent: 'orgs/acme/projects/shop/envs/production/workflows/hire-screening',
  runId: 'applicant-8f2c',
  run: { input: { applicantId: '8f2c' }, startDelay: '900s' },
})

run_id is your business key. Starting the same run_id with the same input returns the existing Run with 200 and Sylphx-Idempotent-Replay: true; a different input under the same id is 409. startDelay (at most 365 days) delays the first call to your handler.

#3. Answer the handler

Your handler receives a POST signed with a key you verify against https://api.sylphx.com/.well-known/workflows-jwks.json. A plain 2xx answer completes the Run, with a JSON body as its output, so a handler that just does the work needs nothing more. A 400, 401, 403, 404, 410 or 422 fails the Run with no retry. A 408, 409, 425, 429, a 5xx or a dropped connection is retried under the Workflow's retry policy.

#4. Read the Run back

curl "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/hire-screening/runs/applicant-8f2c" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"

state is running, succeeded, failed, cancelled or timed_out. To block until it closes, call POST …/runs/{run}:wait with {"timeout":"30s"}; to stop it, POST …/runs/{run}:cancel. A Run is metered as workflows.actions: one for its start and one for each attempt that reached your handler.

• The workflows collection
• The runs collection