Getting Started

This guide walks you through creating a scheduler, enqueuing a delayed task, listing tasks, reserving and acknowledging a task, and checking scheduler health.

Prerequisites

• A HolaCloud account with API credentials.
• curl installed on your machine.

Authentication

Some endpoints require authentication via API key. Pass it using the X-API-Key header or Authorization: Bearer <key>.

Step 1: Create a Scheduler

Create a new scheduler:

1curl -X POST "https://api.hola.cloud/schedulers" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
6    "display_name": "my-scheduler"
7  }'

Expected response:

1{
2  "scheduler": {
3    "id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
4    "ready": true,
5    "scheduled": 0,
6    "inflight": 0,
7    "display_name": "my-scheduler"
8  }
9}

Use the scheduler id in subsequent requests.

Step 2: Enqueue a Task with Delay

Enqueue a task that becomes available in 60 seconds:

 1curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks" \
 2  -H "X-API-Key: YOUR_API_KEY" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "id": "task-001",
 6    "payload": {
 7      "type": "send_email",
 8      "to": "user@example.com",
 9      "template": "welcome"
10    },
11    "delay": "60s",
12    "labels": ["project:onboarding", "priority:high"]
13  }'

Expected response: HTTP 202 Accepted with an empty body.

Step 3: List Tasks

View all tasks in the scheduler:

1curl "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks"

Expected response:

 1{
 2  "scheduled": [
 3    {
 4      "id": "task-001",
 5      "future": "2025-06-21T12:01:01Z",
 6      "labels": ["project:onboarding", "priority:high"]
 7    }
 8  ],
 9  "inflight": [],
10  "scheduled_meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 },
11  "inflight_meta": { "page": 1, "per_page": 25, "total": 0, "total_pages": 0 }
12}

Step 4: Reserve and Acknowledge a Task

Once the delay has elapsed, reserve the task:

1curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "worktime": "30s"
6  }'

Expected response:

1{
2  "id": "task-001",
3  "payload": { "type": "send_email", "to": "user@example.com", "template": "welcome" },
4  "lease_expires_at": "2025-06-21T12:02:01Z",
5  "labels": ["project:onboarding", "priority:high"]
6}

Process the task, then acknowledge (delete) it:

1curl -X DELETE "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001" \
2  -H "X-API-Key: YOUR_API_KEY"

Expected response: HTTP 204 No Content.

Step 5: Check Scheduler Health

Verify the scheduler is healthy:

1curl "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health"

Expected response:

1{
2  "status": "ok",
3  "ready": true,
4  "scheduled": 0,
5  "inflight": 0,
6  "scheduler_id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
7}

Next Steps

• Learn how to manage schedulers, including updates and monitoring, in Managing Schedulers.
• Dive deeper into the task lifecycle — including lease extension, reschedule, and SSE streaming — in Task Lifecycle.