# Cronbolt agent guide

Cronbolt schedules HTTP requests. A project API key can manage jobs and runs for one project. It cannot access another project, account details, or billing.

## Preferred connection: MCP

Connect a Streamable HTTP MCP client to `https://api.cronbolt.com/mcp`. Send the project key as the
`Authorization: Bearer $CRONBOLT_API_KEY` header. Never pass the key as a tool
argument or include it in model context.

The server supports stateless MCP `2026-07-28` requests and older MCP clients.
Call `get_project_context` first, inspect existing jobs before creating one, use
a unique idempotency key for every new mutation, and ask before calling
`delete_job`.

## Direct HTTP setup

Read the API key from the agent process environment using the exact variable name `CRONBOLT_API_KEY`. Do not use a key from chat history, source files, logs, or a similarly named environment variable. Never print its value.

Before any API call, confirm the variable is present without echoing it:

```sh
test -n "${CRONBOLT_API_KEY:-}" || {
  echo "CRONBOLT_API_KEY is not set" >&2
  exit 1
}
```

If it is missing or empty, stop and ask the developer to create a project API key in Cronbolt Settings and add it to the agent's secret environment. Do not ask them to paste the key into the conversation.

The API base URL is `https://api.cronbolt.com/api/v1`. It is already included in every example below. Send `X-API-Key: $CRONBOLT_API_KEY` on every request. Never print, log, or commit the key.

Check the connection before making changes:

```sh
curl --fail-with-body -sS "https://api.cronbolt.com/api/v1/context" \
  -H "X-API-Key: $CRONBOLT_API_KEY"
```

This returns the project, plan limits, docs URL, and OpenAPI URL. Treat the returned project as the authoritative scope for the environment key. If it is not the intended project, stop and ask the developer to update `CRONBOLT_API_KEY` in the agent environment. The key already selects the project, so do not ask for a project ID.

## Create a recurring job

Set `schedule_type` to `recurring`, then provide `url` and `cron_expression`. Cronbolt defaults to GET, UTC, active, a 30 second timeout, two retries, and a 30 second initial backoff. It derives the name from the URL.

```sh
curl --fail-with-body -sS -X POST "https://api.cronbolt.com/api/v1/jobs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CRONBOLT_API_KEY" \
  -H "Idempotency-Key: setup-heartbeat-v1" \
  -d '{"url":"https://example.com/webhooks/heartbeat","schedule_type":"recurring","cron_expression":"*/15 * * * *"}'
```

Use one stable, unique idempotency key for each intended create. Repeating the same request with the same key returns the original job. Reusing it with different input returns a conflict.

## Create a one-time request

One-time requests require Bolt or Surge. Set `schedule_type` to `one_time`, supply a future `run_at`, and set its IANA `timezone`. They create one run with the same automatic retry defaults, then expire. Check the project context for the account's current pending limit.

```sh
curl --fail-with-body -sS -X POST "https://api.cronbolt.com/api/v1/jobs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CRONBOLT_API_KEY" \
  -H "Idempotency-Key: launch-callback-v1" \
  -d '{"url":"https://example.com/webhooks/launch","schedule_type":"one_time","run_at":"2035-01-01T09:00:00","timezone":"Asia/Kolkata"}'
```

## Common operations

Cronbolt prevents overlapping deliveries for each job. HTTP 200 through 299 means success by default. Use `expected_status_min`, `expected_status_max`, and optional `response_contains` for application-level checks. Use `alert_webhook_url` for secret-free failure and recovery events. Response bodies are never stored.

- `GET /jobs`: list this project's jobs.
- `GET /jobs/{job_id}`: inspect one job.
- `PATCH /jobs/{job_id}`: change supplied fields only.
- `POST /jobs/{job_id}/pause`: pause a recurring job.
- `POST /jobs/{job_id}/resume`: resume a recurring job.
- `POST /jobs/{job_id}/run-now`: queue a manual run. Send an Idempotency-Key.
- `GET /jobs/{job_id}/runs`: list runs.
- `GET /jobs/{job_id}/runs/{run_id}`: inspect run attempts.
- `POST /jobs/{job_id}/runs/{run_id}/retry`: retry an eligible recurring run. Send an Idempotency-Key.
- `DELETE /jobs/{job_id}`: permanently delete a job. Ask the developer for confirmation first.

For a manual run or retry, follow the response `Location` header and wait for the `Retry-After` seconds before polling.

## Errors

Errors include `code`, `message`, and `request_id`. Validation errors also include `errors`. If `action_url` is present, give it to the developer. Respect HTTP 429 and `Retry-After`.

OpenAPI: https://api.cronbolt.com/api/v1/openapi.json
MCP: https://api.cronbolt.com/mcp
Human docs: https://cronbolt.com/docs