API Reference

The Fliq API is a REST API. All requests are over HTTPS. Request and response bodies are JSON.

Base URL

https://api.fliq.sh

Authentication

Pass your API token in the Authorization header as a Bearer token. Generate tokens in Settings → API Tokens.

Authorization: Bearer fliq_sk_your_token

Jobs

Create a job

POST /jobs

{
  "url":             string,   // required
  "http_method":     string,   // optional — default "POST"
  "scheduled_at":    string,   // required — ISO 8601 UTC
  "headers":         object,   // optional
  "body":            string,   // optional
  "max_retries":     number,   // optional — default 0
  "idempotency_key": string,   // optional
  "webhook_url":     string,   // optional — URL to POST when job reaches terminal state
  "webhook_headers": object    // optional — custom headers for webhook request
}

// Response — 201 Created
{
  "id":           "job_01hx...",
  "url":          "https://yourapp.com/api/charge",
  "http_method":  "POST",
  "scheduled_at": "2026-04-01T09:00:00Z",
  "max_retries":  3,
  "status":       "scheduled",
  "created_at":   "2026-03-10T14:22:01Z"
}

Get a job

GET /jobs/{job_id}

Returns the job object with current status and execution count.

List jobs

GET /jobs?status=scheduled&limit=50&cursor=...

• status — filter by scheduled | success | failed | cancelled
• limit — max results per page (default 20, max 100)
• cursor — pagination cursor from previous response

Cancel a job

DELETE /jobs/{job_id}

Cancels a job that has not yet fired. Returns 404 if the job doesn’t exist or 409 if it has already executed.

Schedules

Create a schedule

POST /schedules

{
  "url":             string,   // required
  "http_method":     string,   // optional — default "POST"
  "cron":            string,   // required — 5-part cron expression (UTC)
  "headers":         object,   // optional
  "body":            string,   // optional
  "max_retries":     number,   // optional — default 0
  "webhook_url":     string,   // optional — inherited by spawned jobs
  "webhook_headers": object    // optional — inherited by spawned jobs
}

// Response — 201 Created
{
  "id":          "sched_01hx...",
  "url":         "https://yourapp.com/api/digest",
  "cron":        "0 8 * * 1-5",
  "status":      "active",
  "created_at":  "2026-03-10T14:22:01Z",
  "next_run_at": "2026-03-11T08:00:00Z"
}

List schedules

GET /schedules?limit=50&cursor=...

Delete a schedule

DELETE /schedules/{schedule_id}

Stops all future executions immediately. Already-queued executions for the current interval may still fire.

Webhooks

When a job has a webhook_url, Fliq POSTs a JSON payload to that URL when the job reaches a terminal state (completed, failed, or cancelled).

// Webhook payload
{
  "job_id":       "job_01hx...",
  "status":       "completed",
  "status_code":  200,
  "last_error":   null,
  "completed_at": "2026-04-01T09:00:01Z",
  "attempt_num":  1
}

• Delivery is best-effort, fire-and-forget — a webhook failure does not change the job’s status
• Webhook calls have a 10-second timeout
• Webhook calls do not consume credits
• Custom headers can be set via webhook_headers (e.g. for auth tokens)
• Schedules inherit webhook_url and webhook_headers — every spawned job gets the same webhook config

Executions

List executions for a job

GET /jobs/{job_id}/executions

// Response
{
  "executions": [
    {
      "id":           "exec_01hx...",
      "attempt_num":  1,
      "status":       "success",
      "status_code":  200,
      "duration_ms":  143,
      "executed_at":  "2026-04-01T09:00:00Z"
    }
  ]
}

Errors

All error responses follow the same shape:

{
  "error": {
    "code":    "invalid_scheduled_at",
    "message": "scheduled_at must be in the future"
  }
}

• 400 — invalid request body or parameters
• 401 — missing or invalid API token
• 403 — action not allowed on this resource
• 404 — resource not found
• 409 — conflict (e.g. cancelling an already-executed job)
• 429 — daily execution limit reached (free tier)
• 500 — something went wrong on our end