Para agentes de IA: markdown desta página — /docs-content-en/infra/jobs/update.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Replace job settings

PATCH /v1/infra/servers/:id/jobs/:jobId

Fully replaces the job settings; it does not merge individual fields. Omitted label and enabled take their defaults: an empty string and true. To disable a job, read the job list and send the previous values of every other field together with enabled: false. When the feature or entitlement is unavailable, only this kind of disabling, with no other changes, is allowed. The secret is unchanged.

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. Request verification in the handler: Verify signatures.

Parameters

Parameter In Type Required Description
Parameterid Inpath Typestring Requiredyes DescriptionServer ID from the server list
ParameterjobId Inpath Typestring Requiredyes DescriptionJob ID from the job list
ParametercronExpr Inbody Typestring Requiredyes DescriptionFive-field cron expression, 9–120 characters. The platform sets the minimum interval, 5 minutes by default
Parametertimezone Inbody Typestring Requiredyes DescriptionIANA time zone, for example Africa/Abidjan
Parameterpath Inbody Typestring Requiredyes DescriptionRelative handler path with an optional query string, 1–512 characters. An absolute URL, a leading //, .. traversal, control characters and an unencoded # are rejected
Parameterlabel Inbody Typestring Requiredno DescriptionJob label, up to 80 characters. Defaults to an empty string
Parameterenabled Inbody Typeboolean Requiredno DescriptionWhether 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 configured on a server in ALWAYS mode.

Examples

curl — personal key

Terminal 
curl --max-time 20 -X PATCH "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/jobs/JOB_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cronExpr": "30 9 * * 1-5",
  "timezone": "Africa/Abidjan",
  "path": "/tasks/digest?mode=weekday",
  "label": "weekday digest",
  "enabled": true
}'

curl — OAuth application

Terminal 
curl --max-time 20 -X PATCH "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/jobs/JOB_ID" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "cronExpr": "30 9 * * 1-5",
  "timezone": "Africa/Abidjan",
  "path": "/tasks/digest?mode=weekday",
  "label": "weekday digest",
  "enabled": true
}'

JavaScript — personal key

javascript 
const serverId = 'SERVER_ID';
const jobId = 'JOB_ID';
const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/${encodeURIComponent(serverId)}/jobs/${encodeURIComponent(jobId)}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cronExpr": "30 9 * * 1-5",
  "timezone": "Africa/Abidjan",
  "path": "/tasks/digest?mode=weekday",
  "label": "weekday digest",
  "enabled": true
}),
});
const result = await res.json();
if (!res.ok || !result.success) throw new Error(result.error?.code ?? `HTTP_${res.status}`);
console.log(result);

JavaScript — OAuth application

javascript 
const serverId = 'SERVER_ID';
const jobId = 'JOB_ID';
const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/${encodeURIComponent(serverId)}/jobs/${encodeURIComponent(jobId)}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cronExpr": "30 9 * * 1-5",
  "timezone": "Africa/Abidjan",
  "path": "/tasks/digest?mode=weekday",
  "label": "weekday digest",
  "enabled": true
}),
});
const result = await res.json();
if (!res.ok || !result.success) throw new Error(result.error?.code ?? `HTTP_${res.status}`);
console.log(result);

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionJob ID
Fielddata.serverId Typestring DescriptionServer ID
Fielddata.label Typestring DescriptionJob label
Fielddata.cronExpr Typestring DescriptionFive-field cron expression
Fielddata.timezone Typestring DescriptionSchedule time zone
Fielddata.path Typestring DescriptionHandler path and optional query string
Fielddata.enabled Typeboolean DescriptionWhether scheduled runs are enabled
Fielddata.nextScheduledFor Typestring DescriptionNext scheduled occurrence, UTC ISO-8601
Fielddata.scheduleRevision Typeinteger DescriptionSchedule revision
Fielddata.availableSince Typestring DescriptionStart of the current schedule period, UTC ISO-8601
Fielddata.createdAt Typestring DescriptionCreation time, UTC ISO-8601
Fielddata.updatedAt Typestring DescriptionLast update time, UTC ISO-8601

The signing secret is not returned.

Response example

200 OK response after a schedule change: scheduleRevision rose to 2, and nextScheduledFor was recomputed from the new cronExpr.

JSON 
{
  "success": true,
  "data": {
    "id": "cmvht3jly1xgh4bo25ge2t996",
    "serverId": "9547e3f2-1369-4ed4-b047-a589b0a303c4",
    "label": "weekday digest",
    "cronExpr": "30 9 * * 1-5",
    "timezone": "Africa/Abidjan",
    "path": "/tasks/digest?mode=weekday",
    "enabled": true,
    "nextScheduledFor": "2026-10-21T09:30:00.000Z",
    "scheduleRevision": 2,
    "availableSince": "2026-10-21T07:44:22.328Z",
    "createdAt": "2026-10-21T07:44:21.733Z",
    "updatedAt": "2026-10-21T07:44:22.339Z"
  }
}

Error response example

404 — the job is missing, deleted or belongs to another server:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "NOT_FOUND"
  }
}

Errors

HTTP Code Reason
HTTP400 CodeVALIDATION_ERROR ReasonThe body failed validation: an unknown field, a wrong type, an invalid path or an unknown time zone
HTTP400 CodeINVALID_CRON ReasonThe cron expression cannot be parsed or its next occurrence cannot be computed
HTTP400 CodeCADENCE_TOO_LOW ReasonThe interval between occurrences is below the minimum, 5 minutes by default
HTTP400 CodeBLACKHOLE_ONLY ReasonThe server is not in Black Hole mode
HTTP400 CodeGALAXY_NOT_SUPPORTED ReasonThe server is a galaxy host
HTTP403 CodeWAKE_SCHEDULE_DISABLED ReasonSchedules are unavailable to this portal
HTTP403 CodeWAKE_SCHEDULE_GALAXY_DISABLED ReasonSchedules for galaxy apps are not enabled
HTTP404 CodeNOT_FOUND ReasonServer not found or inaccessible to the caller; message is Server not found
HTTP404 CodeNOT_FOUND ReasonThe job is missing, deleted or belongs to another server; message is NOT_FOUND
HTTP404 CodeFEATURE_DISABLED ReasonThe feature is unavailable to this portal
HTTP401 CodeMISSING_API_KEY ReasonMissing API key
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY ReasonA Cowork key cannot write infrastructure. Use a deployment key
HTTP403 CodeINFRA_SCOPE_REQUIRED ReasonThe key lacks the vibe:infra scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY ReasonA read-only key cannot write
HTTP403 CodeSERVER_ROLE_FORBIDDEN ReasonDevelopment team role does not permit this action
HTTP429 CodeRATE_LIMITED ReasonThe 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

Full list of shared error codes — Errors.

See also