Overview

The raw crontab endpoints let you read and replace the full crontab text for a system user, or list every user that currently has a crontab. These operations work on the complete crontab file as a single string and do not parse, validate, or manage individual scheduled entries. For per-entry management, use the managed entry endpoints under /api/cron/users/{user}/entries/.

List all user crontabs

GET /crontab

Returns a paginated list of every system user that has a crontab installed. Each item contains the username and the raw crontab text.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	Page number (1-based)
limit	query	integer	No	Items per page (max 200)

Response

200

{
  "items": [
    {
      "user": "deploy",
      "crontab": "0 2 * * * /usr/local/bin/backup.sh\n"
    },
    {
      "user": "www-data",
      "crontab": "*/15 * * * * /usr/local/bin/rotate-logs.sh\n"
    }
  ],
  "limit": 50,
  "page": 1,
  "total": 2
}

500

{
  "code": "BACKEND_ERROR",
  "details": "crontab binary not found in PATH",
  "message": "Internal server error"
}

Error Code	Title	Description	Resolution
BACKEND_ERROR	Backend error	Failed to read or write system crontab	Check crontab availability and permissions

SDK usage

const result = await client.cron.crontab.listGlobalIterator({
  page: 1,
  limit: 50,
});

curl -X GET "https://api.example.com/api/cron/crontab/?page=1&limit=50" \
  -H "Authorization: Bearer <token>"

Get a user’s crontab

GET /users/{user}/crontab

Returns the raw crontab text for a single system user.

Parameters

Name	In	Type	Required	Description
user	path	string	Yes	System username

Response

200

{
  "user": "deploy",
  "crontab": "0 2 * * * /usr/local/bin/backup.sh\n"
}

400

{
  "code": "INVALID_USER",
  "details": null,
  "message": "Invalid user"
}

Error Code	Title	Description	Resolution
INVALID_USER	Invalid user	User parameter failed validation	Provide a valid system username
INVALID_COMMENT	Invalid comment	Comment is empty, too long, or contains newlines	Provide a short single-line comment
INVALID_SCHEDULE	Invalid schedule	Schedule is not a valid cron expression	Use a standard 5-field cron expression or @daily style macros
INVALID_COMMAND	Invalid command	Command field is empty or contains invalid characters	Provide a command without newlines
INVALID_PAGINATION	Invalid pagination	Page or limit is out of range	Use page >= 1 and limit between 1 and 200

404

{
  "code": "USER_NOT_FOUND",
  "details": null,
  "message": "User not found"
}

Error Code	Title	Description	Resolution
USER_NOT_FOUND	User not found	The requested system user does not exist	Create the user or choose an existing username
ENTRY_NOT_FOUND	Entry not found	No managed entry with the provided id exists	List entries and retry with a valid id

500

{
  "code": "BACKEND_ERROR",
  "details": "crontab binary not found in PATH",
  "message": "Internal server error"
}

Error Code	Title	Description	Resolution
BACKEND_ERROR	Backend error	Failed to read or write system crontab	Check crontab availability and permissions

SDK usage

const result = await client.cron.crontab.get({
  user: "deploy",
});

curl -X GET "https://api.example.com/api/cron/crontab/users/deploy/crontab" \
  -H "Authorization: Bearer <token>"

Replace a user’s crontab

PUT /users/{user}/crontab

Replaces the entire crontab for a system user with the supplied text. The response includes removed_expired, the number of expired managed entries that were pruned during the replacement.

Parameters

Name	In	Type	Required	Description
user	path	string	Yes	System username

Request Body

Field	Type	Required	Description
crontab	string	Yes	Full crontab text to install for the user. Replaces any existing crontab.

Response

200

{
  "user": "deploy",
  "crontab": "0 2 * * * /usr/local/bin/backup.sh\n",
  "removed_expired": 1
}

400

{
  "code": "INVALID_USER",
  "details": null,
  "message": "Invalid user"
}

Error Code	Title	Description	Resolution
INVALID_USER	Invalid user	User parameter failed validation	Provide a valid system username
INVALID_COMMENT	Invalid comment	Comment is empty, too long, or contains newlines	Provide a short single-line comment
INVALID_SCHEDULE	Invalid schedule	Schedule is not a valid cron expression	Use a standard 5-field cron expression or @daily style macros
INVALID_COMMAND	Invalid command	Command field is empty or contains invalid characters	Provide a command without newlines
INVALID_PAGINATION	Invalid pagination	Page or limit is out of range	Use page >= 1 and limit between 1 and 200

404

{
  "code": "USER_NOT_FOUND",
  "details": null,
  "message": "User not found"
}

Error Code	Title	Description	Resolution
USER_NOT_FOUND	User not found	The requested system user does not exist	Create the user or choose an existing username
ENTRY_NOT_FOUND	Entry not found	No managed entry with the provided id exists	List entries and retry with a valid id

413

{
  "code": "PAYLOAD_TOO_LARGE",
  "details": "crontab text exceeds maximum allowed size",
  "message": "Payload too large"
}

500

{
  "code": "BACKEND_ERROR",
  "details": "crontab binary not found in PATH",
  "message": "Internal server error"
}

Error Code	Title	Description	Resolution
BACKEND_ERROR	Backend error	Failed to read or write system crontab	Check crontab availability and permissions

SDK usage

await client.cron.crontab.put({
  user: "deploy",
  data: {
    crontab: "0 2 * * * /usr/local/bin/backup.sh\n",
  },
});

curl -X PUT "https://api.example.com/api/cron/crontab/users/deploy/crontab" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"crontab": "0 2 * * * /usr/local/bin/backup.sh\n"}'