# Request Scheduling

**Page:** api/curl/scheduling

[Download Raw Markdown](./api/curl/scheduling.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



# 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




```json
{
  "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
  }
}
```




```json
{
  "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

```typescript
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




```json
{
  "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..."
    }
  }
}
```




```json
{
  "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 |




```json
{
  "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

```typescript
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. |

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

### Response




```json
{
  "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"
  }
}
```




```json
{
  "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 |




```json
{
  "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

```typescript
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




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




```json
{
  "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 |




```json
{
  "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

```typescript
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




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




```json
{
  "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 |




```json
{
  "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

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