Managed Entries

Download Page (.md)

The Managed Entries API provides endpoints to create, list, retrieve, update, and delete cron entries that the platform manages on behalf of a system user. Each managed entry pairs a cron schedule with a shell command, supports optional expiration and human-readable metadata, and tracks creation and update timestamps. Use these endpoints when you need programmatic control over scheduled jobs for a specific system user on the host.

List entries

GET /users/{user}/entries

Returns a paginated list of crontab entries for the given system user. The response includes both managed entries (with schedule, command, and metadata) and raw crontab lines that exist outside of managed tracking.

Parameters

Name	In	Type	Required	Description
`user`	path	string	Yes	System username
`page`	query	integer	No	Page number (1-based)
`limit`	query	integer	No	Items per page (max 200)

Response

{
  "user": "deploy",
  "page": 1,
  "limit": 50,
  "total": 2,
  "entries": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "managed",
      "name": "Daily backup",
      "comment": "Runs the daily backup script",
      "schedule": "0 2 * * *",
      "schedule_human": "At 02:00 AM, every day",
      "command": "/usr/local/bin/backup.sh",
      "enabled": true,
      "expired": false,
      "expires_at": null,
      "created_at": "2024-11-01T10:30:00Z",
      "updated_at": "2024-11-15T14:22:00Z"
    },
    {
      "type": "raw",
      "line": "*/15 * * * * /usr/local/bin/healthcheck.sh"
    }
  ]
}

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

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

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

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

{
  "code": "BACKEND_ERROR",
  "message": "Internal server error",
  "details": null
}

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

for await (const entry of client.cron.entries.listIterator({ user: "deploy" })) {
  console.log(entry);
}

curl -X GET "https://api.hoody.com/api/cron/entries/users/deploy/entries?page=1&limit=50"

Get an entry

GET /users/{user}/entries/{id}

Returns the details of a single managed cron entry for the given system user.

Parameters

Name	In	Type	Required	Description
`user`	path	string	Yes	System username
`id`	path	string	Yes	Managed entry id

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user": "deploy",
  "name": "Daily backup",
  "comment": "Runs the daily backup script",
  "schedule": "0 2 * * *",
  "schedule_human": "At 02:00 AM, every day",
  "command": "/usr/local/bin/backup.sh",
  "enabled": true,
  "expired": false,
  "expires_at": null,
  "created_at": "2024-11-01T10:30:00Z",
  "updated_at": "2024-11-15T14:22:00Z"
}

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

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

{
  "code": "ENTRY_NOT_FOUND",
  "message": "Entry not found",
  "details": null
}

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

{
  "code": "BACKEND_ERROR",
  "message": "Internal server error",
  "details": null
}

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

SDK usage

TypeScript
cURL

const entry = await client.cron.entries.get({
  user: "deploy",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
});

curl -X GET "https://api.hoody.com/api/cron/entries/users/deploy/entries/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Create an entry

POST /users/{user}/entries

Creates a new managed cron entry for the given system user. The endpoint requires a JSON request body describing the schedule and command to run.

Parameters

Name	In	Type	Required	Description
`user`	path	string	Yes	System username

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user": "deploy",
  "name": "Daily backup",
  "comment": "Runs the daily backup script",
  "schedule": "0 2 * * *",
  "schedule_human": "At 02:00 AM, every day",
  "command": "/usr/local/bin/backup.sh",
  "enabled": true,
  "expired": false,
  "expires_at": null,
  "created_at": "2024-11-01T10:30:00Z",
  "updated_at": "2024-11-01T10:30:00Z"
}

{
  "code": "INVALID_SCHEDULE",
  "message": "Invalid schedule",
  "details": null
}

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

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

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

{
  "code": "BACKEND_ERROR",
  "message": "Internal server error",
  "details": null
}

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

SDK usage

TypeScript
cURL

const entry = await client.cron.entries.create({
  user: "deploy",
  data: {
    schedule: "0 2 * * *",
    command: "/usr/local/bin/backup.sh"
  }
});

curl -X POST "https://api.hoody.com/api/cron/entries/users/deploy/entries" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 2 * * *",
    "command": "/usr/local/bin/backup.sh"
  }'

Update an entry

PATCH /users/{user}/entries/{id}

Updates an existing managed cron entry for the given system user. Only the fields included in the request body are modified; omitted fields are left unchanged.

Parameters

Name	In	Type	Required	Description
`user`	path	string	Yes	System username
`id`	path	string	Yes	Managed entry id

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user": "deploy",
  "name": "Daily backup",
  "comment": "Runs the daily backup script",
  "schedule": "0 2 * * *",
  "schedule_human": "At 02:00 AM, every day",
  "command": "/usr/local/bin/backup.sh",
  "enabled": false,
  "expired": false,
  "expires_at": null,
  "created_at": "2024-11-01T10:30:00Z",
  "updated_at": "2024-11-15T14:22:00Z"
}

{
  "code": "INVALID_SCHEDULE",
  "message": "Invalid schedule",
  "details": null
}

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

{
  "code": "ENTRY_NOT_FOUND",
  "message": "Entry not found",
  "details": null
}

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

{
  "code": "BACKEND_ERROR",
  "message": "Internal server error",
  "details": null
}

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

SDK usage

TypeScript
cURL

const entry = await client.cron.entries.update({
  user: "deploy",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  data: {
    enabled: false
  }
});

curl -X PATCH "https://api.hoody.com/api/cron/entries/users/deploy/entries/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Delete an entry

DELETE /users/{user}/entries/{id}

Deletes a managed cron entry for the given system user. The underlying crontab is rewritten to remove the entry; raw crontab lines are not affected.

Parameters

Name	In	Type	Required	Description
`user`	path	string	Yes	System username
`id`	path	string	Yes	Managed entry id

Response

{
  "deleted": true
}

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

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

{
  "code": "ENTRY_NOT_FOUND",
  "message": "Entry not found",
  "details": null
}

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

{
  "code": "BACKEND_ERROR",
  "message": "Internal server error",
  "details": null
}

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

SDK usage

TypeScript
cURL

const result = await client.cron.entries.delete({
  user: "deploy",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
});

curl -X DELETE "https://api.hoody.com/api/cron/entries/users/deploy/entries/a1b2c3d4-e5f6-7890-abcd-ef1234567890"