Tasks

Tasks are the core unit of work in AsyncQueue. Each task represents a job to be executed asynchronously via a webhook call.

Create a task

POST /v1/tasks

Request body

Field	Type	Required	Description
queue	string	Yes	Target queue name
webhook_url	string	Yes	URL to call when the task executes
payload	object	No	JSON data to send with the webhook
delay	integer	No	Delay in seconds before the task becomes eligible for execution
priority	integer	No	Priority level (1-10, higher is processed first, default: 5)
max_retries	integer	No	Override the queue’s default retry count

Example

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue": "emails",
    "webhook_url": "https://your-app.com/webhooks/send-email",
    "payload": {"to": "[email protected]", "template": "welcome"},
    "delay": 300,
    "priority": 8
  }'

Response

{
  "id": "task_abc123",
  "queue": "emails",
  "status": "pending",
  "priority": 8,
  "delay": 300,
  "created_at": "2025-01-15T10:30:00Z"
}

Get a task

GET /v1/tasks/:task_id

Returns the current state of a task, including its execution history.

curl https://api.asyncqueue.io/v1/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "task_abc123",
  "queue": "emails",
  "status": "completed",
  "priority": 8,
  "payload": {"to": "[email protected]", "template": "welcome"},
  "attempts": [
    {
      "number": 1,
      "status": "success",
      "response_code": 200,
      "executed_at": "2025-01-15T10:35:02Z"
    }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:35:02Z"
}

List tasks

GET /v1/tasks?queue=emails&status=pending

Query parameters

Parameter	Type	Description
queue	string	Filter by queue name
status	string	Filter by status: pending, active, completed, failed
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Pagination offset

Delete a task

DELETE /v1/tasks/:task_id

Removes a pending task from the queue. Active or completed tasks cannot be deleted.

Task statuses

Status	Description
pending	Waiting in the queue (or delayed)
active	Currently being executed
completed	Webhook returned a 2xx response
failed	All retry attempts exhausted