Managed Entries

The Managed Entries API lets you create, list, retrieve, update, and delete cron entries that the Hoody cron service owns on behalf of a system user. Unlike raw crontab lines, managed entries expose scheduling metadata (human-readable schedule, enabled flag, optional expiration) and can be toggled or removed without rewriting the user’s crontab directly. Use these endpoints to programmatically manage scheduled tasks for any system user inside a container.

All endpoints are scoped to a system user via the {user} path parameter. Managed entries are returned alongside any raw crontab lines, so list responses may contain both shapes.

`GET /users/{user}/entries`

List the crontab entries for a system user. Results include both managed entries and raw lines that are not managed by the cron service. Supports pagination via page and limit query parameters.

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": "alice",
  "page": 1,
  "limit": 50,
  "total": 2,
  "entries": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "type": "managed",
      "name": "nightly-backup",
      "schedule": "0 2 * * *",
      "schedule_human": "At 02:00 every day",
      "command": "/usr/local/bin/backup.sh /var/backups",
      "comment": "Nightly database backup",
      "enabled": true,
      "expired": false,
      "expires_at": "2026-12-31T00:00:00Z",
      "created_at": "2026-01-15T08:30:00Z",
      "updated_at": "2026-01-15T08:30:00Z"
    },
    {
      "type": "raw",
      "line": "*/15 * * * * /usr/local/bin/healthcheck.sh"
    }
  ]
}

{
  "code": "INVALID_PAGINATION",
  "details": null,
  "message": "Invalid pagination"
}

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

{
  "code": "BACKEND_ERROR",
  "details": "crontab: permission denied",
  "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

curl -X GET "https://proj_abc123-cont_xyz789-cron-1.us-east-1.containers.hoody.icu/users/alice/entries?page=1&limit=50" \
  -H "Authorization: Bearer <token>"

for await (const entry of client.cron.entries.listIterator("alice", { page: 1, limit: 50 })) {
  console.log(entry);
}

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

Retrieve a single managed entry by id.

Parameters

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

Response

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "user": "alice",
  "name": "nightly-backup",
  "schedule": "0 2 * * *",
  "schedule_human": "At 02:00 every day",
  "command": "/usr/local/bin/backup.sh /var/backups",
  "comment": "Nightly database backup",
  "enabled": true,
  "expired": false,
  "expires_at": "2026-12-31T00:00:00Z",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-01-15T08:30:00Z"
}

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

{
  "code": "ENTRY_NOT_FOUND",
  "details": null,
  "message": "Entry 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

{
  "code": "BACKEND_ERROR",
  "details": null,
  "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

cURL
TypeScript SDK

curl -X GET "https://proj_abc123-cont_xyz789-cron-1.us-east-1.containers.hoody.icu/users/alice/entries/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer <token>"

const entry = await client.cron.entries.get("alice", "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d");

`POST /users/{user}/entries`

Create a new managed cron entry for the given user.

Parameters

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

Request Body

Field	Type	Required	Description
`schedule`	string	Yes	Cron expression (5-field or `@daily` style macro)
`command`	string	Yes	Shell command to execute
`name`	string \| null	No	Friendly display name
`comment`	string \| null	No	Single-line comment associated with the entry
`enabled`	boolean \| null	No	Whether the entry is active. Defaults to true when omitted
`expires_at`	string \| null	No	ISO 8601 timestamp after which the entry is considered expired

Response

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "user": "alice",
  "name": "nightly-backup",
  "schedule": "0 2 * * *",
  "schedule_human": "At 02:00 every day",
  "command": "/usr/local/bin/backup.sh /var/backups",
  "comment": "Nightly database backup",
  "enabled": true,
  "expired": false,
  "expires_at": "2026-12-31T00:00:00Z",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-01-15T08:30:00Z"
}

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

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

{
  "code": "BACKEND_ERROR",
  "details": null,
  "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

cURL
TypeScript SDK

curl -X POST "https://proj_abc123-cont_xyz789-cron-1.us-east-1.containers.hoody.icu/users/alice/entries" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 2 * * *",
    "command": "/usr/local/bin/backup.sh /var/backups",
    "name": "nightly-backup",
    "comment": "Nightly database backup",
    "enabled": true,
    "expires_at": "2026-12-31T00:00:00Z"
  }'

const entry = await client.cron.entries.create("alice", {
  schedule: "0 2 * * *",
  command: "/usr/local/bin/backup.sh /var/backups",
  name: "nightly-backup",
  comment: "Nightly database backup",
  enabled: true,
  expires_at: "2026-12-31T00:00:00Z",
});

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

Update one or more fields of an existing managed entry. Omitted fields are left unchanged.

Parameters

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

Request Body

Field	Type	Required	Description
`schedule`	string \| null	No	Cron expression to replace the current schedule
`command`	string \| null	No	Command to replace the current command
`name`	string \| null	No	Friendly display name
`comment`	string \| null	No	Single-line comment
`enabled`	boolean \| null	No	Whether the entry is active
`expires_at`	string \| null	No	ISO 8601 timestamp after which the entry is considered expired
`clear_expiration`	boolean \| null	No	When true, remove the existing expiration timestamp

Response

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "user": "alice",
  "name": "nightly-backup",
  "schedule": "30 2 * * *",
  "schedule_human": "At 02:30 every day",
  "command": "/usr/local/bin/backup.sh /var/backups",
  "comment": "Nightly database backup",
  "enabled": false,
  "expired": false,
  "expires_at": "2026-12-31T00:00:00Z",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-02-10T11:05:00Z"
}

{
  "code": "INVALID_COMMAND",
  "details": null,
  "message": "Invalid command"
}

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",
  "details": null,
  "message": "Entry 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

{
  "code": "BACKEND_ERROR",
  "details": null,
  "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

cURL
TypeScript SDK

curl -X PATCH "https://proj_abc123-cont_xyz789-cron-1.us-east-1.containers.hoody.icu/users/alice/entries/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "30 2 * * *",
    "enabled": false
  }'

const entry = await client.cron.entries.update(
  "alice",
  "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  {
    schedule: "30 2 * * *",
    enabled: false,
  },
);

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

Delete a managed entry. The corresponding crontab line is removed from the user’s crontab. Raw (non-managed) 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",
  "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

{
  "code": "ENTRY_NOT_FOUND",
  "details": null,
  "message": "Entry 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

{
  "code": "BACKEND_ERROR",
  "details": null,
  "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

cURL
TypeScript SDK

curl -X DELETE "https://proj_abc123-cont_xyz789-cron-1.us-east-1.containers.hoody.icu/users/alice/entries/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer <token>"

await client.cron.entries.delete("alice", "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d");