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

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

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

Parameters

Parameter In Type Required Description
Parameterid Inpath Typestring Requiredyes DescriptionServer ID from the server 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 created on a server in ALWAYS mode.

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 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
Fielddata.secret Typestring DescriptionSigning 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
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 CodeFEATURE_DISABLED ReasonThe feature is unavailable to this portal
HTTP404 CodeNOT_FOUND ReasonServer not found or inaccessible to the caller
HTTP409 CodeSCHEDULED_JOB_LIMIT ReasonThe server already has 20 non-deleted jobs
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 ReasonThe development team member's 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