Buffers

A Buffer is a rate-limited HTTP request queue. Define a target endpoint once, push items into the buffer, and Fliq drains them at your configured rate — no infrastructure to manage.

When to use buffers

Use buffers when you need to send many requests to the same endpoint without overwhelming it. Common use cases:

• Draining a webhook backlog to a third-party API with rate limits
• Fanning out notifications to a single downstream service
• Batch-processing event payloads at a controlled pace

Creating a buffer

A buffer stores the target URL, HTTP method, default headers, and rate limit. Every item pushed into the buffer inherits this configuration.

Fields

{
  "name":            string,   // required — unique per user (max 256 chars)
  "url":             string,   // required — the endpoint Fliq will call
  "method":          string,   // optional — GET | POST | PUT | PATCH | DELETE (default: POST)
  "headers":         object,   // optional — default headers for all items
  "timeout_seconds": number,   // optional — 1–3600 (default: 30)
  "rate_limit":      number,   // optional — items per drain cycle, 1–1000 (default: 10)
  "max_retries":     number,   // optional — 0–20 (default: 3)
  "backoff":         string,   // optional — "exponential" | "linear" (default: "exponential")
  "webhook_url":     string,   // optional — notified on item completion/failure
  "webhook_headers": object    // optional — headers for webhook calls
}

Example

curl -X POST https://api.fliq.sh/buffers \
  -H "Authorization: Bearer fliq_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-webhooks",
    "url": "https://api.example.com/webhooks/stripe",
    "method": "POST",
    "headers": { "Authorization": "Bearer sk_live_..." },
    "rate_limit": 5,
    "max_retries": 3,
    "backoff": "exponential"
  }'

Pushing items

Each item represents a single HTTP request to be sent. Items inherit the buffer's URL, method, and headers — you only need to provide the body and any header overrides.

Fields

{
  "body":    string,   // optional — request body
  "headers": object    // optional — merged with buffer defaults (item wins on conflict)
}

Example

curl -X POST https://api.fliq.sh/buffers/BUFFER_ID/items \
  -H "Authorization: Bearer fliq_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "body": "{\"event\": \"payment.completed\", \"amount\": 4999}",
    "headers": { "X-Idempotency-Key": "pay_abc123" }
  }'

How draining works

Fliq's scheduler polls for active buffers every second. On each cycle it claims up to rate_limit pending items per buffer and executes them sequentially. This guarantees your target endpoint never receives more than rate_limit requests per second.

Item lifecycle

• pending — queued, waiting to be claimed
• running — HTTP request in flight
• completed — endpoint returned 2xx
• failed — all retries exhausted without a 2xx

Rate limit handling (429)

If the target endpoint returns 429 Too Many Requests, Fliq reschedules the item using the Retry-After header (default: 60 seconds). This does not count as a retry attempt — the item keeps its full retry budget.

Retries and backoff

Non-2xx responses (other than 429) consume a retry. The delay before the next attempt depends on the backoff strategy:

• Exponential (default) — 30s × 2^attempt, capped at 1 hour, with ±25% jitter
• Linear— 30s × (attempt + 1)

Pause and resume

You can pause a buffer to temporarily stop draining without losing queued items. New items can still be pushed while paused — they will be processed when you resume.

# Pause
curl -X POST https://api.fliq.sh/buffers/BUFFER_ID/pause \
  -H "Authorization: Bearer fliq_sk_..."

# Resume
curl -X POST https://api.fliq.sh/buffers/BUFFER_ID/resume \
  -H "Authorization: Bearer fliq_sk_..."

Monitoring items

List items to check their status, or fetch a single item for details including the HTTP status code and any error message.

# List all items (supports ?status=pending&limit=20&cursor=...)
curl https://api.fliq.sh/buffers/BUFFER_ID/items \
  -H "Authorization: Bearer fliq_sk_..."

# Get a single item
curl https://api.fliq.sh/buffers/BUFFER_ID/items/ITEM_ID \
  -H "Authorization: Bearer fliq_sk_..."

Crash recovery

If a worker crashes mid-execution, the item's heartbeat stops updating. A background reaper detects stale items within 30 seconds and either reschedules them (if retries remain) or marks them as failed. No manual intervention needed.