Create cron job
POSThttps://api.instacloud.com/projects/{projectId}/cron-jobs
Token scope: account · org · project — read-only tokens refused (not a GET).
Create a cron job on a branch. Gated — cron.write. 403 also when the org is billing-suspended, its schedule quota is full, or the target service belongs to another organization.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | unique per branch |
expression | string | yes | 5-field cron expression, always evaluated in UTC |
branch | string | no | target branch (default: the project’s default branch) |
target | object | yes | Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host. |
request | object | no | Stored encrypted; its VALUES are never returned. Send the whole object to replace it — reads answer with `request` (method and header names only). |
request.method | "GET" | "POST" | no | default GET |
request.headers | object | no | literal headers; put credentials in secretRefs instead |
request.body | string | no | request body (POST only) |
request.secretRefs | object | no | header name → project secret NAME. Resolved per attempt from whatever is current, so rotating a secret takes effect on the next attempt with no edit to the job. Looked up in the JOB’S own branch, then its project — not the target’s — so a service in another project or branch of this org sees a different scope than its own env; for a service target IN THE SAME project and branch, secrets bound to that service also count (the same value the service reads from its env there). Only user-defined secrets resolve — platform-managed credentials such as DATABASE_URL never do. A header may not be in both `headers` and `secretRefs`. |
requestTimeoutMs | integer | no | excludes cold start: the wake is timed separately |
retry | object | no | |
retry.platformMaxRetries | integer | no | retries for failures where nothing was sent (wake/transport). Default 2. |
retry.applicationMaxRetries | integer | no | retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered. |
retry.retryableStatuses | integer[] | no | e.g. [429, 503]; empty means none |
retry.maxRunAgeMs | integer | no | give up on the run once it is this old, whatever the retry budget says |
Responses
201
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
job | object | yes | A cron schedule. Header values are write-only; `request` describes the stored request without them. |
job.id | string | yes | |
job.project_id | string | yes | |
job.branch_id | string | yes | |
job.branch | string | yes | branch name, joined for readability — the id is the identity |
job.name | string | yes | |
job.expression | string | yes | |
job.timezone | string | yes | UTC in v1, so preview and the materializer can never disagree |
job.enabled | boolean | yes | |
job.revision | integer | yes | the If-Match guard for PATCH |
job.next_run_at | string | null | yes | |
job.target | object | yes | Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host. |
job.request | object | yes | The non-secret description of the job’s request. |
job.request.method | "GET" | "POST" | yes | |
job.request.headerNames | string[] | yes | names only, literal and secret-backed alike — never values |
job.request.secretRefs | object | yes | header name → secret NAME for the secret-backed headers. Names are not credentials, so they are returned: an edit can re-send these as they are, where a literal header’s value must be supplied again. |
job.request_timeout_ms | integer | yes | |
job.retry_policy | object | yes | |
job.retry_policy.platformMaxRetries | integer | no | retries for failures where nothing was sent (wake/transport). Default 2. |
job.retry_policy.applicationMaxRetries | integer | no | retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered. |
job.retry_policy.retryableStatuses | integer[] | no | e.g. [429, 503]; empty means none |
job.retry_policy.maxRunAgeMs | integer | no | give up on the run once it is this old, whatever the retry budget says |
job.created_at | string | yes | |
job.updated_at | string | yes |
202
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
status | "approval_required" | no | |
approvalId | string | no | |
action | string | no | the gated action, or a comma-joined compound set — prefer `actions` |
actions | string[] | no | every capability this approval covers |
message | string | no | |
url | string | no | the console page where a project admin reviews this request |
nextActions | object[] | no | |
nextActions.op | string | yes | Neutral logical action id, e.g. "service.add" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface. |
nextActions.reason | string | yes | Natural-language, human/LLM-facing "why do this now". |
nextActions.args | object | no | Suggested, flat named arguments; "<placeholder>"s where a value is unknown. |
nextActions.gated | boolean | no | True if the action passes a governance gate. |
400
invalid expression, target or name
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
403
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
404
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
409
a job of this name already exists on the branch; or code service_public_access_closed: the target compute service has public access closed, so the job could not reach it
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | |
code | string | no | stable machine-readable reason, e.g. private_lane_disabled, private_lane_unavailable_in_region, public_access_closed, credential_change_in_progress |