{ "openapi": "3.1.0", "info": { "title": "CronRadar Ingestion API", "version": "1.0.0", "description": "Public telemetry and framework-discovery API. Version 1 is additive-only. Breaking changes use a new major-version base URL with a documented overlap window. Management endpoints used by the CronRadar web application are not a customer integration surface.", "x-compatibility": { "policy": "additive-only within a major version", "breakingChanges": "publish a new major version and operate both versions for a documented overlap window", "legacyAliases": [ "/ping/*", "/api/sync", "/api/sync/status" ] } }, "servers": [ { "url": "https://cron.life/api/v1", "description": "Production ingestion service" } ], "paths": { "/ping/{monitor_key}/{api_key}": { "get": { "operationId": "getHeartbeatWithPathKey", "summary": "Record a successful completion without duration tracking.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postHeartbeatWithPathKey", "summary": "Record a successful completion without duration tracking.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ping/{monitor_key}": { "get": { "operationId": "getHeartbeatWithBasicAuth", "summary": "Record a successful completion without duration tracking.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postHeartbeatWithBasicAuth", "summary": "Record a successful completion without duration tracking.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ping/{monitor_key}/{api_key}/start": { "get": { "operationId": "getStartWithPathKey", "summary": "Record that an execution started.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postStartWithPathKey", "summary": "Record that an execution started.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ping/{monitor_key}/start": { "get": { "operationId": "getStartWithBasicAuth", "summary": "Record that an execution started.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postStartWithBasicAuth", "summary": "Record that an execution started.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ping/{monitor_key}/{api_key}/complete": { "get": { "operationId": "getCompleteWithPathKey", "summary": "Record successful completion and duration after start.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postCompleteWithPathKey", "summary": "Record successful completion and duration after start.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeCompletion" } } } }, "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ping/{monitor_key}/complete": { "get": { "operationId": "getCompleteWithBasicAuth", "summary": "Record successful completion and duration after start.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postCompleteWithBasicAuth", "summary": "Record successful completion and duration after start.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeCompletion" } } } }, "responses": { "200": { "description": "Telemetry accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ping/{monitor_key}/{api_key}/fail": { "get": { "operationId": "getFailWithPathKey", "summary": "Record explicit failure and create an incident immediately.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." }, { "name": "message", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1000 }, "description": "Bounded human-readable failure context. Do not send secrets, logs, or job payloads." } ], "responses": { "200": { "description": "Failure recorded and incident created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postFailWithPathKey", "summary": "Record explicit failure and create an incident immediately.", "tags": [ "Telemetry" ], "security": [], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "api_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ck_app_" }, "description": "Application API key. Prefer Basic auth for diagnostics so secrets do not enter URLs." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." }, { "name": "message", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1000 }, "description": "Bounded human-readable failure context. Do not send secrets, logs, or job payloads." } ], "responses": { "200": { "description": "Failure recorded and incident created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ping/{monitor_key}/fail": { "get": { "operationId": "getFailWithBasicAuth", "summary": "Record explicit failure and create an incident immediately.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." }, { "name": "message", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1000 }, "description": "Bounded human-readable failure context. Do not send secrets, logs, or job payloads." } ], "responses": { "200": { "description": "Failure recorded and incident created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postFailWithBasicAuth", "summary": "Record explicit failure and create an incident immediately.", "tags": [ "Telemetry" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "monitor_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable automation key." }, { "name": "schedule", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Five-field cron expression. Required to auto-register a missing monitor." }, { "name": "gracePeriod", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60 }, "description": "Grace period in seconds." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Opaque execution identifier shared by lifecycle events for one logical run." }, { "name": "attempt", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional zero-based scheduler retry attempt." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional duplicate-suppression key." }, { "name": "message", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1000 }, "description": "Bounded human-readable failure context. Do not send secrets, logs, or job payloads." } ], "responses": { "200": { "description": "Failure recorded and incident created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/sync": { "post": { "operationId": "syncRecurringAutomations", "summary": "Reconcile an authoritative framework registry.", "tags": [ "Discovery" ], "security": [ { "basicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } } }, "responses": { "200": { "description": "Registry processed. Per-monitor validation and plan-capacity outcomes are in the response arrays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/sync/status": { "get": { "operationId": "getSyncStatus", "summary": "List discovered and manually registered monitors for the authenticated application.", "tags": [ "Discovery" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "description": "Current monitor registry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Application API key as username; empty password." } }, "responses": { "BadRequest": { "description": "Invalid monitor key, schedule, grace period, or request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "API key missing, malformed, revoked, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PaymentRequired": { "description": "Plan or trial does not permit creation of a new active automation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Application or monitor not found. Supply a schedule to auto-register a missing monitor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Application API-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } } }, "InternalError": { "description": "Unexpected ingestion-service error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retry_after": { "type": "integer" } } }, "PingResponse": { "type": "object", "required": [ "status", "monitor", "pingedAt" ], "properties": { "status": { "const": "ok" }, "monitor": { "type": "string" }, "pingedAt": { "type": "string", "format": "date-time" }, "warning": { "type": [ "string", "null" ] } } }, "FailureResponse": { "type": "object", "required": [ "status", "monitor", "recordedAt", "message" ], "properties": { "status": { "const": "failure_recorded" }, "monitor": { "type": "string" }, "recordedAt": { "type": "string", "format": "date-time" }, "message": { "type": "string" }, "failureMessage": { "type": [ "string", "null" ] } } }, "OutcomeCompletion": { "type": "object", "required": [ "outcomes" ], "additionalProperties": false, "properties": { "outcomes": { "type": "object", "maxProperties": 5, "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "boolean" } ] } } } }, "SyncMonitor": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": [ "string", "null" ] }, "schedule": { "type": [ "string", "null" ] }, "gracePeriod": { "type": [ "integer", "null" ], "minimum": 60 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "SyncRequest": { "type": "object", "required": [ "source", "monitors" ], "properties": { "source": { "type": "string", "description": "Stable integration identifier such as hangfire." }, "version": { "type": [ "string", "null" ] }, "mode": { "type": [ "string", "null" ], "enum": [ "reconcile", null ], "description": "reconcile or omitted means the registry is authoritative for source." }, "monitors": { "type": "array", "items": { "$ref": "#/components/schemas/SyncMonitor" } } } }, "SyncResult": { "type": "object", "required": [ "key", "name", "action" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "created_plan_limited", "updated", "unchanged", "paused_removed" ] } } }, "SyncError": { "type": "object", "required": [ "key", "error" ], "properties": { "key": { "type": "string" }, "error": { "type": "string" } } }, "SyncSummary": { "type": "object", "required": [ "total", "created", "updated", "unchanged", "removed", "errors" ], "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "removed": { "type": "integer" }, "errors": { "type": "integer" } } }, "SyncResponse": { "type": "object", "required": [ "source", "timestamp", "created", "updated", "unchanged", "removed", "errors", "summary" ], "properties": { "source": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "created": { "type": "array", "items": { "$ref": "#/components/schemas/SyncResult" } }, "updated": { "type": "array", "items": { "$ref": "#/components/schemas/SyncResult" } }, "unchanged": { "type": "array", "items": { "$ref": "#/components/schemas/SyncResult" } }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/SyncResult" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/SyncError" } }, "summary": { "$ref": "#/components/schemas/SyncSummary" } } }, "SyncStatusMonitor": { "type": "object", "required": [ "monitorKey", "name", "schedule", "gracePeriod", "createdAt", "updatedAt", "status" ], "properties": { "monitorKey": { "type": "string" }, "name": { "type": "string" }, "schedule": { "type": "string" }, "gracePeriod": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastPingAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "healthy", "warning", "critical", "paused" ] } } }, "SyncStatusResponse": { "type": "object", "required": [ "applicationId", "totalMonitors", "monitors", "timestamp" ], "properties": { "applicationId": { "type": "string" }, "totalMonitors": { "type": "integer" }, "monitors": { "type": "array", "items": { "$ref": "#/components/schemas/SyncStatusMonitor" } }, "timestamp": { "type": "string", "format": "date-time" } } } } } }