Request Scheduling

Create and manage recurring HTTP requests using cron-based schedules. Schedules are persistent and survive server restarts. Use these endpoints to define cron-based execution rules, list existing jobs, toggle their state, and remove schedules that are no longer needed.

List Schedules

GET /api/v1/curl/schedule

Retrieve a list of all recurring schedules, sorted by creation time (newest first). Shows schedule configuration, next execution time, and enabled/disabled status.

Schedule States:

• Enabled — Active, will execute at next scheduled time
• Disabled — Paused, will not execute (can be re-enabled)

Parameters

Name	In	Type	Required	Description
page	query	integer	No	1-based page number
limit	query	integer	No	Items per page (current handler returns all items when omitted)

Response

200

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "cron": "0 0 9 * * MON-FRI",
      "enabled": true,
      "created_at": "2025-01-15T10:30:00Z",
      "last_run": "2025-01-15T09:00:00Z",
      "name": "Weekday morning report",
      "next_run": "2025-01-16T09:00:00Z",
      "request": {
        "url": "https://api.example.com/reports/daily",
        "method": "GET"
      }
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "cron": "0 0 * * * *",
      "enabled": false,
      "created_at": "2025-01-14T08:00:00Z",
      "last_run": null,
      "name": "Hourly health check",
      "next_run": null,
      "request": {
        "url": "https://api.example.com/health",
        "method": "GET"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read schedules"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Unable to read schedules from persistent storage	Check storage directory permissions and disk availability

SDK Usage

const result = await client.curl.schedules.listIterator({ page: 1, limit: 20 });

Get Schedule

GET /api/v1/curl/schedule/{id}

Retrieve complete details of a specific schedule including its cron expression, request configuration, and execution history.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique schedule identifier (UUID format)

Response

200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cron": "0 0 9 * * MON-FRI",
  "enabled": true,
  "created_at": "2025-01-15T10:30:00Z",
  "last_run": "2025-01-15T09:00:00Z",
  "name": "Weekday morning report",
  "next_run": "2025-01-16T09:00:00Z",
  "request": {
    "url": "https://api.example.com/reports/daily",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

404

{
  "error": "SCHEDULE_NOT_FOUND",
  "message": "Schedule not found"
}

Error Code	Title	Description	Resolution
SCHEDULE_NOT_FOUND	Schedule does not exist	No schedule found with the provided ID	Verify schedule ID using listSchedules endpoint

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read schedule"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Failed to read schedule data from storage	Check storage integrity and retry

SDK Usage

const result = await client.curl.schedules.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890");

Create Schedule

POST /api/v1/curl/schedule

Create a new cron-based schedule that executes an HTTP request repeatedly at specified intervals.

Cron Expression Format: 6 fields — second minute hour day month weekday

• 0 * * * * * — Every minute
• 0 0 * * * * — Every hour
• 0 0 9 * * MON-FRI — Weekdays at 9 AM
• 0 0 0 * * * — Daily at midnight
• 0 0 12 1 * * — Monthly on 1st at noon

Common Use Cases:

• Periodic API data collection
• Regular health checks and monitoring
• Scheduled report generation
• Automated backups or synchronization

Request Body

Name	Type	Required	Description
cron	string	Yes	Six-field cron expression: second minute hour day month weekday
request	object	Yes	The cURL request to execute on each tick. See CurlRequest for the full field reference.

{
  "cron": "0 0 9 * * MON-FRI",
  "request": {
    "url": "https://api.example.com/reports/daily",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

Response

201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cron": "0 0 9 * * MON-FRI",
  "enabled": true,
  "created_at": "2025-01-15T10:30:00Z",
  "request": {
    "url": "https://api.example.com/reports/daily",
    "method": "GET"
  }
}

400

{
  "error": "INVALID_CRON_EXPRESSION",
  "message": "Invalid cron expression: invalid field"
}

Error Code	Title	Description	Resolution
INVALID_CRON_EXPRESSION	Malformed cron expression	The provided cron expression is invalid or incorrectly formatted	Use 6-field format: second minute hour day month weekday. Example: 0 0 9 * * MON-FRI
INVALID_PARAMETER	Invalid request configuration	The embedded request contains invalid parameters	Verify request.url is valid and all parameters match expected types

500

{
  "error": "SCHEDULE_CREATION_FAILED",
  "message": "Failed to create schedule"
}

Error Code	Title	Description	Resolution
SCHEDULE_CREATION_FAILED	Schedule creation failed	Unable to create schedule in persistent storage	Check storage permissions and disk space, then retry

SDK Usage

const result = await client.curl.schedules.create({
  cron: "0 0 9 * * MON-FRI",
  request: {
    url: "https://api.example.com/reports/daily",
    method: "GET"
  }
});

Toggle Schedule

PATCH /api/v1/curl/schedule/{id}/toggle

Toggle a schedule between enabled and disabled states without deleting it. Send a JSON body of {"enabled": true} to enable or {"enabled": false} to disable the schedule.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique schedule identifier

Response

200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "enabled": true
}

404

{
  "error": "SCHEDULE_NOT_FOUND",
  "message": "Schedule not found"
}

Error Code	Title	Description	Resolution
SCHEDULE_NOT_FOUND	Schedule does not exist	Cannot toggle schedule that doesn’t exist	Verify schedule ID using listSchedules endpoint

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to toggle schedule"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage update failed	Schedule exists but state could not be updated in storage	Check storage permissions and retry operation

SDK Usage

const result = await client.curl.schedules.toggle("a1b2c3d4-e5f6-7890-abcd-ef1234567890", { enabled: true });

Delete Schedule

DELETE /api/v1/curl/schedule/{id}

Permanently delete a recurring schedule. The schedule will immediately stop executing and all configuration will be removed.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique schedule identifier

Response

200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

404

{
  "error": "SCHEDULE_NOT_FOUND",
  "message": "Schedule not found"
}

Error Code	Title	Description	Resolution
SCHEDULE_NOT_FOUND	Schedule does not exist	Cannot delete schedule that doesn’t exist	Verify schedule ID using listSchedules endpoint

500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to delete schedule"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage delete failed	Schedule exists but could not be deleted from storage	Check storage permissions and retry operation

SDK Usage

await client.curl.schedules.delete("a1b2c3d4-e5f6-7890-abcd-ef1234567890");