Scheduled HTTP calls

A job calls your HTTP handler on a Black Hole server at scheduled times. If the feature is unavailable to your Bitrix24 account, you cannot create, enable or run a job. Jobs are configured through the API and MCP. This is separate from wake windows.

Capabilities via Vibecode API

A key with vibe:infra can read jobs and history. Changes require the existing server management permissions: its managing key or a permitted development team role. The job belongs to the server, not the key that created it. Rebinding the server's managing key transfers job control without recreating jobs. The MCP tool manage_server_jobs takes serverId, jobId for actions on a single job, body for create and update, and cursor and limit for run history. It makes the same API calls with the same refusals. Some of the tool's actions modify data, call the handler or rotate the secret.

Schedule and limits

At most 20 non-deleted jobs per server. Disabled jobs count too. The cronExpr expression has five fields; timezone is a supported IANA time zone. The minimum interval is set by the platform, 5 minutes by default. path is a relative path with an optional query string, up to 512 characters: /tasks/digest?mode=daily. Absolute URLs, paths starting with //, traversal .., control characters and an unencoded # are forbidden. Only the path of the handler that receives the POST request is configurable: the host, HTTP method, headers and request body cannot be set.

Creation, a change to cronExpr or timezone, and re-enabling start the schedule strictly in the future. Changing only label or path does not shift the next occurrence. A run snapshots its path and account, so a later PATCH does not redirect it. After downtime, at most one latest occurrence is recovered, rather than the entire missed backlog. If the feature or schedule entitlement was temporarily unavailable, recovery may also produce one latest run, including one from that period.

Wake and delivery

Jobs are also allowed on a server in effective ALWAYS mode: it needs no additional wake window. In IDLE and SCHEDULE modes the platform prepares the server in time for the call. A galaxy host is unsupported; a galaxy app requires separate entitlement. Current account access, payment, server binding, wake restrictions and schedule availability are checked before waking and sending. A job does not bypass restrictions and does not require an external application API key.

Each run, including a manual run on a disabled job, waits for readiness for at most 30 minutes from creation. Waiting does not consume attempts. One run per job is active at a time. An already sent run in RUNNING status finishes its attempt even after the job is disabled or deleted. A newer scheduled occurrence supersedes only an older SCHEDULE run in PENDING status that has had no attempts yet. MANUAL runs and already started runs are not superseded.

Up to four delivery attempts share one runId. The app must verify signatures and durable deduplication. An HTTP 2xx response means acceptance, not completion of background work. A run in PENDING status lives for at most 96 hours. Background work in the app is protected only by the server's ordinary idle timer, not until it completes. Do not rely on exactly-once execution of a business operation.

Observe and stop

History retains completed runs according to the platform setting: 90 days by default, at least 7 days. Runs in PENDING and RUNNING status are not removed by age. The secret is shown only on creation and rotation: store it on the receiving handler side. List and history do not return it.

When the feature or entitlement is unavailable, an authorized owner can read jobs and history, delete a job, or replace its settings as a whole if the replacement only disables the job and changes nothing else. A regular PATCH with other changes requires entitlement. There are no separate notifications for runs in FAILED status; access or payment refusals use the existing daily notification. After deletion, the job disappears from the list and its history at the job's address returns 404. Save records you need beforehand.

List jobs

GET /v1/infra/servers/:id/jobs

Returns all non-deleted server jobs, including disabled ones, with up to five latest runs per job. Works when the feature is unavailable. The response contains no secret.

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

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

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

curl — OAuth application

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

JavaScript — personal key

const serverId = 'SERVER_ID';
const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/${encodeURIComponent(serverId)}/jobs`, {
  method: 'GET',
  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

const serverId = 'SERVER_ID';
const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/${encodeURIComponent(serverId)}/jobs`, {
  method: 'GET',
  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 200. Illustrative response shape with synthetic IDs, not a live request result.

{
  "success": true,
  "data": {
    "items": [
      {
        "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-11T09: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",
        "latestRuns": [
          {
            "id": "run_example",
            "jobId": "job_example",
            "serverId": "server_example",
            "portalId": "account_example",
            "path": "/tasks/digest?mode=daily",
            "scheduleRevision": 1,
            "trigger": "SCHEDULE",
            "scheduledFor": "2026-10-10T09:00:00.000Z",
            "status": "SUCCEEDED",
            "attempts": 1,
            "nextAttemptAt": null,
            "readyDeadlineAt": "2026-10-10T09:30:00.000Z",
            "deliveryDeadlineAt": "2026-10-14T09:00:00.000Z",
            "waitingForServer": false,
            "startedAt": "2026-10-10T09:00:02.000Z",
            "lastAttemptStartedAt": "2026-10-10T09:00:02.000Z",
            "late": false,
            "finishedAt": "2026-10-10T09:00:02.150Z",
            "durationMs": 150,
            "responseSource": "app",
            "httpStatus": 202,
            "errorCode": null,
            "lastAttemptErrorCode": null,
            "requestId": "request_example",
            "responseSnippet": "{\"accepted\":true}",
            "createdAt": "2026-10-10T09:00:00.000Z",
            "updatedAt": "2026-10-10T09:00:02.150Z"
          }
        ]
      }
    ]
  }
}

Response fields

The signing secret is not returned.

Fields of data:

Fields of each job in data.items:

Errors

Full list of shared error codes — Errors.

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

See also

• Create a job
• Replace job settings
• Run history