zhongwei/gh-rawveg-skillsforge-marketplace-cronjob-org
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:50:13 +08:00
commit 2924cce27e
7 changed files with 858 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

524
skills/cronjob-org/SKILL.md Normal file
View File

@@ -0,0 +1,524 @@
---
name: cronjob-org
description: Cron-Job.org Documentation
---
# Cronjob-Org Skill
Comprehensive assistance with the Cron-Job.org REST API for programmatically managing scheduled HTTP jobs. This skill provides guidance on creating, updating, deleting, and monitoring cron jobs through the official API.
## When to Use This Skill
This skill should be triggered when:
- **Creating automated HTTP requests** on a schedule using Cron-Job.org
- **Managing cron jobs programmatically** through the REST API
- **Implementing job monitoring** and execution history tracking
- **Setting up notifications** for job failures or successes
- **Working with API authentication** and rate limits
- **Debugging cron job executions** or analyzing performance metrics
- **Building integrations** that require scheduled HTTP calls
- **Configuring job schedules** using timezone-aware cron expressions
## Key Concepts
### API Authentication
- **API Keys**: Generated in the Cron-Job.org Console under Settings
- **Bearer Token**: API keys are sent via the `Authorization` header
- **IP Restrictions**: Optional IP allowlisting for enhanced security
- **Rate Limits**: 100 requests/day (default), 5,000 requests/day (sustaining members)
### Job Object
A Job represents a scheduled HTTP request with:
- **URL**: The endpoint to call
- **Schedule**: Cron expression with timezone support
- **Settings**: Timeout, HTTP method, headers, authentication
- **State**: Enabled/disabled, execution status, history
### Execution History
Each job execution creates a HistoryItem containing:
- **Timing**: Actual vs planned execution time, jitter, duration
- **Response**: HTTP status code, headers, body (if saveResponses enabled)
- **Performance**: DNS lookup, connection, SSL handshake, transfer times
### Rate Limits
Different endpoints have different rate limits:
- **Job List/Details**: 5 requests/second
- **Job Creation**: 1 request/second, 5 requests/minute
- **History**: 5 requests/second
## Quick Reference
### 1. Authentication Setup
```bash
# Set your API key as a bearer token in the Authorization header
Authorization: Bearer YOUR_API_KEY_HERE
```
**Notes:**
- API keys are generated in the Console → Settings
- Treat API keys as secrets (like passwords)
- Enable IP restrictions whenever possible for security
### 2. List All Jobs (curl)
```bash
curl -X GET https://api.cron-job.org/jobs \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Response:**
```json
{
"jobs": [
{
"jobId": 12345,
"enabled": true,
"title": "Daily Backup",
"url": "https://example.com/backup",
"lastStatus": 200,
"lastExecution": 1699920000,
"nextExecution": 1700006400
}
],
"jobsPartialError": false
}
```
**Rate Limit:** 5 requests/second
### 3. Create a New Job (Python)
```python
import requests
API_KEY = "your_api_key_here"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
job_data = {
"job": {
"url": "https://example.com/api/health-check",
"enabled": True,
"title": "Health Check",
"saveResponses": True,
"schedule": {
"timezone": "America/New_York",
"hours": [-1], # Every hour
"mdays": [-1], # Every day of month
"minutes": [0], # At minute 0
"months": [-1], # Every month
"wdays": [-1] # Every day of week
}
}
}
response = requests.post(
"https://api.cron-job.org/jobs",
headers=headers,
json=job_data
)
print(f"Created job ID: {response.json()['jobId']}")
```
**Rate Limit:** 1 request/second, 5 requests/minute
### 4. Update an Existing Job
```python
import requests
API_KEY = "your_api_key_here"
JOB_ID = 12345
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# Only include fields you want to change
update_data = {
"job": {
"enabled": False, # Disable the job
"title": "Updated Title"
}
}
response = requests.patch(
f"https://api.cron-job.org/jobs/{JOB_ID}",
headers=headers,
json=update_data
)
print("Job updated successfully" if response.status_code == 200 else "Update failed")
```
**Rate Limit:** 5 requests/second
### 5. Job with HTTP Authentication
```json
{
"job": {
"url": "https://api.example.com/protected",
"enabled": true,
"title": "Protected Endpoint",
"auth": {
"enable": true,
"user": "api_user",
"password": "secret_password"
}
}
}
```
**Notes:**
- Uses HTTP Basic Authentication
- Credentials are stored securely by Cron-Job.org
### 6. Job with Custom Headers
```json
{
"job": {
"url": "https://api.example.com/webhook",
"enabled": true,
"title": "Webhook with Headers",
"extendedData": {
"headers": {
"X-API-Key": "your-api-key",
"Content-Type": "application/json",
"User-Agent": "MyCronJob/1.0"
},
"body": "{\"event\": \"scheduled_check\"}"
},
"requestMethod": 1 // 0=GET, 1=POST, 2=PUT, 3=PATCH, 4=DELETE, etc.
}
}
```
### 7. Job with Failure Notifications
```json
{
"job": {
"url": "https://example.com/critical-task",
"enabled": true,
"title": "Critical Task",
"notifications": {
"onFailure": true,
"onSuccess": false,
"onDisable": true
}
}
}
```
**Notification Options:**
- `onFailure`: Notify after job fails (set `onFailureMinutes` for threshold)
- `onSuccess`: Notify when job succeeds after previous failure
- `onDisable`: Notify when job is automatically disabled
### 8. Get Job Execution History
```python
import requests
API_KEY = "your_api_key_here"
JOB_ID = 12345
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(
f"https://api.cron-job.org/jobs/{JOB_ID}/history",
headers=headers
)
data = response.json()
print(f"Last {len(data['history'])} executions:")
for item in data['history']:
print(f" {item['date']}: Status {item['httpStatus']} ({item['duration']}ms)")
print(f"\nNext executions: {data['predictions']}")
```
**Rate Limit:** 5 requests/second
### 9. Schedule Examples
**Every day at 2:30 AM EST:**
```json
{
"schedule": {
"timezone": "America/New_York",
"hours": [2],
"mdays": [-1],
"minutes": [30],
"months": [-1],
"wdays": [-1]
}
}
```
**Every Monday and Friday at 9 AM UTC:**
```json
{
"schedule": {
"timezone": "UTC",
"hours": [9],
"mdays": [-1],
"minutes": [0],
"months": [-1],
"wdays": [1, 5] // 0=Sunday, 1=Monday, ..., 6=Saturday
}
}
```
**Every 15 minutes:**
```json
{
"schedule": {
"timezone": "UTC",
"hours": [-1],
"mdays": [-1],
"minutes": [0, 15, 30, 45],
"months": [-1],
"wdays": [-1]
}
}
```
### 10. Delete a Job
```python
import requests
API_KEY = "your_api_key_here"
JOB_ID = 12345
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.delete(
f"https://api.cron-job.org/jobs/{JOB_ID}",
headers=headers
)
print("Job deleted" if response.status_code == 200 else "Delete failed")
```
**Rate Limit:** 5 requests/second
## Reference Files
This skill includes comprehensive documentation in `references/`:
- **api.md** - Complete REST API reference including:
- Authentication and security
- Rate limits and quotas
- All API endpoints (jobs, history)
- Request/response formats
- Object schemas (Job, DetailedJob, JobSchedule, HistoryItem, etc.)
- HTTP status codes and error handling
- Timing statistics and performance metrics
Use the reference file for:
- Detailed object schema documentation
- Complete list of request/response fields
- Advanced configuration options
- Troubleshooting API errors
## Working with This Skill
### For Beginners
1. Start by **reading the API authentication section** in `references/api.md`
2. Generate an API key in the Cron-Job.org Console
3. Use the **Quick Reference examples** above to:
- List your existing jobs
- Create a simple job with a basic schedule
- View execution history
4. Test with curl or Python before building integrations
### For Intermediate Users
Focus on:
- **Custom headers and authentication** for API integrations
- **Notification settings** for failure alerting
- **Schedule optimization** using timezone-aware cron expressions
- **Execution history analysis** for monitoring job performance
- **Rate limit management** for high-volume applications
### For Advanced Users
Explore:
- **Batch job management** with proper rate limit handling
- **Performance optimization** using timing statistics from HistoryItem
- **Error handling strategies** based on HTTP status codes
- **IP allowlisting** for production security
- **Sustaining membership** for higher API quotas (5,000 requests/day)
### Navigation Tips
- Use `references/api.md` for complete endpoint documentation
- Check HTTP status codes section for error troubleshooting
- Review object schemas for all available configuration fields
- Reference the schedule examples for common cron patterns
## Common Patterns
### Pattern 1: Health Check Monitoring
Create a job that pings your service every 5 minutes and notifies on failure:
```python
job = {
"url": "https://myapp.com/health",
"enabled": True,
"title": "App Health Check",
"saveResponses": False,
"schedule": {
"timezone": "UTC",
"hours": [-1],
"mdays": [-1],
"minutes": [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55],
"months": [-1],
"wdays": [-1]
},
"notifications": {
"onFailure": True,
"onSuccess": True,
"onDisable": True
}
}
```
### Pattern 2: Daily Data Sync
Trigger a webhook at 3 AM daily with custom headers:
```python
job = {
"url": "https://api.myapp.com/sync",
"enabled": True,
"title": "Daily Data Sync",
"requestMethod": 1, # POST
"extendedData": {
"headers": {
"X-Sync-Token": "secret",
"Content-Type": "application/json"
},
"body": '{"action": "daily_sync"}'
},
"schedule": {
"timezone": "America/Los_Angeles",
"hours": [3],
"mdays": [-1],
"minutes": [0],
"months": [-1],
"wdays": [-1]
}
}
```
### Pattern 3: Weekday Business Hours Job
Run a job every weekday at 9 AM and 5 PM:
```python
job = {
"url": "https://example.com/business-task",
"enabled": True,
"title": "Business Hours Task",
"schedule": {
"timezone": "America/New_York",
"hours": [9, 17],
"mdays": [-1],
"minutes": [0],
"months": [-1],
"wdays": [1, 2, 3, 4, 5] # Monday-Friday
}
}
```
## HTTP Status Codes
| Code | Description |
|------|-------------|
| 200 | OK - Request succeeded |
| 400 | Bad Request - Invalid request or input data |
| 401 | Unauthorized - Invalid API key |
| 403 | Forbidden - API key cannot be used from this origin |
| 404 | Not Found - Resource doesn't exist |
| 409 | Conflict - Resource already exists |
| 429 | Too Many Requests - Quota or rate limit exceeded |
| 500 | Internal Server Error |
## Important Limits
- **Daily Quota**: 100 requests/day (default), 5,000 requests/day (sustaining members)
- **Job Creation**: 1 request/second, 5 requests/minute
- **Other Endpoints**: 5 requests/second
- **Job Timeout**: Configurable per job (default system timeout applies)
- **Response Storage**: Enable `saveResponses` to store headers/body in history
## Security Best Practices
1. **Protect API Keys**: Treat them like passwords, never commit to version control
2. **Enable IP Restrictions**: Limit API access to specific IP addresses
3. **Use HTTPS**: All API communication is HTTPS-only
4. **Rotate Keys**: Periodically regenerate API keys
5. **Monitor Usage**: Track API request counts to avoid quota exhaustion
## Resources
### Official Documentation
- REST API Docs: https://docs.cron-job.org/rest-api.html
- Console: https://console.cron-job.org/
### Supported Timezones
See the official documentation for a complete list of supported timezone values (e.g., "UTC", "America/New_York", "Europe/London").
### Example Use Cases
- **API Health Checks**: Monitor service availability
- **Data Synchronization**: Trigger scheduled data imports/exports
- **Report Generation**: Generate and send periodic reports
- **Cache Warming**: Pre-load caches before peak traffic
- **Webhook Delivery**: Send scheduled webhook notifications
- **Backup Triggers**: Initiate automated backup processes
## Troubleshooting
### 401 Unauthorized
- Verify API key is correct
- Check Authorization header format: `Authorization: Bearer YOUR_KEY`
- Ensure API key hasn't been revoked
### 403 Forbidden
- Check if IP restrictions are enabled
- Verify your IP address is allowlisted
### 429 Too Many Requests
- Review rate limits for specific endpoint
- Implement exponential backoff
- Consider sustaining membership for higher limits
### Job Not Executing
- Verify job is enabled
- Check schedule configuration
- Review `nextExecution` timestamp
- Check if job has been auto-disabled due to failures
### Missing Response Data in History
- Ensure `saveResponses` is set to `true`
- Use the detailed history item endpoint for headers/body
## Notes
- All timestamps are Unix timestamps in seconds
- Schedule uses arrays where `[-1]` means "all values" (every hour, every day, etc.)
- Job execution times may have jitter (scheduling delay) - check `HistoryItem.jitter`
- Failed jobs may be automatically disabled based on notification settings
- Execution history is limited; use the API to retrieve recent items
## Updating
This skill was generated from official Cron-Job.org documentation. For the latest API changes:
1. Visit https://docs.cron-job.org/rest-api.html
2. Check for new endpoints or schema changes
3. Update your integration code accordingly

15
skills/cronjob-org/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "cronjob-org",
"description": "Interacts with the cronjob.org API.",
"version": "1.0.0",
"author": {
"name": "Tim Green",
"email": "rawveg@gmail.com"
},
"homepage": "https://github.com/rawveg/claude-skills-marketplace",
"repository": "https://github.com/rawveg/claude-skills-marketplace",
"license": "MIT",
"keywords": ["cronjob-org", "cronjob.org", "Claude Code"],
"category": "productivity",
"strict": false
}

241
skills/cronjob-org/references/api.md Normal file
View File

@@ -0,0 +1,241 @@
# Cronjob-Org - Api
**Pages:** 1
---
## REST API — cron-job.org documentation
**URL:** https://docs.cron-job.org/rest-api.html
**Contents:**
- REST API
- Introduction
- Limitations
- Requests
- Endpoint
- Authentication
- Content Type
- HTTP Status Codes
- Examples
- API Methods
cron-job.org provides an API which enables users to programatically create, update, delete and view cron jobs. The API provides a REST-like interface with API-key based authorization and JSON request and response payload. Given this, the API should be easily usable from virtually any programming language.
In order to prevent abuse of our service, we enforce a daily usage limit. By default, this limit is 100 requests per day, but can be increased upon request. For sustaining members, a higher limit of 5,000 requests per day applies.
Apart from the daily request limit, individual rate limits might apply depending on the specific API call made. Those limits are mentioned in the documentation of the specific API method.
The API endpoint is reachable via HTTPS at:
All requests to the API must be authenticated via an API key supplied in the Authorization bearer token header. API keys can be retrieved/generated in the cron-job.org Console at “Settings”. An example header could look like:
Access via a specific API key might be restricted to certain IP addresses, if configured in the Console. In this case, requests from non-allowlisted IP addresses will be rejected with an HTTP error code of 403.
API keys are secrets, just like a password. They allow access to your cron-job.org account via the API and should always be treated confidentially. We highly recommend to also enable the IP address restriction whenever possible.
In case a request requires a payload, it must be JSON-encoded and the Content-Type header must be set to application/json. In case the Content-Type header is missing or contains a different value, the request payload will be ignored.
The following status codes can be returned by the API:
OK: Request succeeded
Bad request: Invalid request / invalid input data
Unauthorized: Invalid API key
Forbidden: API key cannot be used from this origin
Not found: The requested resource could not be found
Conflict, e.g. because a resource already exists
API key quota, resource quota or rate limit exceeded
Internal server error
Example request via curl:
Example request via Python:
List all jobs in this account:
List of jobs present in the account
true in case some jobs could not be retrieved because of internal errors and the list might be incomplete, otherwise false
Max. 5 requests per second.
Retrieve detailed information for a specific cron job identified by its jobId:
Max. 5 requests per second.
Creating a new cron job:
Job (only the url field is mandatory)
Identifier of the created job
Max. 1 request per second and 5 requests per minute.
Updating a cron job identified by its jobId:
Job delta (only include changed fields - unchanged fields can be left out)
Max. 5 requests per second.
Deleting a cron job identified by its jobId:
Max. 5 requests per second.
Retrieve the execution history for a specific cron job identified by its jobId:
The last execution history items
Unix timestamps (in seconds) of the predicted next executions (up to 3)
Please note that the headers and body fields of the HistoryItem objects will not be populated. In order to retrieve headers and body, see Retrieving Job Execution History Item Details.
Max. 5 requests per second.
Retrieve details for a specific history item identified by its identifier for a specific cron job identified by its jobId:
Max. 5 requests per second.
The Job object represents a cron job.
Job identifier (read only; ignored during job creation or update)
Whether the job is enabled (i.e. being executed) or not
Whether to save job response header/body or not
Last execution status (read only)
0 (Unknown / not executed yet)
Last execution duration in milliseconds (read only)
Unix timestamp of last execution (in seconds; read only)
Unix timestamp of predicted next execution (in seconds), null if no prediction available (read only)
Job timeout in seconds
-1 (i.e. use default timeout)
Whether to treat 3xx HTTP redirect status codes as success or not
The identifier of the folder this job resides in
* Value when field is omitted while creating a job.
The DetailedJob object represents a cron job with detailed settings. It consists of all members of the Job object plus the following additional fields.
HTTP authentication settings
JobNotificationSettings
Notification settings
Extended request data
The JobAuth object represents HTTP (basic) authentication settings for a job.
Whether to enable HTTP basic authentication or not.
HTTP basic auth username
HTTP basic auth password
* Value when field is omitted while creating a job.
The JobNotificationSettings specifies notification settings for a job.
Whether to send a notification on job failure or not.
How many failures are required before a notification is sent (min 1).
Whether to send a notification when the job succeeds after a prior failure or not.
Whether to send a notification when the job has been disabled automatically or not.
* Value when field is omitted while creating a job.
The JobExtendedData holds extended request data for a job.
Request headers (key-value dictionary)
* Value when field is omitted while creating a job.
Unknown / not executed yet
Failed (could not connect to host)
Failed (too much response data)
Failed (internal errors)
Failed (unknown reason)
Monitoring job (used in a status monitor)
The JobSchedule object represents the execution schedule of a job.
Schedule time zone (see here for a list of supported values)
Date/time (in job’s time zone) after which the job expires, i.e. after which it is not scheduled anymore (format: YYYYMMDDhhmmss, 0 = does not expire)
Hours in which to execute the job (0-23; [-1] = every hour)
Days of month in which to execute the job (1-31; [-1] = every day of month)
Minutes in which to execute the job (0-59; [-1] = every minute)
Months in which to execute the job (1-12; [-1] = every month)
Days of week in which to execute the job (0=Sunday - 6=Saturday; [-1] = every day of week)
* Value when field is omitted while creating a job.
The HistoryItem object represents a job history log entry corresponding to one execution of the job.
Identifier of the associated cron job
Identifier of the history item
Unix timestamp (in seconds) of the actual execution
Unix timestamp (in seconds) of the planned/ideal execution
Scheduling jitter in milliseconds
Job URL at time of execution
Actual job duration in milliseconds
Detailed job status Description
HTTP status code returned by the host, if any
Raw response headers returned by the host (null if unavailable)
Raw response body returned by the host (null if unavailable)
Additional timing information for this request
The HistoryItemStats object contains additional timing information for a job execution history item.
Time from transfer start until name lookups completed (in microseconds)
Time from transfer start until socket connect completed (in microseconds)
Time from transfer start until SSL handshake completed (n microseconds) - 0 if not using SSL
Time from transfer start until beginning of data transfer (in microseconds)
Time from transfer start until the first response byte is received (in microseconds)
Total transfer time (in microseconds)
---

7
skills/cronjob-org/references/index.md Normal file
View File

@@ -0,0 +1,7 @@
# Cronjob-Org Documentation Index
## Categories
### Api
**File:** `api.md`
**Pages:** 1