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 when 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; signature verification.

Parameters

Parameter	In	Type	Required	Description
`id`	path	string	yes	Server ID from the server list
`cronExpr`	body	string	yes	Five fields, 9–120 characters; default minimum interval 5 minutes
`timezone`	body	string	yes	Supported IANA zone, for example Africa/Abidjan
`path`	body	string	yes	Relative path with query, 1–512 characters; no URL, traversal, controls or raw #
`label`	body	string	no	Up to 80 characters, default empty string
`enabled`	body	boolean	no	Default true

Unknown fields are rejected; lead is unavailable here. ALWAYS is allowed; there is no always-on conflict. Galaxy hosts are unsupported; a galaxy app requires separate availability.

Examples

curl — personal key

Terminal

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

Terminal

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

HTTP 201. Illustrative response shape with synthetic IDs, not a live request result.

JSON

{
  "success": true,
  "data": {
    "id": "job_example",
    "serverId": "server_example",
    "label": "daily digest",
    "cronExpr": "0 9 * * *",
    "timezone": "Africa/Abidjan",
    "path": "/tasks/digest?mode=daily",
    "enabled": true,
    "nextScheduledFor": "2026-10-10T09:00:00.000Z",
    "scheduleRevision": 1,
    "availableSince": "2026-10-09T10:00:00.000Z",
    "createdAt": "2026-10-09T10:00:00.000Z",
    "updatedAt": "2026-10-09T10:00:00.000Z",
    "secret": "vjs_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
  }
}

Response fields

Field	Type	Description
`success`	boolean	Always `true` on success.
`data`	object	Created job and signing secret; the object fields are described below.

Fields of data:

Field	Type	Description
`id`	string	Job ID
`serverId`	string	Server ID
`label`	string	Job label
`cronExpr`	string	Five-field cron
`timezone`	string	Schedule time zone
`path`	string	Path and optional query string
`enabled`	boolean	Whether scheduled runs are enabled
`nextScheduledFor`	string	Next scheduled occurrence, UTC ISO-8601
`scheduleRevision`	integer	Schedule revision
`availableSince`	string	Start of the current schedule period, UTC ISO-8601
`createdAt`	string	Creation time, UTC ISO-8601
`updatedAt`	string	Last update time, UTC ISO-8601
`secret`	string	Signing secret; shown only now and cannot be read back

Errors

HTTP	Code	Reason
401	`MISSING_API_KEY`	Missing API key
403	`INFRA_FORBIDDEN_FOR_COWORK_KEY`	A Cowork key cannot write infrastructure; use a deployment key
403	`INFRA_SCOPE_REQUIRED`	Requires the `vibe:infra` scope
403	`WRITE_BLOCKED_READONLY_KEY`	A read-only key cannot write
403	`SERVER_ROLE_FORBIDDEN`	Development team role does not permit this action
404	`NOT_FOUND`	Server not found or inaccessible to the caller
404	`FEATURE_DISABLED`	Feature unavailable to this account
403	`WAKE_SCHEDULE_DISABLED`	Schedules unavailable to this account
400	`BLACKHOLE_ONLY`	Requires a Black Hole server
400	`GALAXY_NOT_SUPPORTED`	Galaxy host is unsupported
403	`WAKE_SCHEDULE_GALAXY_DISABLED`	Galaxy app schedules unavailable
400	`VALIDATION_ERROR`	Invalid request shape, path or time zone
400	`INVALID_CRON`	Cron cannot be parsed or its next occurrence cannot be computed
400	`CADENCE_TOO_LOW`	Schedule is more frequent than allowed
409	`SCHEDULED_JOB_LIMIT`	20-job limit reached
429	`RATE_LIMITED`	Too many requests; mutations are configured for 10 per minute, and shared limits also apply

Full list of shared error codes — Errors.