## Create a job `POST /v1/infra/servers/:id/jobs` Creates a job and returns its signing secret once. Store it in the receiving handler's protected configuration. The first scheduled time is strictly after creation, even with `enabled: false`. Requires a key with `vibe:infra` and existing server permissions. Writes need the managing key or a team role permitted to manage the lifecycle. General rules: [Scheduled HTTP calls](../jobs.md). Request verification in the handler: [Verify signatures](./signature.md). ## Parameters | Parameter | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | yes | Server ID from the [server list](../servers/list.md) | | `cronExpr` | body | string | yes | Five-field cron expression, 9–120 characters. The platform sets the minimum interval, 5 minutes by default | | `timezone` | body | string | yes | IANA time zone, for example `Africa/Abidjan` | | `path` | body | string | yes | Relative handler path with an optional query string, 1–512 characters. An absolute URL, a leading `//`, `..` traversal, control characters and an unencoded `#` are rejected | | `label` | body | string | no | Job label, up to 80 characters. Defaults to an empty string | | `enabled` | body | boolean | no | Whether scheduled runs are enabled. Defaults to `true` | Unknown fields, including `lead` from wake windows, are rejected with `400 VALIDATION_ERROR`. A job can also be created on a server in `ALWAYS` mode. ## Examples ### curl — personal key ```bash curl --max-time 20 -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/jobs" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cronExpr": "0 9 * * *", "timezone": "Africa/Abidjan", "path": "/tasks/digest?mode=daily", "label": "daily digest", "enabled": true }' ``` ### curl — OAuth application ```bash curl --max-time 20 -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/jobs" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "cronExpr": "0 9 * * *", "timezone": "Africa/Abidjan", "path": "/tasks/digest?mode=daily", "label": "daily digest", "enabled": true }' ``` ### JavaScript — personal key ```javascript const serverId = 'SERVER_ID'; const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/${encodeURIComponent(serverId)}/jobs`, { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ "cronExpr": "0 9 * * *", "timezone": "Africa/Abidjan", "path": "/tasks/digest?mode=daily", "label": "daily digest", "enabled": true }), }); const result = await res.json(); if (!res.ok || !result.success) throw new Error(result.error?.code ?? `HTTP_${res.status}`); // Store result.data.secret in protected server-side configuration; never log it. ``` ### JavaScript — OAuth application ```javascript const serverId = 'SERVER_ID'; const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/${encodeURIComponent(serverId)}/jobs`, { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ "cronExpr": "0 9 * * *", "timezone": "Africa/Abidjan", "path": "/tasks/digest?mode=daily", "label": "daily digest", "enabled": true }), }); const result = await res.json(); if (!res.ok || !result.success) throw new Error(result.error?.code ?? `HTTP_${res.status}`); // Store result.data.secret in protected server-side configuration; never log it. ``` ## Response fields | Field | Type | Description | |---|---|---| | `success` | boolean | Always `true` on success | | `data.id` | string | Job ID | | `data.serverId` | string | Server ID | | `data.label` | string | Job label | | `data.cronExpr` | string | Five-field cron expression | | `data.timezone` | string | Schedule time zone | | `data.path` | string | Handler path and optional query string | | `data.enabled` | boolean | Whether scheduled runs are enabled | | `data.nextScheduledFor` | string | Next scheduled occurrence, UTC ISO-8601 | | `data.scheduleRevision` | integer | Schedule revision | | `data.availableSince` | string | Start of the current schedule period, UTC ISO-8601 | | `data.createdAt` | string | Creation time, UTC ISO-8601 | | `data.updatedAt` | string | Last update time, UTC ISO-8601 | | `data.secret` | string | Signing secret. Shown only in this response and cannot be read back | ## Response example `201 Created` response: ```json { "success": true, "data": { "id": "cmvht3jly1xgh4bo25ge2t996", "serverId": "9547e3f2-1369-4ed4-b047-a589b0a303c4", "label": "daily digest", "cronExpr": "0 9 * * *", "timezone": "Africa/Abidjan", "path": "/tasks/digest?mode=daily", "enabled": true, "nextScheduledFor": "2026-10-21T09:00:00.000Z", "scheduleRevision": 1, "availableSince": "2026-10-21T07:44:21.733Z", "createdAt": "2026-10-21T07:44:21.733Z", "updatedAt": "2026-10-21T07:44:21.733Z", "secret": "vjs_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8" } } ``` ## Error response example 404 — the server is not found or is inaccessible to the caller: ```json { "success": false, "error": { "code": "NOT_FOUND", "message": "Server not found" } } ``` ## Errors | HTTP | Code | Reason | |---|---|---| | 400 | `VALIDATION_ERROR` | The body failed validation: an unknown field, a wrong type, an invalid `path` or an unknown time zone | | 400 | `INVALID_CRON` | The cron expression cannot be parsed or its next occurrence cannot be computed | | 400 | `CADENCE_TOO_LOW` | The interval between occurrences is below the minimum, 5 minutes by default | | 400 | `BLACKHOLE_ONLY` | The server is not in Black Hole mode | | 400 | `GALAXY_NOT_SUPPORTED` | The server is a galaxy host | | 403 | `WAKE_SCHEDULE_DISABLED` | Schedules are unavailable to this portal | | 403 | `WAKE_SCHEDULE_GALAXY_DISABLED` | Schedules for galaxy apps are not enabled | | 404 | `FEATURE_DISABLED` | The feature is unavailable to this portal | | 404 | `NOT_FOUND` | Server not found or inaccessible to the caller | | 409 | `SCHEDULED_JOB_LIMIT` | The server already has 20 non-deleted jobs | | 401 | `MISSING_API_KEY` | Missing API key | | 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | A Cowork key cannot write infrastructure. Use a [deployment key](../../cowork/deploy-key.md) | | 403 | `INFRA_SCOPE_REQUIRED` | The key lacks the `vibe:infra` scope | | 403 | `WRITE_BLOCKED_READONLY_KEY` | A read-only key cannot write | | 403 | `SERVER_ROLE_FORBIDDEN` | The development team member's role does not permit this action | | 429 | `RATE_LIMITED` | The job mutation limit is exceeded: 10 per minute platform-wide. The effective value for the key is in the `x-ratelimit-limit` header, as the cap is divided across replicas. Shared API limits also apply | | 429 | `CALLER_RATE_LIMITED` | The overall per-minute request limit of the API key or its owner was exhausted before this route's limit. `Retry-After` gives the delay before retrying and `X-RateLimit-Scope` names the refusing layer. This refusal does not promise an `x-ratelimit-limit` header | Full list of shared error codes — [Errors](/docs/errors). ## See also - [List jobs](./list.md) - [Replace job settings](./update.md) - [Rotate the secret](./rotate-secret.md)