← Back to home
Documentation

CronAI Docs

Getting started guides, product concepts, and practical examples for running scheduled HTTP jobs and alerts with CronAI.

Getting Started

Create a team, add a job, choose a schedule, and configure alerts. CronAI monitors each execution and keeps a run history for debugging and alerting.

CronAI is optimized for outbound HTTP jobs and webhook-style automation. You point CronAI at an endpoint, and CronAI handles scheduling, retries, timeouts, and alerting.

Core Concepts
  • Jobs: Scheduled HTTP requests with retries, timeouts, and optional expected response checks.
  • Executions: Each individual run of a job, including status, timing, and response snippets (if enabled).
  • Alerts: Policies + channels that notify your team when failures, timeouts, anomalies, or heartbeat misses occur.
  • Teams: Shared workspaces with role-based access (owner, admin, member, viewer).
  • Workflows: Versioned DAG workflow engine (v2) is available with fan-in/fan-out execution, reruns, retries, and scheduled/manual/webhook triggers. Legacy edge-based chaining still exists for compatibility.
How Jobs Execute

CronAI executes jobs from CronAI-managed infrastructure by making outbound HTTP/webhook requests to the URL you configure. CronAI does not run arbitrary customer code.

Retries, backoff, and timeouts are enforced by CronAI, and execution results are recorded in Convex for monitoring and troubleshooting.

Scheduling
  • Cron expressions (5-part)
  • Fixed intervals (minutes)
  • Natural language schedules (AI-assisted parsing with timezone selection)
  • Timezone-aware next-run computation
Retries, Timeouts, and Alerts
  • Per-job timeout, retry count, and backoff strategy
  • Alert channels available today: Email, Slack, Discord, Webhook
  • PagerDuty (beta) and SMS/Twilio (coming soon): PagerDuty delivery is available in newer deployments; SMS remains a planning placeholder
  • Alert deduplication and cooldowns reduce repeated notifications
Webhooks and Integrations

CronAI supports outbound webhooks for alerts and managed inbound signed webhooks that can trigger jobs or workflow v2 definitions.

Integration connection and event logging endpoints are available in the REST API. GitHub Actions and Vercel provider webhook ingestion routes are available in beta, with additional provider adapters still being expanded.

  • Provider webhook beta routes: /api/v1/integrations/providers/github/:connectionId/webhook and /api/v1/integrations/providers/vercel/:connectionId/webhook
  • Managed signed inbound webhook routes: /api/v1/webhooks/:endpointToken
  • Incoming events are recorded with signature verification, dedupe, and processing status for debugging
  • Provider-triggered workflow runs include normalized providerEvent context keys (plus raw providerPayload) for easier templating
API Reference

CronAI exposes a production-usable REST API under /api/v1 with scoped API keys. Current coverage includes jobs, executions, alert policies/channels, workflow definitions/runs/schedules (v2), retention settings, audit logs, API keys, integration connections, incoming events, and managed inbound webhooks.

The API surface is still expanding in breadth and provider depth. Core platform endpoints are available today; some provider-specific integration adapters remain beta or partial.

The OpenAPI document is available at /api/v1/openapi.json.

  • Auth: Authorization: Bearer <crai_live_...>
  • Scopes: least-privilege API key scopes (jobs, executions, workflows, alerts, retention, audit, etc.)
  • Response envelope: { data, requestId } / { error, requestId }
  • Idempotency-Key support is available for workflow and webhook-trigger paths, with broader endpoint coverage improving over time
  • Provider webhook event types and selected payload fields are normalized when possible (for example GitHub workflow_run fields and Vercel deployment state)
  • Smoke script available in-repo: npm run smoke:rest (configure CRONAI_API_BASE_URL and CRONAI_API_KEY)
Examples
  • Health check: Run every minute against /health and alert on failure or timeout.
  • Deployment hook: Trigger a follow-up endpoint after CI or platform webhook delivery.
  • Heartbeat monitor: Expect a periodic callback from a worker and alert when it is missed.
What CronAI Does NOT Do
  • CronAI does not run arbitrary user code on CronAI servers.
  • CronAI does not get direct shell access to your infrastructure.
  • CronAI does not replace your application logs, traces, or APM tooling; it complements them for scheduled job reliability.

REST API Quickstart (curl)

Replace the placeholders with your CronAI deployment URL and a scoped API key from the dashboard.

# 1) Check API health
curl -s https://YOUR-CONVEX-SITE/api/v1/health | jq

# 2) List jobs
curl -s https://YOUR-CONVEX-SITE/api/v1/jobs \
  -H "Authorization: Bearer crai_live_..." | jq

# 3) Trigger a job (idempotent)
curl -s -X POST https://YOUR-CONVEX-SITE/api/v1/jobs/JOB_ID/trigger \
  -H "Authorization: Bearer crai_live_..." \
  -H "Idempotency-Key: job-trigger-001" | jq

# 4) Trigger a workflow v2 definition
curl -s -X POST https://YOUR-CONVEX-SITE/api/v1/workflows/WORKFLOW_ID/trigger \
  -H "Authorization: Bearer crai_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wf-trigger-001" \
  -d '{"contextJson":"{\"env\":\"prod\"}"}' | jq

Provider Webhooks (GitHub/Vercel Beta)

Create a provider integration connection in /settings/integrations and use the connection-specific webhook URL.

# GitHub Actions / GitHub webhooks (connection-specific)
POST /api/v1/integrations/providers/github/INTEGRATION_CONNECTION_ID/webhook
Headers:
  X-Hub-Signature-256: sha256=...
  X-GitHub-Event: workflow_run
  X-GitHub-Delivery: <uuid>

# Vercel webhooks (connection-specific)
POST /api/v1/integrations/providers/vercel/INTEGRATION_CONNECTION_ID/webhook
Headers:
  x-vercel-signature: sha1=... or sha256=...
  x-vercel-event: deployment
  x-vercel-id: <event-id>

Incoming events are deduped and stored with signature verification and processing status for debugging.

The integrations dashboard includes copy-ready workflow node template presets (GitHub/Vercel) for inputTemplate and outputMappings.

Workflow context added for provider webhooks

Provider-triggered workflow runs include workflow.context.providerEvent (normalized fields) and workflow.context.providerPayload (raw parsed payload when JSON).

workflow.context.providerEvent.repositoryFullNameworkflow.context.providerEvent.workflowRunConclusionworkflow.context.providerEvent.projectNameworkflow.context.providerEvent.deploymentReadyState

Smoke Test the API

The repo includes a broad REST API smoke script for read-path validation and optional trigger-path checks.

A GitHub Actions workflow is included at .github/workflows/rest-api-smoke.yml for scheduled/manual smoke runs once repository secrets are configured.

export CRONAI_API_BASE_URL="https://YOUR-CONVEX-SITE/api/v1"
export CRONAI_API_KEY="crai_live_..."

# Optional for targeted read + trigger checks
export CRONAI_TEST_JOB_ID="..."
export CRONAI_TEST_WORKFLOW_DEFINITION_ID="..."

npm run smoke:rest
npm run smoke:rest -- --write --verbose