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

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

Run manually

POST /v1/infra/servers/:id/jobs/:jobId/run

Accepts one manual run and immediately returns runId. Allowed even with enabled: false, but requires the feature and schedules to be available. HTTP 202 does not mean the call was delivered or the work completed. Each repeat of this POST creates a new runId, so do not blindly retry after losing a response; check the run history instead.

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

No request body or query parameters are needed.

Examples

curl — personal key

Terminal 
curl --max-time 20 -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/jobs/JOB_ID/run" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl --max-time 20 -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/jobs/JOB_ID/run" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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)}/run`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
});
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)}/run`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
});
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.runId Typestring DescriptionID of the new run. Use it to find the run in run history

The signing secret is not returned.

Response example

202 Accepted response:

JSON 
{
  "success": true,
  "data": {
    "runId": "cmvht3kfl1vpa4bpf4406sbpt"
  }
}

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 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