API Documentation

Getting Started

The CronPulse API allows you to programmatically manage your projects and cron jobs. All API requests require authentication using an API key.

Base URL

https://app.cronpulse.live/api/v1

Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: cpk_your_api_key_here" https://app.cronpulse.live/api/v1/projects

Projects

List Projects

GET
GET /projects

Response:

[
  {
    "id": "clxxx...",
    "name": "My Project",
    "url": "https://example.com",
    "jobs": [
      {
        "id": "clyyy...",
        "name": "Daily Backup",
        "lastStatus": "success"
      }
    ]
  }
]

Create Project

POST
POST /projects

Request Body:

{
  "name": "New Project",
  "url": "https://example.com"
}

Update Project

PUT
PUT /projects/{id}

Delete Project

DELETE
DELETE /projects/{id}

⚠️ This will also delete all associated jobs and their data.

Jobs

List Jobs

GET
GET /jobs?projectId={projectId}

Response:

[
  {
    "id": "clyyy...",
    "name": "Health Check",
    "projectId": "clxxx...",
    "url": "https://example.com/health",
    "method": "GET",
    "schedule": "*/5 * * * *",
    "heartbeat": true,
    "heartbeatTolerance": 5,
    "timeout": 30,
    "expectedStatusCode": 200,
    "headers": {},
    "body": null,
    "lastStatus": "success",
    "lastActivityAt": "2024-01-30T12:00:00Z",
    "nextRunAt": "2024-01-30T12:05:00Z"
  }
]

Create Job

POST
POST /jobs

Request Body:

{
  "name": "Health Check",
  "projectId": "clxxx...",
  "url": "https://example.com/health",
  "method": "GET",
  "schedule": "*/5 * * * *",
  "heartbeat": true,
  "heartbeatTolerance": 5,
  "timeout": 30,
  "expectedStatusCode": 200,
  "headers": {
    "Authorization": "Bearer token"
  }
}

Required fields: name, projectId, url, method, schedule

Get Job

GET
GET /jobs/{id}

Update Job

PUT
PUT /jobs/{id}

Request Body:

{
  "name": "Updated Job Name",
  "url": "https://example.com/new-endpoint",
  "schedule": "0 * * * *",
  "heartbeat": false,
  "timeout": 60
}

All fields are optional. Only include fields you want to update.

Delete Job

DELETE
DELETE /jobs/{id}

⚠️ This will permanently delete the job and all its execution history.

Examples

Complete Workflow Example

# 1. Create a project
PROJECT_ID=$(curl -X POST https://app.cronpulse.live/api/v1/projects \
  -H "X-API-Key: cpk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My API Project", "url": "https://example.com"}' \
  | jq -r '.id')

# 2. Create a job
JOB_ID=$(curl -X POST https://app.cronpulse.live/api/v1/jobs \
  -H "X-API-Key: cpk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Health Check",
    "projectId": "'$PROJECT_ID'",
    "url": "https://example.com/health",
    "method": "GET",
    "schedule": "*/5 * * * *",
    "heartbeat": true
  }' \
  | jq -r '.id')

# 3. Monitor the job
curl -H "X-API-Key: cpk_your_api_key" \
  https://app.cronpulse.live/api/v1/jobs/$JOB_ID

Error Handling

All errors follow this format:

{
  "error": "Error message"
}
400
Bad Request - Missing or invalid parameters
401
Unauthorized - Missing or invalid API key
403
Forbidden - Insufficient permissions
404
Not Found
500
Internal Server Error

Permissions

API keys can have the following permissions:

read:projects
- Read project data
write:projects
- Create, update, and delete projects
read:jobs
- Read job data
write:jobs
- Create, update, and delete jobs
*
- Full access