## Replace job settings

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

PATCH fully replaces user settings; it does not merge individual fields. Cron, timezone and path are required; omitted label/enabled become an empty string/true. Before disabling, read the list and send the previous values of every other field. Only this disabling without other changes is allowed when the feature or entitlement is unavailable. 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](../jobs.md); [signature verification](./signature.md).

## Parameters

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Server ID from the [server list](../servers.md) |
| `jobId` | path | string | yes | Job ID from the [list](./list.md) |
| `cronExpr` | body | string | yes | Five fields, 9–120 characters; default minimum interval 5 minutes |
| `timezone` | body | string | yes | Supported IANA zone, for example Africa/Abidjan |
| `path` | body | string | yes | Relative path with query, 1–512 characters; no URL, traversal, controls or raw # |
| `label` | body | string | no | Up to 80 characters, default empty string |
| `enabled` | body | boolean | no | Default true |

Unknown fields are rejected; lead is unavailable here. ALWAYS is allowed; there is no always-on conflict. Galaxy hosts are unsupported; a galaxy app requires separate availability.

## Examples

### curl — personal key

```bash
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": "0 9 * * *",
  "timezone": "Africa/Abidjan",
  "path": "/tasks/digest?mode=daily",
  "label": "daily digest",
  "enabled": true
}'
```

### curl — OAuth application

```bash
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": "0 9 * * *",
  "timezone": "Africa/Abidjan",
  "path": "/tasks/digest?mode=daily",
  "label": "daily 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": "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}`);
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": "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}`);
console.log(result);
```

## Response

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

```json
{
  "success": true,
  "data": {
    "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-10T09: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"
  }
}
```

## Response fields

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Always `true` on success. |
| `data` | object | Updated job; the object fields are described below. |

The signing secret is not returned.

Fields of `data`:

| Field | Type | Description |
|---|---|---|
| `id` | string | Job ID |
| `serverId` | string | Server ID |
| `label` | string | Job label |
| `cronExpr` | string | Five-field cron |
| `timezone` | string | Schedule time zone |
| `path` | string | Path and optional query string |
| `enabled` | boolean | Whether scheduled runs are enabled |
| `nextScheduledFor` | string | Next scheduled occurrence, UTC ISO-8601 |
| `scheduleRevision` | integer | Schedule revision |
| `availableSince` | string | Start of the current schedule period, UTC ISO-8601 |
| `createdAt` | string | Creation time, UTC ISO-8601 |
| `updatedAt` | string | Last update time, UTC ISO-8601 |

## 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](../../cowork/deploy-key.md) |
| 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 |
| 400 | `VALIDATION_ERROR` | Invalid request shape, path or time zone |
| 400 | `INVALID_CRON` | Cron cannot be parsed or its next occurrence cannot be computed |
| 400 | `CADENCE_TOO_LOW` | Schedule is more frequent than allowed |
| 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](/docs/errors).

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

## See also

- [List jobs](./list.md)
- [Run manually](./run.md)
- [Delete a job](./delete.md)