# Schedules endpoints (Client API: game servers)

> 11 FeatherPanel Client API: game servers endpoints from user/server/schedules.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/user/server/schedules/

Defined in [`backend/app/routes/user/server/schedules.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php). Authentication used here: **Server access**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/user/servers/{uuidShort}/schedules`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-schedules`)
- Route name: `session-server-schedules`
- Controller: [`ServerScheduleController::getSchedules`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L28)

**Get server schedules** Retrieve all schedules for a specific server that the user owns or has subuser access to.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `page` | query | integer | no | Page number for pagination |
| `per_page` | query | integer | no | Number of records per page |
| `search` | query | string | no | Search term to filter schedules by name |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `data` | ServerSchedule\[\] |  |
| `pagination` | SchedulePagination |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Server schedules retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found · `500` Internal server error - Failed to retrieve schedules

### POST `/api/user/servers/{uuidShort}/schedules`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-schedules`)
- Route name: `session-server-create-schedule`
- Controller: [`ServerScheduleController::createSchedule`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L51)

**Create schedule** Create a new schedule for a server with cron expression validation and next run time calculation.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`ScheduleCreateRequest`](https://featherpanel.com/docs/api/schemas/#schema-schedulecreaterequest) (application/json) · Response data: [`ScheduleCreateResponse`](https://featherpanel.com/docs/api/schemas/#schema-schedulecreateresponse)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Schedule name |
| `cron_day_of_week` | string | yes | Cron day of week expression |
| `cron_month` | string | yes | Cron month expression |
| `cron_day_of_month` | string | yes | Cron day of month expression |
| `cron_hour` | string | yes | Cron hour expression |
| `cron_minute` | string | yes | Cron minute expression |
| `timezone` | string | no | IANA timezone the cron expression is authored in (default: "UTC") |
| `is_active` | boolean | no | Whether schedule is active |
| `only_when_online` | boolean | no | Whether to run only when server is online |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `id` | integer | Created schedule ID |
| `name` | string | Schedule name |
| `next_run_at` | string (date-time) | Next scheduled run time |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","cron_day_of_week":"","cron_month":"","cron_day_of_month":"","cron_hour":"","cron_minute":"","timezone":"","is_active":false,"only_when_online":false}'
```

Plugin events: [`featherpanel:user:server:schedule:created`](https://featherpanel.com/docs/plugins/events/server/#server-schedule-created)

Responses: `201` Schedule created successfully · `400` Bad request - Missing required fields, invalid cron expression, or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found · `500` Internal server error - Failed to create schedule

### GET `/api/user/servers/{uuidShort}/schedules/{scheduleId}`

- Auth: Server access
- Route name: `session-server-get-schedule`
- Controller: [`ServerScheduleController::getSchedule`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L74)

**Get specific schedule** Retrieve details of a specific schedule for a server that the user owns or has subuser access to.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `scheduleId` | path | integer | yes | Schedule ID |

Response data: [`ServerSchedule`](https://featherpanel.com/docs/api/schemas/#schema-serverschedule)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `id` | integer | Schedule ID |
| `server_id` | integer | Server ID |
| `name` | string | Schedule name |
| `cron_day_of_week` | string | Cron day of week expression |
| `cron_month` | string | Cron month expression |
| `cron_day_of_month` | string | Cron day of month expression |
| `cron_hour` | string | Cron hour expression |
| `cron_minute` | string | Cron minute expression |
| `timezone` | string | IANA timezone the cron expression is authored in (e.g. "Europe/Paris", "UTC") |
| `is_active` | boolean | Whether schedule is active |
| `is_processing` | boolean | Whether schedule is currently processing |
| `only_when_online` | boolean | Whether to run only when server is online |
| `next_run_at` | string (date-time) | Next scheduled run time |
| `created_at` | string (date-time) | Creation timestamp |
| `updated_at` | string (date-time) | Last update timestamp |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Schedule details retrieved successfully · `400` Bad request - Missing or invalid parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or schedule not found · `500` Internal server error - Failed to retrieve schedule

### PUT `/api/user/servers/{uuidShort}/schedules/{scheduleId}`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-schedules`)
- Route name: `session-server-update-schedule`
- Controller: [`ServerScheduleController::updateSchedule`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L96)

**Update schedule** Update an existing schedule with new cron expression validation and next run time recalculation.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `scheduleId` | path | integer | yes | Schedule ID |

Request body: [`ScheduleUpdateRequest`](https://featherpanel.com/docs/api/schemas/#schema-scheduleupdaterequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Schedule name |
| `cron_day_of_week` | string | no | Cron day of week expression |
| `cron_month` | string | no | Cron month expression |
| `cron_day_of_month` | string | no | Cron day of month expression |
| `cron_hour` | string | no | Cron hour expression |
| `cron_minute` | string | no | Cron minute expression |
| `timezone` | string | no | IANA timezone the cron expression is authored in |
| `is_active` | boolean | no | Whether schedule is active |
| `only_when_online` | boolean | no | Whether to run only when server is online |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X PUT "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","cron_day_of_week":"","cron_month":"","cron_day_of_month":"","cron_hour":"","cron_minute":"","timezone":"","is_active":false,"only_when_online":false}'
```

Plugin events: [`featherpanel:user:server:schedule:updated`](https://featherpanel.com/docs/plugins/events/server/#server-schedule-updated)

Responses: `200` Schedule updated successfully · `400` Bad request - Invalid cron expression or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or schedule not found · `500` Internal server error - Failed to update schedule

### DELETE `/api/user/servers/{uuidShort}/schedules/{scheduleId}`

- Auth: Server access
- Route name: `session-server-delete-schedule`
- Controller: [`ServerScheduleController::deleteSchedule`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L120)

**Delete schedule** Delete a schedule. Schedules that are currently processing can also be deleted (e.g. to clear stuck schedules).

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `scheduleId` | path | integer | yes | Schedule ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:schedule:deleted`](https://featherpanel.com/docs/plugins/events/server/#server-schedule-deleted)

Responses: `200` Schedule deleted successfully · `400` Bad request - Missing parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or schedule not found · `500` Internal server error - Failed to delete schedule

### POST `/api/user/servers/{uuidShort}/schedules/{scheduleId}/toggle`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-schedules`)
- Route name: `session-server-toggle-schedule-status`
- Controller: [`ServerScheduleController::toggleScheduleStatus`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L142)

**Toggle schedule status** Toggle the active status of a schedule (enable/disable).

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `scheduleId` | path | integer | yes | Schedule ID |

Response data: [`ScheduleToggleResponse`](https://featherpanel.com/docs/api/schemas/#schema-scheduletoggleresponse)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `is_active` | boolean | New active status |
| `status` | string | Status description |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/$SCHEDULE_ID/toggle" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:server:schedule:status:toggle`](https://featherpanel.com/docs/plugins/events/server/#server-schedule-status-toggled)

Responses: `200` Schedule status toggled successfully · `400` Bad request - Missing or invalid parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or schedule not found · `500` Internal server error - Failed to toggle schedule status

### GET `/api/user/servers/{uuidShort}/schedules/active`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-schedules`)
- Route name: `session-server-active-schedules`
- Controller: [`ServerScheduleController::getActiveSchedules`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L166)

**Get active schedules** Retrieve all active schedules for a specific server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `data` | ServerSchedule\[\] |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/active" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Active schedules retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found · `500` Internal server error - Failed to retrieve active schedules

### GET `/api/user/servers/{uuidShort}/schedules/due`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-schedules`)
- Route name: `session-server-due-schedules`
- Controller: [`ServerScheduleController::getDueSchedules`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L189)

**Get due schedules** Retrieve schedules that are due to run for a specific server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `data` | ServerSchedule\[\] |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/due" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Due schedules retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found · `500` Internal server error - Failed to retrieve due schedules

### POST `/api/user/servers/{uuidShort}/schedules/{scheduleId}/run`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-schedules`)
- Route name: `session-server-run-schedule-now`
- Controller: [`ServerScheduleController::runNow`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L207)

**Run schedule now** Trigger a schedule to run on the next cron tick by setting its next run time to the past. The schedule must not already be processing.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `scheduleId` | path | integer | yes | Schedule ID |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/$SCHEDULE_ID/run" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:schedule:updated`](https://featherpanel.com/docs/plugins/events/server/#server-schedule-updated)

Responses: `200` Schedule queued to run on next cron tick · `400` Bad request - Schedule is already processing or has no tasks · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or schedule not found · `500` Internal server error - Failed to queue schedule

### GET `/api/user/servers/{uuidShort}/schedules/{scheduleId}/export`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-schedules`)
- Route name: `session-server-export-schedule`
- Controller: [`ServerScheduleController::exportSchedule`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L231)

**Export schedule** Export a schedule and all its tasks as a JSON payload that can be imported into another server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `scheduleId` | path | integer | yes | Schedule ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `name` | string | Schedule name |
| `cron_minute` | string |  |
| `cron_hour` | string |  |
| `cron_day_of_month` | string |  |
| `cron_month` | string |  |
| `cron_day_of_week` | string |  |
| `is_active` | boolean |  |
| `only_when_online` | boolean |  |
| `tasks` | object\[\] |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/$SCHEDULE_ID/export" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Schedule exported successfully · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or schedule not found

### POST `/api/user/servers/{uuidShort}/schedules/import`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-schedules`)
- Route name: `session-server-import-schedule`
- Controller: [`ServerScheduleController::importSchedule`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerScheduleController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/schedules.php#L255)

**Import schedule** Import a schedule and its tasks from a previously exported JSON payload.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Schedule name (overrides exported name) |
| `cron_minute` | string | no |  |
| `cron_hour` | string | no |  |
| `cron_day_of_month` | string | no |  |
| `cron_month` | string | no |  |
| `cron_day_of_week` | string | no |  |
| `is_active` | boolean | no |  |
| `only_when_online` | boolean | no |  |
| `tasks` | object\[\] | no |  |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `id` | integer | Created schedule ID |
| `name` | string | Schedule name |
| `tasks_imported` | integer | Number of tasks imported |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/schedules/import" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","cron_minute":"","cron_hour":"","cron_day_of_month":"","cron_month":"","cron_day_of_week":"","is_active":false,"only_when_online":false,"tasks":[]}'
```

Plugin events: [`featherpanel:user:server:schedule:created`](https://featherpanel.com/docs/plugins/events/server/#server-schedule-created)

Responses: `201` Schedule imported successfully · `400` Bad request - Missing required fields, invalid cron expression, or invalid task data · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found · `500` Internal server error - Failed to import schedule