cronmaster/howto/API.md

Cr*nMaster API

REST API for managing cron jobs and system monitoring.

Authentication

The API supports two authentication methods:

1. API Key (Recommended)

Set the API_KEY environment variable and include it as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Note: If no API_KEY is set, the API is publicly accessible (for development).

2. Session Cookies

Login with password to get a session cookie, then use it for subsequent requests:

1. Login:

curl -X POST https://your-cronmaster-url.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"your-password"}'

2. Use session cookie:

curl -b cookies.txt https://your-cronmaster-url.com/api/cronjobs

Note: Session cookies are HTTP-only and expire automatically.

All API endpoints work with either authentication method.

Endpoints

GET /api/cronjobs

List all cron jobs.

Response:

{
  "success": true,
  "data": [
    {
      "id": "fccview-0",
      "schedule": "0 2 * * *",
      "command": "/usr/bin/echo hello",
      "comment": "Test job",
      "user": "fccview",
      "logsEnabled": false,
      "isPaused": false
    }
  ]
}

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-cronmaster-url.com/api/cronjobs

---

GET /api/cronjobs/:id

Get details for a specific cron job.

Parameters:

• id (string) - Cron job ID

Response:

{
  "success": true,
  "data": {
    "id": "fccview-0",
    "schedule": "0 2 * * *",
    "command": "/usr/bin/echo hello",
    "comment": "Test job",
    "user": "fccview",
    "logsEnabled": false,
    "isPaused": false
  }
}

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-cronmaster-url.com/api/cronjobs/fccview-0

---

PATCH /api/cronjobs/:id

Update a cron job.

Parameters:

• id (string) - Cron job ID

Request:

{
  "schedule": "0 3 * * *",
  "command": "/usr/bin/echo updated",
  "comment": "Updated job",
  "logsEnabled": true
}

Response:

{
  "success": true,
  "message": "Cron job updated successfully"
}

Example:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"0 3 * * *","command":"/usr/bin/echo updated"}' \
  https://your-cronmaster-url.com/api/cronjobs/fccview-0

---

DELETE /api/cronjobs/:id

Delete a cron job.

Parameters:

• id (string) - Cron job ID

Response:

{
  "success": true,
  "message": "Cron job deleted successfully"
}

Example:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-cronmaster-url.com/api/cronjobs/fccview-0

---

GET /api/cronjobs/:id/execute

Manually execute a cron job.

Parameters:

• id (string) - Cron job ID

Query Parameters:

• runInBackground (boolean, optional) - Whether to run the job in background. Defaults to true.

Response:

{
  "success": true,
  "runId": "run-123",
  "message": "Job execution started"
}

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-cronmaster-url.com/api/cronjobs/fccview-0/execute?runInBackground=true

---

GET /api/scripts

List all scripts.

Response:

{
  "success": true,
  "data": [
    {
      "id": "script-123",
      "filename": "backup.sh",
      "name": "Backup Script",
      "content": "#!/bin/bash\necho 'backup'",
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-cronmaster-url.com/api/scripts

---

GET /api/system-stats

Get system statistics.

Response:

{
  "uptime": "2 days, 4 hours",
  "memory": {
    "total": "16.0 GB",
    "used": "4.2 GB",
    "free": "11.8 GB",
    "usage": 26,
    "status": "Normal"
  },
  "cpu": {
    "model": "AMD Ryzen 7",
    "cores": 8,
    "usage": 15,
    "status": "Normal"
  },
  "network": {
    "speed": "1000 Mbps",
    "latency": "1ms",
    "status": "Connected"
  }
}

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-cronmaster-url.com/api/system-stats

---

GET /api/events

Server-Sent Events stream for real-time updates.

Response: SSE stream with events like:

event: job-completed
data: {"runId":"run-123","cronJobId":"fccview-0","exitCode":0}

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  https://your-cronmaster-url.com/api/events

---

GET /api/logs/stream

Stream job execution logs.

Query Parameters:

• runId (string, required) - The run ID of the job execution
• offset (number, optional) - Byte offset for streaming new content. Defaults to 0.
• maxLines (number, optional) - Maximum lines to return. Defaults to 500, min 100, max 5000.

Note: When offset=0, the endpoint only reads the last maxLines from the file for performance. This means totalLines is only returned when the file is small enough to read entirely (not truncated).

Response:

{
  "status": "running",
  "content": "[log content]",
  "newContent": "[new log content since offset]",
  "logFile": "2025-11-10_14-30-00.log",
  "isComplete": false,
  "exitCode": null,
  "fileSize": 1024,
  "offset": 0,
  "totalLines": 50,
  "displayedLines": 50,
  "truncated": false
}

Response Fields:

• status (string) - Job status: "running", "completed", or "failed"
• content (string) - The log content to display
• newContent (string) - New content since the last offset (for streaming)
• logFile (string) - Name of the log file
• isComplete (boolean) - Whether the job has completed
• exitCode (number | null) - Exit code of the job (null if still running)
• fileSize (number) - Total size of the log file in bytes
• offset (number) - Current byte offset
• totalLines (number | undefined) - Total number of lines in the file (only returned when file is small enough to read entirely)
• displayedLines (number) - Number of lines being displayed
• truncated (boolean) - Whether the content is truncated due to maxLines limit

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-cronmaster-url.com/api/logs/stream?runId=run-123&offset=0&maxLines=500"

---

GET /api/system/wrapper-check

Check if the log wrapper script has been modified from the default.

Response:

{
  "modified": false
}

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-cronmaster-url.com/api/system/wrapper-check

---

GET /api/oidc/login

Initiate OIDC (SSO) login flow. Redirects to the OIDC provider's authorization endpoint.

Note: This endpoint is only available when SSO_MODE=oidc is configured.

Response: HTTP 302 redirect to OIDC provider

Example:

curl -L https://your-cronmaster-url.com/api/oidc/login

---

GET /api/oidc/callback

OIDC callback endpoint. Handles the authorization code from the OIDC provider and creates a session.

Note: This endpoint is typically called by the OIDC provider after authentication, not directly by clients.

Query Parameters:

• code (string) - Authorization code from OIDC provider
• state (string) - State parameter for CSRF protection

Response: HTTP 302 redirect to application root

---

GET /api/oidc/logout

Initiate OIDC logout flow. Redirects to the OIDC provider's logout endpoint.

Note: This endpoint is only available when SSO_MODE=oidc is configured.

Response: HTTP 302 redirect to OIDC provider logout endpoint

Example:

curl -L https://your-cronmaster-url.com/api/oidc/logout

---

POST /api/auth/login

Login with password (alternative to API key).

Request:

{
  "password": "your-password"
}

Response:

{
  "success": true,
  "message": "Login successful"
}

Example:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"password":"your-password"}' \
  https://your-cronmaster-url.com/api/auth/login

---

GET /api/auth/check-session

Check if current session is valid (requires login first).

Response:

{
  "valid": true
}

---

POST /api/auth/logout

Logout and clear session (requires login first).

Response:

{
  "success": true,
  "message": "Logout successful"
}

Error Responses

{
  "success": false,
  "error": "Unauthorized",
  "message": "Authentication required. Use session cookie or API key (Bearer token)."
}