# Managed Entries

**Page:** api/cron/entries

[Download Raw Markdown](./api/cron/entries.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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




```json
{
  "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"
    }
  ]
}
```




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




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




```json
{
  "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
for await (const entry of client.cron.entries.listIterator({ user: "deploy" })) {
  console.log(entry);
}
```




```bash
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




```json
{
  "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"
}
```




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




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




```json
{
  "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
const entry = await client.cron.entries.get({
  user: "deploy",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
});
```




```bash
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




```json
{
  "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"
}
```




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




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




```json
{
  "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
const entry = await client.cron.entries.create({
  user: "deploy",
  data: {
    schedule: "0 2 * * *",
    command: "/usr/local/bin/backup.sh"
  }
});
```




```bash
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




```json
{
  "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"
}
```




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




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




```json
{
  "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
const entry = await client.cron.entries.update({
  user: "deploy",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  data: {
    enabled: false
  }
});
```




```bash
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




```json
{
  "deleted": true
}
```




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




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




```json
{
  "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
const result = await client.cron.entries.delete({
  user: "deploy",
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
});
```




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