Initial commit
This commit is contained in:
Zhongwei Li
524
skills/cronjob-org/SKILL.md
Normal file
524
skills/cronjob-org/SKILL.md
Normal 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
|
||||
Reference in New Issue
Block a user