API Reference

Cron Scheduler

Schedule and manage recurring HTTP jobs with cron expressions

Schedule and manage recurring HTTP jobs using standard cron expressions, without running your own scheduler infrastructure. The Cron Service handles job execution, retry with exponential backoff, overlap policies, and full execution history — replacing custom cron setups with a managed API that scales with your workload.

cron expressionsHTTP callbacksexecution historyretry policies

Endpoint

GET /v1/cron/jobs

Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.

Open Swagger UI (interactive docs)

Request

{
  "name": "health-check",
  "url": "https://example.com/health",
  "method": "GET",
  "schedule": "*/5 * * * *",
  "headers": {
    "Authorization": "Bearer token"
  }
}

Request Fields

Field	Type	Description
`name`	`string`	Field value
`url`	`string`	Target URL
`method`	`string`	Field value
`schedule`	`string`	Field value
`headers`	`object`	Nested object with properties

Response

{
  "id": 1,
  "name": "health-check",
  "url": "https://example.com/health",
  "schedule": "*/5 * * * *",
  "status": "ACTIVE",
  "lastRun": "2026-03-25T14:25:00Z",
  "nextRun": "2026-03-25T14:30:00Z",
  "lastStatus": 200
}

Response Fields

Field	Type	Description
`id`	`string`	Unique identifier
`name`	`string`	Field value
`url`	`string`	Target URL
`schedule`	`string`	Field value
`status`	`string`	Field value
`lastRun`	`string`	Field value
`nextRun`	`string`	Field value
`lastStatus`	`integer`	Field value

Error Codes

Status	Meaning
`200`	Request completed successfully
`400`	Bad request — invalid or missing parameters
`401`	Missing or invalid `X-API-Key` header
`429`	Rate limit exceeded — check `Retry-After` header
`500`	Internal server error

Common Error Scenarios

400 Invalid cron expression

Request that triggers this:

{"schedule": "invalid"}

Error response:

{"type": "/problems/validation-error", "title": "Invalid Cron Expression", "status": 400, "detail": "'invalid' is not a valid cron expression"}

How to fix: Use valid cron syntax (e.g., '0 9 * * *' for 9 AM daily). Check cron expression format in documentation.

503 Webhook endpoint unreachable

Request that triggers this:

{"schedule": "0 * * * *", "webhookUrl": "https://unreachable.example.com"}

Error response:

{"type": "/problems/service-unavailable", "title": "Webhook Unreachable", "status": 503, "detail": "Could not reach webhook endpoint at scheduled time"}

How to fix: Ensure webhook endpoint is accessible and responding. Verify domain name and firewall rules.

Code Examples

curl -X POST /v1/cron/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "name": "health-check",
  "url": "https://example.com/health",
  "method": "GET",
  "schedule": "*/5 * * * *",
  "headers": {
    "Authorization": "Bearer token"
  }
}'

// Node.js (18+) or modern browser
const response = await fetch("/v1/cron/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "health-check",
    "url": "https://example.com/health",
    "method": "GET",
    "schedule": "*/5 * * * *",
    "headers": {
        "Authorization": "Bearer token"
    }
}),
});

const data = await response.json();
console.log(response.status, data);

import requests

response = requests.post(
    "/v1/cron/jobs",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "name": "health-check",
    "url": "https://example.com/health",
    "method": "GET",
    "schedule": "*/5 * * * *",
    "headers": {
        "Authorization": "Bearer token"
    }
},
)

print(response.status_code)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "name": "health-check",
  "url": "https://example.com/health",
  "method": "GET",
  "schedule": "*/5 * * * *",
  "headers": {
    "Authorization": "Bearer token"
  }
}`)
	req, _ := http.NewRequest("POST", "/v1/cron/jobs", body)
	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()

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

{
  "name": "cron_service",
  "description": "Schedule and manage recurring HTTP jobs with cron expressions",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/cron/jobs",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference