Create a task

POST /tasks

Schedule an HTTP request for a future time.

Request fields

Field	Type	Description
`execute_at`	string	When to run (RFC3339, UTC). Must be in the future. Exactly one of `execute_at` or `execute_in` is required.
`execute_in`	string	How long from now to run, as a positive Go duration (`"5m"`, `"2h"`). The server stores the resolved absolute time. Exactly one of `execute_at` or `execute_in` is required.
`url`	string	Required. Where to send the request.
`method`	string	Optional HTTP verb: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` (default `POST`). `GET`/`HEAD` send no body.
`headers`	object	Optional map of HTTP headers to send.
`payload`	any	Optional body: JSON object, string, or form data.
`retries`	int	Optional number of retries.
`retry_interval`	int	Optional ms between retries (default `2000`).
`retry_mode`	string	Optional retry timing: `fixed` (default) or `exponential` (backoff + jitter). See Retries.
`schedule`	string	Optional recurrence interval as a Go duration (`"15m"`, `"2h"`). After each fire, a fresh one-shot task is enqueued at `fire_time + schedule`. See Recurrence.

Recurrence

Set schedule to an interval and the task becomes recurring: each time it fires, Schedy enqueues a fresh one-shot task at fire_time + schedule. The interval is a Go duration - "30s", "15m", "2h" - and must be positive.

curl -X POST http://localhost:8080/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret" \
  -d '{
    "execute_at": "2030-05-26T15:00:00Z",
    "url": "https://example.com/heartbeat",
    "schedule": "15m"
  }'

To stop a recurring task, cancel the current pending task - the chain stops because no successor is enqueued.

This is interval-only recurrence, deliberately not cron. There is no cron syntax, no timezones, no DST handling, and no catch-up for missed fires - the next fire is always measured forward from the moment the task actually ran. If you need calendar scheduling, run cron on your side and POST one-shot tasks.

Example

curl -X POST http://localhost:8080/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret" \
  -d '{
    "url": "https://example.com/webhook",
    "execute_at": "2030-01-01T09:00:00Z",
    "payload": { "event": "user.created" }
  }'

const res = await fetch("http://localhost:8080/tasks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-secret",
  },
  body: JSON.stringify({
    url: "https://example.com/webhook",
    execute_at: "2030-01-01T09:00:00Z",
    payload: { event: "user.created" },
  }),
});

const task = await res.json();
console.log(task);

import requests

resp = requests.post(
    "http://localhost:8080/tasks",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-secret",
    },
    json={
        "url": "https://example.com/webhook",
        "execute_at": "2030-01-01T09:00:00Z",
        "payload": {"event": "user.created"},
    },
)

print(resp.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"url":        "https://example.com/webhook",
		"execute_at": "2030-01-01T09:00:00Z",
		"payload":    map[string]any{"event": "user.created"},
	})

	req, _ := http.NewRequest("POST", "http://localhost:8080/tasks", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "your-secret")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}

The X-API-Key header is only required when the server is started with SCHEDY_API_KEY set; otherwise you can omit it. Send an optional Idempotency-Key header to make retries safe - a repeat with the same key returns the task the first call created instead of scheduling a duplicate. See Idempotency. Payloads are flexible - a JSON object (default Content-Type: application/json), form data (application/x-www-form-urlencoded), or plain text; set the Content-Type header to match.

Responses

Response	Meaning
`201 Created`	Task scheduled; returns the task.
`200 OK`	Idempotent match; returns the existing pending task.
`400 Bad Request`	Invalid body, bad time format, or time in the past.

Tasks

System

Request fields

Recurrence

Example

Responses

​Request fields

​Recurrence

​Example

​Responses

Request fields

Recurrence

Example

Responses