{"openapi":"3.1.0","info":{"title":"Cronicle API","description":"Cronicle is a modern, web-based task scheduler with job history, plugin support, and multi-server capabilities.\n\nThis API provides access to job management, server status, and application statistics for the Haiven\ninfrastructure task scheduling system.\n\n**Features:**\n- Job scheduling and management\n- Server group configuration\n- Real-time job execution\n- Job history and logs\n- Plugin system for custom job types\n- Multi-server job distribution\n","version":"1.0","contact":{"name":"Haiven Infrastructure","url":"https://scheduler.haiven.site"},"license":{"name":"MIT","url":"https://github.com/cronicle-edge/cronicle-edge/blob/main/LICENSE"}},"servers":[{"url":"https://scheduler.haiven.site","description":"Production scheduler (via Traefik)"},{"url":"http://cronicle:3012","description":"Internal Docker service endpoint"}],"tags":[{"name":"Application","description":"Application status and health endpoints"},{"name":"Jobs","description":"Job management and execution"},{"name":"Events","description":"Scheduled event management"},{"name":"Servers","description":"Server and server group management"},{"name":"History","description":"Job execution history"}],"security":[{"ApiKeyQuery":[]},{"ApiKeyHeader":[]}],"paths":{"/api/app/ping":{"get":{"tags":["Application"],"summary":"Health check","description":"Simple health check endpoint to verify Cronicle is running","security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"description":{"type":"string","example":"success"}}}}}}}}},"/api/app/stats":{"get":{"tags":["Application"],"summary":"Application statistics","description":"Retrieve comprehensive application statistics including:\n- Active jobs count\n- Job queue status\n- Memory usage\n- Server health metrics\n\nUsed by Prometheus for metrics scraping.\n","security":[],"responses":{"200":{"description":"Statistics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppStats"}}}}}}},"/api/app/get_schedule":{"get":{"tags":["Events"],"summary":"Get scheduled events","description":"Retrieve all scheduled events (jobs) configured in Cronicle","responses":{"200":{"description":"Schedule retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"rows":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}}}}},"/api/app/get_event":{"get":{"tags":["Events"],"summary":"Get single event","description":"Retrieve details for a specific scheduled event by ID","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Event ID","example":"evt_abc123"}],"responses":{"200":{"description":"Event retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"event":{"$ref":"#/components/schemas/Event"}}}}}},"404":{"description":"Event not found"}}}},"/api/app/run_event":{"post":{"tags":["Jobs"],"summary":"Run event immediately","description":"Trigger immediate execution of a scheduled event.\n**Auth:** Requires `?api_key=` query parameter; the `X-API-Key` header\ndoes NOT work for this write endpoint.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Event ID to execute","example":"evt_abc123"},"params":{"type":"object","description":"Optional parameters to pass to the job","additionalProperties":true}}}}}},"responses":{"200":{"description":"Job started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"ids":{"type":"array","items":{"type":"string"},"description":"Job IDs of started executions"}}}}}}}}},"/api/app/abort_job":{"post":{"tags":["Jobs"],"summary":"Abort running job","description":"Stop a currently running job.\n**Auth:** Requires `?api_key=` query parameter; the `X-API-Key` header\ndoes NOT work for this write endpoint.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Job ID to abort","example":"job_abc123"}}}}}},"responses":{"200":{"description":"Job aborted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0}}}}}}}}},"/api/app/get_active_jobs":{"get":{"tags":["Jobs"],"summary":"Get active jobs","description":"List all currently running jobs across all servers","responses":{"200":{"description":"Active jobs retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}}}}}}}},"/api/app/get_job_status":{"get":{"tags":["Jobs"],"summary":"Get job status","description":"Get the current status and details of a specific job","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Job ID","example":"job_abc123"}],"responses":{"200":{"description":"Job status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"job":{"$ref":"#/components/schemas/Job"}}}}}}}}},"/api/app/get_history":{"get":{"tags":["History"],"summary":"Get job history","description":"Retrieve job execution history with optional filtering","parameters":[{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Pagination offset"},{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Number of records to return"},{"name":"event_id","in":"query","schema":{"type":"string"},"description":"Filter by event ID"}],"responses":{"200":{"description":"History retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"rows":{"type":"array","items":{"$ref":"#/components/schemas/HistoryItem"}},"list":{"type":"object","properties":{"length":{"type":"integer"}}}}}}}}}}},"/api/app/get_job_log":{"get":{"tags":["History"],"summary":"Get job log","description":"Retrieve the execution log for a completed job","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Job ID","example":"job_abc123"}],"responses":{"200":{"description":"Log retrieved successfully","content":{"text/plain":{"schema":{"type":"string","description":"Job execution log output"}}}}}}},"/api/app/get_servers":{"get":{"tags":["Servers"],"summary":"Get server list","description":"Retrieve all registered Cronicle servers","responses":{"200":{"description":"Server list retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"rows":{"type":"array","items":{"$ref":"#/components/schemas/Server"}}}}}}}}}},"/api/app/get_server_groups":{"get":{"tags":["Servers"],"summary":"Get server groups","description":"Retrieve all configured server groups","responses":{"200":{"description":"Server groups retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ServerGroup"}}}}}}}}}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Cronicle API key passed as a request header. **Works for read-only (GET)\nendpoints only.** Write operations (create/update/delete events,\nrun/abort jobs) fail when authenticated via header. Use ApiKeyQuery\nfor writes.\n"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Cronicle API key passed as a URL query parameter (`?api_key=<key>`).\n**Required for all write operations.** Also works for reads.\n"}},"schemas":{"AppStats":{"type":"object","properties":{"version":{"type":"string","example":"1.0.0","description":"Cronicle version"},"hostname":{"type":"string","example":"haiven-scheduler"},"server_time":{"type":"integer","description":"Current server time (epoch)"},"uptime":{"type":"integer","description":"Server uptime in seconds"},"active_jobs":{"type":"integer","description":"Number of currently running jobs"},"pending_jobs":{"type":"integer","description":"Number of jobs in queue"},"completed_jobs_today":{"type":"integer","description":"Jobs completed in last 24h"},"failed_jobs_today":{"type":"integer","description":"Jobs failed in last 24h"},"mem_used":{"type":"integer","description":"Memory usage in bytes"},"cpu_percent":{"type":"number","description":"CPU usage percentage"}}},"Event":{"type":"object","properties":{"id":{"type":"string","example":"evt_abc123"},"title":{"type":"string","example":"Daily Log Cleanup"},"enabled":{"type":"boolean","example":true},"category":{"type":"string","example":"Maintenance"},"plugin":{"type":"string","example":"shellplug","description":"Plugin type (shellplug, urlplug, etc.)"},"target":{"type":"string","example":"allgrp","description":"Server group target"},"timing":{"type":"object","properties":{"hours":{"type":"array","items":{"type":"integer"}},"minutes":{"type":"array","items":{"type":"integer"}},"days":{"type":"array","items":{"type":"integer"}}}},"params":{"type":"object","description":"Plugin-specific parameters"},"created":{"type":"integer","description":"Creation timestamp (epoch)"},"modified":{"type":"integer","description":"Last modified timestamp (epoch)"}}},"Job":{"type":"object","properties":{"id":{"type":"string","example":"job_abc123"},"event":{"type":"string","description":"Parent event ID"},"event_title":{"type":"string","example":"Daily Log Cleanup"},"hostname":{"type":"string","example":"haiven-scheduler"},"pid":{"type":"integer","description":"Process ID"},"progress":{"type":"number","minimum":0,"maximum":1,"description":"Job progress (0-1)"},"elapsed":{"type":"integer","description":"Elapsed time in seconds"},"time_start":{"type":"integer","description":"Start timestamp (epoch)"},"complete":{"type":"boolean"},"code":{"type":"integer","description":"Exit code (0 = success)"},"description":{"type":"string","description":"Job status description"}}},"HistoryItem":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"event_title":{"type":"string"},"hostname":{"type":"string"},"time_start":{"type":"integer"},"time_end":{"type":"integer"},"elapsed":{"type":"number"},"code":{"type":"integer"},"description":{"type":"string"},"perf":{"type":"object","description":"Performance metrics"}}},"Server":{"type":"object","properties":{"hostname":{"type":"string","example":"haiven-scheduler"},"ip":{"type":"string","example":"10.10.0.50"},"manager":{"type":"boolean","description":"Is this the manager node"},"workers":{"type":"integer","description":"Number of worker slots"},"active_jobs":{"type":"integer"},"uptime":{"type":"integer"}}},"ServerGroup":{"type":"object","properties":{"id":{"type":"string","example":"allgrp"},"title":{"type":"string","example":"All Servers"},"regexp":{"type":"string","description":"Hostname regex pattern"},"master":{"type":"boolean","description":"Include manager server"}}}}}}