Schedule Management

The Schedule Management section covers all operations related to creating, updating, and managing scheduled HTTP requests.

Get All Schedules

Retrieve all schedules for the authenticated user.

const schedules = await cronhost.getSchedules();

Returns: Promise<Schedule[]>

Get Schedule by ID

Retrieve a specific schedule by its ID.

const schedule = await cronhost.getSchedule("schedule-id");

Parameters:

id (string, required): The unique identifier of the schedule

Returns: Promise<Schedule>

Create Schedule

Create a new scheduled HTTP request.

const schedule = await cronhost.createSchedule({
  name: "Daily Health Check",
  description: "Check if our API is healthy every day at 9 AM",
  cronExpression: "0 9 * * *",
  timezone: "America/New_York",
  endpoint: "https://api.example.com/health",
  httpMethod: "GET",
  body: JSON.stringify({ key: "value" }), // Optional for POST/PUT/PATCH
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer token",
  },
  maxRetries: 3,
  timeoutSeconds: 30,
  expectedStatusCodes: "200-299,410", // optional
});

Parameters:

name (string, required): A descriptive name for the schedule
description (string, optional): Additional description of what the schedule does
cronExpression (string, required): Valid cron expression defining when to run
timezone (string, required): IANA timezone identifier (e.g., ‘America/New_York’) - View all options
endpoint (string, required): The HTTP endpoint to call
httpMethod (“GET” | “POST” | “PUT” | “DELETE” | “PATCH”, required): HTTP method to use
body (string, optional): Request body for POST/PUT/PATCH requests
headers (Record<string, string>, optional): HTTP headers to include in the request
maxRetries (number, optional): Total attempts including the first, clamped to 1-10 (default: 3)
timeoutSeconds (number, optional): Request timeout in seconds, clamped to 1-300 (default: 30)
expectedStatusCodes (string, optional): Comma-separated 3-digit codes/ranges counted as success (e.g. "200-299,410"). Omit or leave blank for the default rule (status below 400)

See the Execution Model for how success, retries, and quota work. Returns: Promise<Schedule>

Bulk Create Schedules

Pass an array (1-1000 items) to createSchedule to create many schedules in one request. Validation is all-or-nothing: if any entry is invalid or the batch exceeds a plan limit, none are created.

const result = await cronhost.createSchedule([
  {
    name: "Morning Sync",
    cronExpression: "0 6 * * *",
    timezone: "UTC",
    endpoint: "https://api.example.com/sync",
    httpMethod: "POST",
  },
  {
    name: "Nightly Cleanup",
    cronExpression: "0 2 * * *",
    timezone: "UTC",
    endpoint: "https://api.example.com/cleanup",
    httpMethod: "POST",
  },
]);

console.log(result.count); // 2
console.log(result.schedules); // [{ id, name }, ...]

Returns: Promise<BulkCreateResponse> where BulkCreateResponse is { count: number; schedules: { id: string; name: string }[] }

Update Schedule

Update an existing schedule.

const updatedSchedule = await cronhost.updateSchedule("schedule-id", {
  name: "Updated Schedule Name",
  cronExpression: "0 10 * * *", // Changed to 10 AM
  maxRetries: 5,
});

Parameters:

id (string, required): The unique identifier of the schedule to update
data (UpdateScheduleData, required): Object containing fields to update

UpdateScheduleData fields (all optional):

name (string): Update the schedule name
description (string): Update the description
cronExpression (string): Update the cron expression
timezone (string): Update the timezone
endpoint (string): Update the endpoint URL
httpMethod (“GET” | “POST” | “PUT” | “DELETE” | “PATCH”): Update HTTP method
body (string): Update request body
headers (Record<string, string>): Update HTTP headers
maxRetries (number): Total attempts including the first, clamped to 1-10
timeoutSeconds (number): Request timeout in seconds, clamped to 1-300
expectedStatusCodes (string): Comma-separated codes/ranges counted as success. Pass "" to clear back to the default rule (status below 400)

Returns: Promise<Schedule>

Delete Schedule

Delete a schedule permanently.

await cronhost.deleteSchedule("schedule-id");

Parameters:

id (string, required): The unique identifier of the schedule to delete

Returns: Promise<void>

Toggle Schedule

Enable or disable a schedule without deleting it.

// Disable a schedule
const disabledSchedule = await cronhost.toggleSchedule("schedule-id", false);

// Enable a schedule
const enabledSchedule = await cronhost.toggleSchedule("schedule-id", true);

Parameters:

id (string, required): The unique identifier of the schedule
enabled (boolean, required): Whether to enable (true) or disable (false) the schedule

Returns: Promise<Schedule>

Trigger Schedule

Manually trigger a schedule to run immediately, regardless of its cron schedule.

const jobId = await cronhost.triggerSchedule("schedule-id");
const job = await cronhost.getJob(jobId); // fetch details if needed

Parameters:

id (string, required): The unique identifier of the schedule to trigger

Returns: Promise<string> - the id of the newly created job. Fetch its details with getJob(id).

Example: Complete Schedule Workflow

import { Cronhost } from "cronhost";

const cronhost = new Cronhost({
  apiKey: "your-api-key",
});

async function scheduleWorkflow() {
  try {
    // Create a new schedule
    const schedule = await cronhost.createSchedule({
      name: "API Health Check",
      description: "Monitor API health every hour",
      cronExpression: "0 * * * *", // Every hour
      timezone: "UTC",
      endpoint: "https://api.example.com/health",
      httpMethod: "GET",
      headers: {
        "User-Agent": "Cronhost-Monitor",
      },
      maxRetries: 2,
      timeoutSeconds: 15,
    });

    console.log("Created schedule:", schedule.id);

    // Update the schedule
    const updated = await cronhost.updateSchedule(schedule.id, {
      maxRetries: 3, // Increase retry count
    });

    // Trigger it immediately for testing
    const jobId = await cronhost.triggerSchedule(schedule.id);
    console.log("Triggered job:", jobId);

    // Disable the schedule temporarily
    await cronhost.toggleSchedule(schedule.id, false);
    console.log("Schedule disabled");

    // Re-enable it
    await cronhost.toggleSchedule(schedule.id, true);
    console.log("Schedule re-enabled");
  } catch (error) {
    console.error("Workflow error:", error.message);
  }
}

scheduleWorkflow();

Getting Started

Core Features

Reference

Schedule Management

Schedule Management

Get All Schedules

Get Schedule by ID

Create Schedule

Bulk Create Schedules

Update Schedule

Delete Schedule

Toggle Schedule

Trigger Schedule

Example: Complete Schedule Workflow

​Schedule Management

​Get All Schedules

​Get Schedule by ID

​Create Schedule

​Bulk Create Schedules

​Update Schedule

​Delete Schedule

​Toggle Schedule

​Trigger Schedule

​Example: Complete Schedule Workflow

Schedule Management

Get All Schedules

Get Schedule by ID

Create Schedule

Bulk Create Schedules

Update Schedule

Delete Schedule

Toggle Schedule

Trigger Schedule

Example: Complete Schedule Workflow