Cron API
Full API reference for managing cron jobs. Create, update, delete, and run scheduled tasks.
Base URL
https://api.hookwatch.dev/v1/cron-jobsThe Cron Job Object
Properties
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the cron job |
name | string | Human-readable name for the job |
schedule | string | Human-readable schedule or cron expression |
schedule_cron | string | Normalized cron expression |
command | string | Shell command to execute on the assigned CLI agent |
working_dir | string | Working directory for command execution |
timeout_seconds | number | Execution timeout in seconds (default: 300) |
retry_config | object | Retry configuration with max_retries and intervals |
notification_config | object | Notification settings (on_failure, on_success) |
environment | object | Key-value environment variables passed to the command |
tags | string[] | Tags for organizing and filtering jobs |
agent_id | string | ID of the CLI agent assigned to execute this job |
agent_name | string | Name of the assigned CLI agent |
is_enabled | boolean | Whether the job is active |
last_run_at | string | null | ISO 8601 timestamp of last execution |
next_run_at | string | null | ISO 8601 timestamp of next scheduled run |
Create Cron Job
Create a new scheduled cron job.
POST /v1/cron-jobsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name for the cron job |
schedule | string | Yes | Cron expression or human-readable schedule |
command | string | Yes | Shell command to execute |
working_dir | string | No | Working directory for the command |
timeout_seconds | number | No | Timeout in seconds (default: 300, max: 3600) |
retry_config | object | No | Custom retry configuration |
notification_config | object | No | Notification preferences (on_failure, on_success) |
environment | object | No | Key-value environment variables |
tags | string[] | No | Tags for the job |
agent_id | string | No | ID of agent to assign (optional) |
Example
List Cron Jobs
Retrieve all cron jobs for the authenticated user.
GET /v1/cron-jobsQuery Parameters
| Field | Type | Description |
|---|---|---|
limit | number | Maximum jobs to return (default: 20, max: 100) |
offset | number | Number of jobs to skip for pagination |
enabled | boolean | Filter by enabled status |
tag | string | Filter by tag |
Response
Get Next Scheduled Runs
Get the next scheduled run time for all enabled jobs.
GET /v1/cron-jobs/nextResponse
Get Cron Job
Retrieve a specific cron job by ID.
GET /v1/cron-jobs/:idUpdate Cron Job
Update an existing cron job's configuration.
PUT /v1/cron-jobs/:idAll fields are optional. Only include fields you want to update.
Delete Cron Job
Permanently delete a cron job and all its execution history.
DELETE /v1/cron-jobs/:idWarning
This action is irreversible. All execution history for this job will be permanently deleted.
Enable / Disable
Toggle a cron job's enabled status without deleting it.
POST /v1/cron-jobs/:id/enableEnable the job
POST /v1/cron-jobs/:id/disableDisable the job
Run Job Now
Manually trigger an immediate execution of a cron job, regardless of its schedule.
POST /v1/cron-jobs/:id/runResponse
Note
Manual runs create an execution with status: "pending" and triggered_by: "manual". The assigned CLI agent picks it up and executes it
locally.
Agent-Based Execution
Cron jobs are executed locally by registered CLI agents, not in the cloud. When you create a job, assign it to an agent or let HookWatch use the default agent. The agent runs the shell command on its host machine and reports results back to the cloud.
Error Codes
| Status | Error | Description |
|---|---|---|
400 | Bad Request | Invalid schedule expression or request body |
401 | Unauthorized | Invalid or missing access token |
403 | Forbidden | Cron job limit reached (upgrade plan) |
404 | Not Found | Cron job not found |