Introduction

Scheduler0 is a distributed cron-job scheduler. You define jobs (a cron spec or a one-time start date plus a JSON payload), group them into projects, and point each job at an executor that decides how it runs: an HTTP webhook, a cloud function, or a shell command on a machine you control. Every run is recorded as an execution you can query. The engine is written in Go and uses SQLite with Raft consensus, so it can run as a hosted service or on your own infrastructure.

Everything in these docs is exposed through one HTTP API. The dashboard, the CLI, the client libraries, and the MCP server all use it.

Base URL

Deployment	Base URL
Hosted service	https://api.scheduler0.com/api/v1
Self-hosted	https://<your-host>/api/v1

All requests and responses are JSON (Content-Type: application/json).

Authentication

Every request except GET /healthcheck must carry all three headers:

Header	Value
X-API-Key	The credential's apiKey
X-Secret-Key	The credential's plaintextSecret (shown once, when the credential is created)
X-Account-ID	The numeric ID of the account the credential belongs to

A missing or mismatched account ID is treated as an invalid credential and returns 401.

curl "https://api.scheduler0.com/api/v1/projects" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID"

Self-hosted operators also have Basic Authentication (the AuthUsername/AuthPassword from the server configuration) together with an X-Peer: cmd header. This is the bootstrap path for operator work such as creating the first account; it is not available on the hosted service. See Credentials for how credentials, scopes and expiry work.

Response envelope

Every JSON response has the same shape:

{ "success": true, "data": { ... } }

On error success is false and data is a string message (a few AI endpoints return an object with code/message). 204 No Content responses have no body.

Common status codes:

Status	Meaning
400	Validation failed; data explains which field
401	Missing/invalid API key, secret or account ID, or the credential has expired
403	The credential lacks the required scope (credential missing required scope: <scope>) or the resource belongs to another account
404	Resource not found in this account
422	Body is not valid JSON, or (AI endpoints) the prompt was rejected by the intent guardrail
429	List limit above 100, or a monthly AI quota is exhausted

Scopes

A credential carries one or more scopes that gate which routes it may call:

Scope	Grants
read	All GET routes: jobs, projects, credentials, executors, executions, async-tasks/{id}, features, AI settings/models/prompt-request log, and local-executors/{id}/jobs
write	POST/PUT/DELETE on jobs, projects, credentials, executors and AI settings; POST /local-executors
execute	The AI endpoints (ai/prompt, ai/prompt/classify, ai/schedule, ai/suggestions/*), executors/{id}/test-invoke, executions/cleanup-old-logs, and local-executors/{id}/executions
admin	/accounts/*, /cluster/* and POST /account/rotate-secret. Satisfies every other scope check too. Only an operator or an existing admin credential can grant it.

Pagination

List endpoints for jobs, projects, credentials and executors accept limit (default 10, maximum 100 — anything larger returns 429), offset (default 0), orderBy and orderByDirection (asc/desc, default desc). They return { total, offset, limit, <resource>: [...] }. GET /executions uses different parameter names and has no maximum; see Executions.

Hosted service vs self-hosting

The resource endpoints (credentials, projects, executors, jobs, executions, AI) behave the same in both deployments. The pages under Self-Hosting & Operations — Account Management, Cluster Management and Backup and Restore — cover routes that require the admin scope or Basic Authentication and are meant for operators running their own cluster.

Clients

Client	Install	Source
Go	go get github.com/scheduler0/scheduler0-go-client/v2	scheduler0-go-client
Node.js / TypeScript	npm install @scheduler0/scheduler0-node-client	scheduler0-node-client
Python	pip install scheduler0	scheduler0-python-client
CLI	see CLI	scheduler0-cli

Each client README documents its own API; the examples in these docs use curl so they map directly onto the HTTP API. The full OpenAPI specification is at api-reference.scheduler0.com.

Where to start

1. Create a credential in the dashboard (or with POST /credentials) and save the plaintextSecret — Credentials.
2. Create a project and an executor.
3. Create a job and watch it run in Executions.