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:
curl -X POST "https://api.hola.cloud/schedulers" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"display_name": "my-scheduler"
}'POST /schedulers HTTP/1.1
Host: api.hola.cloud
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"display_name": "my-scheduler"
}package main
import (
"fmt"
"io"
"net/http"
"encoding/json"
"strings"
)
func main() {
payload := map[string]any{"display_name": "my-scheduler", "id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
bodyBytes, err := json.Marshal(payload)
if err != nil {
panic(err)
}
body := string(bodyBytes)
req, err := http.NewRequest("POST", "https://api.hola.cloud/schedulers", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("X-API-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$payload = ['display_name' => 'my-scheduler', 'id' => 'sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890'];
$body = json_encode($payload);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/schedulers',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'X-API-Key: YOUR_API_KEY',
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
import json
headers = {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {"display_name": "my-scheduler", "id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
body = json.dumps(payload)
response = requests.request(
"POST",
"https://api.hola.cloud/schedulers",
headers=headers,
data=body
)
print(response.text)
const payload = {"display_name": "my-scheduler", "id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890"};
const response = await fetch("https://api.hola.cloud/schedulers", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
console.log(await response.text());
const payload = {"display_name": "my-scheduler", "id": "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890"};
const response = await fetch("https://api.hola.cloud/schedulers", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.List;
public class Main {
public static void main(String[] args) throws Exception {
var payload = Map.of("display_name", "my-scheduler", "id", "sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890");
var body = new ObjectMapper().writeValueAsString(payload);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/schedulers"))
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}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:
curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "task-001",
"payload": {
"type": "send_email",
"to": "user@example.com",
"template": "welcome"
},
"delay": "60s",
"labels": ["project:onboarding", "priority:high"]
}'POST /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks HTTP/1.1
Host: api.hola.cloud
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"id": "task-001",
"payload": {
"type": "send_email",
"to": "user@example.com",
"template": "welcome"
},
"delay": "60s",
"labels": ["project:onboarding", "priority:high"]
}package main
import (
"fmt"
"io"
"net/http"
"encoding/json"
"strings"
)
func main() {
payload := map[string]any{"delay": "60s", "id": "task-001", "labels": []any{"project:onboarding", "priority:high"}, "payload": map[string]any{"template": "welcome", "to": "user@example.com", "type": "send_email"}}
bodyBytes, err := json.Marshal(payload)
if err != nil {
panic(err)
}
body := string(bodyBytes)
req, err := http.NewRequest("POST", "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("X-API-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$payload = ['delay' => '60s', 'id' => 'task-001', 'labels' => ['project:onboarding', 'priority:high'], 'payload' => ['template' => 'welcome', 'to' => 'user@example.com', 'type' => 'send_email']];
$body = json_encode($payload);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'X-API-Key: YOUR_API_KEY',
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
import json
headers = {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {"delay": "60s", "id": "task-001", "labels": ["project:onboarding", "priority:high"], "payload": {"template": "welcome", "to": "user@example.com", "type": "send_email"}}
body = json.dumps(payload)
response = requests.request(
"POST",
"https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks",
headers=headers,
data=body
)
print(response.text)
const payload = {"delay": "60s", "id": "task-001", "labels": ["project:onboarding", "priority:high"], "payload": {"template": "welcome", "to": "user@example.com", "type": "send_email"}};
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
console.log(await response.text());
const payload = {"delay": "60s", "id": "task-001", "labels": ["project:onboarding", "priority:high"], "payload": {"template": "welcome", "to": "user@example.com", "type": "send_email"}};
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.List;
public class Main {
public static void main(String[] args) throws Exception {
var payload = Map.of("delay", "60s", "id", "task-001", "labels", List.of("project:onboarding", "priority:high"), "payload", Map.of("template", "welcome", "to", "user@example.com", "type", "send_email"));
var body = new ObjectMapper().writeValueAsString(payload);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks"))
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response: HTTP 202 Accepted with an empty body.
Step 3: List Tasks
View all tasks in the scheduler:
curl "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks"GET /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks HTTP/1.1
Host: api.hola.cloud
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks", nil)
if err != nil {
panic(err)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
response = requests.request(
"GET",
"https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks"
)
print(response.text)
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks", {
method: "GET"
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks", {
method: "GET"
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}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:
curl -X POST "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"worktime": "30s"
}'POST /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve HTTP/1.1
Host: api.hola.cloud
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"worktime": "30s"
}package main
import (
"fmt"
"io"
"net/http"
"encoding/json"
"strings"
)
func main() {
payload := map[string]any{"worktime": "30s"}
bodyBytes, err := json.Marshal(payload)
if err != nil {
panic(err)
}
body := string(bodyBytes)
req, err := http.NewRequest("POST", "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("X-API-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$payload = ['worktime' => '30s'];
$body = json_encode($payload);
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'X-API-Key: YOUR_API_KEY',
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
import json
headers = {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {"worktime": "30s"}
body = json.dumps(payload)
response = requests.request(
"POST",
"https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve",
headers=headers,
data=body
)
print(response.text)
const payload = {"worktime": "30s"};
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
console.log(await response.text());
const payload = {"worktime": "30s"};
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.List;
public class Main {
public static void main(String[] args) throws Exception {
var payload = Map.of("worktime", "30s");
var body = new ObjectMapper().writeValueAsString(payload);
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/reserve"))
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}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:
curl -X DELETE "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001" \
-H "X-API-Key: YOUR_API_KEY"DELETE /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001 HTTP/1.1
Host: api.hola.cloud
X-API-Key: YOUR_API_KEY
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("DELETE", "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001", nil)
if err != nil {
panic(err)
}
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'X-API-Key: YOUR_API_KEY',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
headers = {
"X-API-Key": "YOUR_API_KEY",
}
response = requests.request(
"DELETE",
"https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001",
headers=headers
)
print(response.text)
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001", {
method: "DELETE",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001", {
method: "DELETE",
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks/task-001"))
.method("DELETE", HttpRequest.BodyPublishers.noBody())
.header("X-API-Key", "YOUR_API_KEY")
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Expected response: HTTP 204 No Content.
Step 5: Check Scheduler Health
Verify the scheduler is healthy:
curl "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health"GET /schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health HTTP/1.1
Host: api.hola.cloud
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health", nil)
if err != nil {
panic(err)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
responseBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(responseBody))
}
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
echo $response;
import requests
response = requests.request(
"GET",
"https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health"
)
print(response.text)
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health", {
method: "GET"
});
console.log(await response.text());
const response = await fetch("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health", {
method: "GET"
});
const text = await response.text();
console.log(text);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.hola.cloud/schedulers/sched-a1b2c3d4-e5f6-7890-abcd-ef1234567890/health"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}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.
Comments