Managed Entries

Download Page (.md)

The Managed Entries API provides CRUD operations for cron jobs that are managed through the Hoody platform. Each entry belongs to a specific system user and is identified by a UUID. Use these endpoints to create new scheduled tasks, list existing entries, retrieve details, update properties, and remove entries from the managed crontab.

List Entries

Returns a paginated list of managed entries for a given system user. The response includes both managed and raw crontab entries.

GET /users/{user}/entries

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)

cURL
SDK

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

const iterator = client.cron.entries.listIterator({ user: "www-data" });
for await (const entry of iterator) {
  console.log(entry.id, entry.schedule);
}

Responses

{
  "user": "www-data",
  "entries": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "schedule": "*/5 * * * *",
      "schedule_human": "Every 5 minutes",
      "command": "/usr/bin/php /var/www/artisan schedule:run",
      "comment": "Laravel scheduler",
      "name": "laravel-scheduler",
      "enabled": true,
      "expired": false,
      "expires_at": null,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "type": "managed"
    },
    {
      "line": "0 3 * * * /usr/local/bin/backup.sh",
      "type": "raw"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 50
}

{
  "code": "INVALID_PAGINATION",
  "message": "Invalid pagination",
  "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

Create Entry

Creates a new managed cron entry for a given system user. The new entry is appended to the system crontab and returned with its assigned id and timestamps.

POST /users/{user}/entries

Parameters

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

Request Body

Name	Type	Required	Description
`schedule`	string	Yes	Cron expression (5-field or `@daily`-style macro)
`command`	string	Yes	Command to execute
`name`	string \| null	No	Display name for the entry
`comment`	string \| null	No	Short single-line comment
`enabled`	boolean \| null	No	Whether the entry is active
`expires_at`	string \| null	No	ISO 8601 expiration timestamp

cURL
SDK

curl -X POST "https://api.hoody.com/api/cron/entries/users/www-data/entries" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "*/5 * * * *",
    "command": "/usr/bin/php /var/www/artisan schedule:run",
    "name": "laravel-scheduler",
    "comment": "Laravel scheduler",
    "enabled": true
  }'

const entry = await client.cron.entries.create({
  user: "www-data",
  data: {
    schedule: "*/5 * * * *",
    command: "/usr/bin/php /var/www/artisan schedule:run",
    name: "laravel-scheduler",
    comment: "Laravel scheduler",
    enabled: true
  }
});
console.log(entry.id);

Responses

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user": "www-data",
  "schedule": "*/5 * * * *",
  "schedule_human": "Every 5 minutes",
  "command": "/usr/bin/php /var/www/artisan schedule:run",
  "comment": "Laravel scheduler",
  "name": "laravel-scheduler",
  "enabled": true,
  "expired": false,
  "expires_at": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10: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

Get Entry

Retrieves a single managed entry by its id.

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

Parameters

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

cURL
SDK

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

const entry = await client.cron.entries.get({
  user: "www-data",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
});
console.log(entry.schedule, entry.command);

Responses

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user": "www-data",
  "schedule": "*/5 * * * *",
  "schedule_human": "Every 5 minutes",
  "command": "/usr/bin/php /var/www/artisan schedule:run",
  "comment": "Laravel scheduler",
  "name": "laravel-scheduler",
  "enabled": true,
  "expired": false,
  "expires_at": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30: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

Update Entry

Partially updates a managed entry. Only the fields included in the request body are modified; omitted fields are left unchanged. Set clear_expiration to true to remove an existing expiration timestamp.

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

Parameters

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

Request Body

Name	Type	Required	Description
`schedule`	string \| null	No	Cron expression (5-field or `@daily`-style macro)
`command`	string \| null	No	Command to execute
`name`	string \| null	No	Display name for the entry
`comment`	string \| null	No	Short single-line comment
`enabled`	boolean \| null	No	Whether the entry is active
`expires_at`	string \| null	No	ISO 8601 expiration timestamp
`clear_expiration`	boolean \| null	No	When `true`, remove any existing expiration timestamp

cURL
SDK

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

const entry = await client.cron.entries.update({
  user: "www-data",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  data: {
    enabled: false,
    comment: "Disabled for maintenance"
  }
});
console.log(entry.enabled);

Responses

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user": "www-data",
  "schedule": "*/5 * * * *",
  "schedule_human": "Every 5 minutes",
  "command": "/usr/bin/php /var/www/artisan schedule:run",
  "comment": "Disabled for maintenance",
  "name": "laravel-scheduler",
  "enabled": false,
  "expired": false,
  "expires_at": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:05:42Z"
}

{
  "code": "INVALID_COMMAND",
  "message": "Invalid command",
  "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

Delete Entry

Removes a managed entry from the system crontab. Returns a deleted flag confirming the operation.

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

Parameters

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

cURL
SDK

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

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

Responses

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