API Documentation

TaskFlow Queue is an HTTP-based async job queue. All endpoints accept and return JSON.

Base URL: https://taskflowq.com

Getting Started

curl -X POST https://taskflowq.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

# → {"api_key": "tfq_abc123...", "tier": "free"}

Authentication

Pass your API key in the X-API-Key header on every request. Keys follow the format tfq_<random>. Lost your key? Use the recover endpoint.

curl https://taskflowq.com/api/jobs \
  -H "X-API-Key: tfq_abc123..."

API Endpoints

POST/api/auth/registerAuth: None

Request Body

{ "email": "[email protected]" }

Response / Example

{ "api_key": "tfq_abc123...", "tier": "free" }

curl

curl -X POST https://taskflowq.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

POST/api/auth/recoverAuth: None

Recover your API key via email.

Request Body

{ "email": "[email protected]" }

Response / Example

{ "message": "If the email exists, a recovery email has been sent." }

curl

curl -X POST https://taskflowq.com/api/auth/recover \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

POST/api/jobsAuth: X-API-Key

Enqueue a new async job.

Request Body

{
  "task_url": "https://yourapp.com/process",  // required
  "payload": { "key": "value" },
  "max_tries": 3,
  "priority": 0,
  "delay_ms": 0
}

Response / Example

{ "job_id": "01JOB...", "status": "pending" }

curl

curl -X POST https://taskflowq.com/api/jobs \
  -H "X-API-Key: tfq_abc123" \
  -H "Content-Type: application/json" \
  -d '{"task_url": "https://yourapp.com/hook", "max_tries": 5}'

GET/api/jobs/:idAuth: X-API-Key

Get the status and details of a job.

Response / Example

{
  "job_id": "01JOB...",
  "status": "pending|processing|completed|failed|dead_letter",
  "task_url": "https://yourapp.com/process",
  "attempts": 1,
  "created_at": "2024-01-15T10:00:00Z"
}

curl

curl https://taskflowq.com/api/jobs/01JOB... \
  -H "X-API-Key: tfq_abc123"

POST/api/jobs/:id/callbackAuth: Internal

Internal endpoint called by the worker to deliver job results to your task_url. Not called directly.

Response / Example

# Your task_url receives:
POST https://yourapp.com/process
X-TaskFlow-Signature: sha256=<hmac>
X-TaskFlow-Job-Id: 01JOB...

{ "job_id": "01JOB...", "payload": {...}, "attempt": 1 }

curl

# Verify the signature in your handler:
import hmac, hashlib
sig = request.headers['X-TaskFlow-Signature']
expected = 'sha256=' + hmac.new(
    YOUR_SECRET.encode(), request.body, hashlib.sha256
).hexdigest()
assert hmac.compare_digest(sig, expected)

POST/api/jobs/:id/retryAuth: X-API-Key

Manually retry a failed or dead-letter job.

Response / Example

{ "job_id": "01JOB...", "status": "pending" }

curl

curl -X POST https://taskflowq.com/api/jobs/01JOB.../retry \
  -H "X-API-Key: tfq_abc123"

POST/api/stripe/checkoutAuth: X-API-Key

Create a Stripe Checkout session for Pro or Team upgrade.

Request Body

{ "tier": "pro" }

Response / Example

{ "checkout_url": "https://checkout.stripe.com/..." }

curl

curl -X POST https://taskflowq.com/api/stripe/checkout \
  -H "X-API-Key: tfq_abc123" \
  -H "Content-Type: application/json" \
  -d '{"tier": "pro"}'

Callback Flow

When the worker processes your job, it POSTs to your task_url with an HMAC-SHA256 signature. Always verify this signature before processing.

# Python: verify callback signature
import hmac, hashlib

def verify(request, job_secret: str) -> bool:
    sig = request.headers.get('X-TaskFlow-Signature', '')
    body = request.get_data()
    expected = 'sha256=' + hmac.new(
        job_secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

Rate Limits

Limits are per API key, reset daily at midnight UTC.

Tier	Jobs/Day	Max Retries	Priority
Free	1,000	3	Standard
Pro	50,000	10	0–100
Team	500,000	10	0–100

Error Codes

Code	HTTP	Description
VALIDATION_ERROR	400	Request body failed schema validation.
INVALID_API_KEY	401	Missing or invalid X-API-Key header.
RATE_LIMIT_EXCEEDED	429	Daily job limit reached for your tier.
NOT_FOUND	404	Job ID not found or does not belong to your account.
CONFLICT	409	Idempotency key collision — job already exists with this key.
INTERNAL_ERROR	500	Unexpected server error. Retry with exponential backoff.

Code Examples

Python

import requests

API_KEY = "tfq_your_key"
BASE = "https://taskflowq.com"

# Enqueue a job
resp = requests.post(f"{BASE}/api/jobs",
    headers={"X-API-Key": API_KEY},
    json={
        "task_url": "https://yourapp.com/process",
        "payload": {"doc_id": "abc"},
        "max_tries": 5,
        "priority": 80,
    }
)
job_id = resp.json()["job_id"]

# Check status
status = requests.get(f"{BASE}/api/jobs/{job_id}",
    headers={"X-API-Key": API_KEY}
).json()
print(status["status"])  # "pending" | "completed" | ...

TypeScript

const API_KEY = "tfq_your_key";
const BASE = "https://taskflowq.com";

const res = await fetch(`${BASE}/api/jobs`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    task_url: "https://yourapp.com/process",
    payload: { docId: "abc" },
    max_tries: 5,
    priority: 80,
  }),
});
const { job_id } = await res.json();
console.log("Enqueued:", job_id);

Billing

Upgrade to Pro ($9/mo) or Team ($29/mo) via Stripe Checkout.

curl -X POST https://taskflowq.com/api/stripe/checkout \
  -H "X-API-Key: tfq_abc123" \
  -H "Content-Type: application/json" \
  -d '{"tier": "pro"}'

# → {"checkout_url": "https://checkout.stripe.com/..."}

See the full pricing page for tier comparison.