FlowynBETA
LoginSign up

Durable HTTP Jobs

Stores an HTTP request, executes it on managed workers, retries failures within a finite policy, and keeps every attempt with a terminal status.

What durable http jobs does

Stores an HTTP request, executes it on managed workers, retries failures within a finite policy, and keeps every attempt with a terminal status.

When to use durable http jobs

  • Calling a flaky third-party API
  • Work that must outlive the web request
  • Calling an agent's HTTP endpoint with retries

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/jobs

Request

Send an Idempotency-Key so a retried request cannot create a duplicate. The body is JSON.

curl -X POST https://api.flowyn.dev/v1/jobs \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-invoice-881" \
  -d '{
    "url": "https://api.example.com/reports/generate",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"report\":\"monthly\"}",
    "timeout_ms": 10000,
    "max_attempts": 5
  }'

Response

Flowyn returns HTTP 202. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "id": "6a2f1c9e-8b4d-4f3a-a5e7-2c9d0b1e4f83",
  "environment": "test",
  "kind": "http",
  "status": "queued",
  "method": "POST",
  "url": "https://api.example.com/reports/generate",
  "attempt_count": 0,
  "max_attempts": 5,
  "run_at": "2026-09-30T09:14:02Z",
  "request_id": "req_5f2a9c1e7b3d4a6f8e0c2b1d",
  "created_at": "2026-09-30T09:14:02Z"
}

Lifecycle

  1. POST /v1/jobs stores the call and returns HTTP 202. Nothing has been sent yet.
  2. A worker claims the job with a lease and makes the request.
  3. A 2xx completes the job. A timeout, connection error, 408, 429, or 5xx records a failed attempt and schedules a retry.
  4. Other 4xx responses fail the job without a retry.
  5. When every attempt fails, the job ends exhausted. Read the attempts with GET /v1/jobs/{id}/attempts.

Status values

StatusMeaning
queuedStored, waiting for a worker.
delayedWaiting for run_at or a retry delay.
runningAn attempt is in flight.
retryingThe last attempt failed and another is scheduled.
completedA 2xx response was received.
failedA response that is not retried, such as a 404.
exhaustedEvery attempt failed.
cancelledCancelled with POST /v1/jobs/{id}/cancel.

Retries

The wait doubles from about one second with ±20% variation, capped at five minutes. A Retry-After header is honoured.

Idempotency

Send Idempotency-Key on create. Each outbound attempt carries Idempotency-Key: <job id> so the destination can deduplicate.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • timeout_ms 100–30,000 (default 10,000)
  • max_attempts 1–20 (default 5)
  • body is a string of up to 65,536 characters
  • Up to 16 headers

Read it back

Keep the id and read the resource whenever you need its current state.

bash
curl https://api.flowyn.dev/v1/jobs/6a2f1c9e-8b4d-4f3a-a5e7-2c9d0b1e4f83 \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Next step

Run the same call on a cron with Schedules.