API docs by Redocly

Cronverse Scheduler Service API (1.0.0)

Download OpenAPI specification:

URL: https://cronverse.com License: Proprietary

Standalone AWS microservice for managing scheduled API orchestrations.

The Scheduler Service handles all scheduling and execution responsibilities for the Cronverse platform. It operates independently from the main application, accepting fully denormalized configurations and managing the entire lifecycle of scheduled API orchestrations.

Key Features

  • EventBridge Scheduler: Manages cron-based and rate-based schedules
  • Step Functions: Orchestrates execution workflows with automatic retries
  • DynamoDB: Stores execution metadata with unlimited retention
  • S3: Stores consolidated data with signed URLs for secure access
  • Webhooks: Real-time notifications for execution status changes

Authentication

All API requests require an X-API-Key header for authentication.

Webhook Notifications

The service can send webhook notifications to configured URLs when executions complete (success or failure). Webhooks are signed with HMAC-SHA256 for authenticity verification.

System

System health and status endpoints

Health check endpoint

Returns the health status of the scheduler service. This endpoint does not require authentication.

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "service": "scheduler-api",
  • "version": "1.0.0",
  • "timestamp": "2025-01-16T10:30:00Z"
}

Schedules

Schedule management operations

Create a new schedule or execute immediately

Creates a new schedule or executes immediately based on whether the schedule field is provided.

Scheduled Mode (with schedule field)

Creates an EventBridge Scheduler rule that triggers executions at the specified cron/rate expression. Returns scheduleId and createdAt.

Immediate Mode (without schedule field)

Skips EventBridge Scheduler creation and immediately triggers a Step Function execution. Returns scheduleId, executionId, and startedAt. The scheduleId is used as a namespace for tracking the execution in DynamoDB, but no persistent schedule is created. Note: GET /schedules/{id} will return 404 for immediate-only executions.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
object (Configuration)

Responses

Request samples

Content type
application/json
Example
{
  • "configuration": {
    }
}

Response samples

Content type
application/json
Example
{
  • "scheduleId": "abc123def456",
  • "createdAt": "2025-01-16T10:30:00Z"
}

Get schedule details

Retrieves the configuration and state of a specific schedule from EventBridge Scheduler.

Note: This endpoint returns 404 for immediate-only executions (created without a schedule field), since no persistent schedule is created in EventBridge. Use GET /schedules/{scheduleId}/executions to retrieve execution history for immediate executions.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

Responses

Response samples

Content type
application/json
{
  • "scheduleId": "arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123",
  • "configuration": {
    },
  • "state": "ENABLED",
  • "createdAt": "2025-01-16T10:30:00Z",
  • "modifiedAt": "2025-01-16T10:30:00Z"
}

Update schedule configuration

Updates an existing schedule's configuration. Supports partial updates. Changes take effect immediately for future executions.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

Request Body schema: application/json
required
required
object

Partial configuration update (all fields optional)

Responses

Request samples

Content type
application/json
Example
{
  • "configuration": {
    }
}

Response samples

Content type
application/json
{
  • "scheduleId": "arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123",
  • "modifiedAt": "2025-01-16T11:45:00Z"
}

Delete a schedule

Deletes a schedule from EventBridge Scheduler. This stops all future executions. Historical execution data in DynamoDB is preserved.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

Responses

Response samples

Content type
application/json
{
  • "scheduleId": "arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123",
  • "deletedAt": "2025-01-16T12:00:00Z"
}

Enable a schedule

Enables a previously disabled schedule, resuming automatic execution according to its cron expression. This is the recommended way to resume a paused schedule.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

Responses

Response samples

Content type
application/json
{
  • "scheduleId": "sch_abc123",
  • "state": "ENABLED",
  • "modifiedAt": "2025-01-16T14:30:00Z"
}

Disable a schedule

Disables a schedule, pausing automatic execution. The schedule configuration is preserved and can be re-enabled at any time using the enable endpoint. This is the recommended way to pause a schedule without deleting it.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

Responses

Response samples

Content type
application/json
{
  • "scheduleId": "sch_abc123",
  • "state": "DISABLED",
  • "modifiedAt": "2025-01-16T14:30:00Z"
}

Executions

Execution monitoring and retrieval

List executions for a schedule

Retrieves execution history from DynamoDB for a specific schedule. Results are ordered by start time (newest first) with pagination support.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of executions to return (1-100)

nextToken
string

Pagination token from previous response

Responses

Response samples

Content type
application/json
{
  • "executions": [
    ],
  • "nextToken": "eyJzY2hlZHVsZUlkIjoiYXJuOmF3czpzY2hlZHVsZXI6ZXUtY2VudHJhbC0xOjEyMzQ1Njc4OTAxMjpzY2hlZHVsZS9jcm9udmVyc2Uvc2NoZWR1bGUtYWJjMTIzIiwiZXhlY3V0aW9uSWQiOiJleGVjLTIwMjUwMTE1LWRlZjQ1NiJ9"
}

Get execution details

Retrieves detailed information about a specific execution from DynamoDB. For successful executions, includes a signed S3 URL to download the consolidated data.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

executionId
required
string
Example: exec-20250116-abc123

The unique identifier for the execution. Example: exec-20250116-abc123

Responses

Response samples

Content type
application/json
Example
{}

Manually trigger execution

Manually starts a Step Functions execution for the specified schedule. This is independent of the schedule's cron expression and does not affect future scheduled executions.

Authorizations:
ApiKeyAuth
path Parameters
scheduleId
required
string
Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

The unique identifier for the schedule (EventBridge Scheduler ARN or name). Example: arn:aws:scheduler:eu-central-1:123456789012:schedule/cronverse/schedule-abc123

Responses

Response samples

Content type
application/json
{
  • "executionId": "exec-manual-20250116-xyz789",
  • "startedAt": "2025-01-16T14:30:00Z"
}

Webhooks

Execution completion notification Webhook

The scheduler service sends this webhook when an execution completes (either successfully or with failure).

Authentication

Webhooks are signed using HMAC-SHA256 with the secret provided in the notification.secret field. The signature is sent in the X-Scheduler-Signature header as a hex-encoded string.

Signature Verification

To verify the webhook:

  1. Get the raw request body as a string
  2. Compute HMAC-SHA256 using your secret key
  3. Compare the computed signature with the X-Scheduler-Signature header
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(payload))
  .digest('hex');

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

  • Initial retry: 1 second
  • Max retries: 3
  • Backoff multiplier: 2x
Authorizations:
ApiKeyAuth
header Parameters
X-Scheduler-Signature
required
string
Example: a1b2c3d4e5f6...

HMAC-SHA256 signature of the request body (hex-encoded)

Request Body schema: application/json
required
status
required
string
executionId
required
string

Unique identifier for the execution (use for deduplication)

scheduleId
required
string

Schedule that triggered this execution

startedAt
required
string <date-time>

ISO 8601 timestamp when execution started

finishedAt
required
string <date-time>

ISO 8601 timestamp when execution completed

object

Custom metadata from configuration

dataUrl
required
string <uri>

Signed S3 URL for downloading consolidated payload (24-hour expiry)

Responses

Request samples

Content type
application/json
Example
{}