For AI agents: markdown of this page — /docs-content-en/infra/jobs/run.md documentation index — /llms.txt

Run manually

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

Accepts one manual run and immediately returns runId. Allowed with enabled=false, but requires feature and schedule availability. HTTP 202 does not mean delivery or work completion. Each repeat of this POST creates a new runId: do not blindly retry after losing a response. Observe history.

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
jobId path string yes Job ID from the list

No request body or query parameters are needed. For a POST without a body, omit Content-Type: application/json; an empty JSON body is rejected before the handler.

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

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

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

Response fields

Field Type Description
success boolean Always true on success.
data object Object containing the new run ID in runId.

The signing secret is not returned.

Fields of data:

Field Type Description
runId string New run ID for history

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 NOT_FOUND Job is missing, deleted or belongs to another server
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
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.

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

See also