Update a schedule

Update a cron schedule (expression, timezone, enabled state, or input). Merge semantics (RFC 7396): an absent field is left unchanged, null clears a nullable one. A schedule whose actor is ANOTHER platform member than the caller lends that member's connections to every run, so any patch of it — whatever the fields, enabling and disabling included — requires the org role owner or admin on the user's own credential, never an API key or a third-party OAuth client (else 403 forbidden); schedules running as the caller or as an end user need schedules:write only.

PATCH/api/schedules/{id}

Authorization

better-auth.session_token<token>

Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.

In: cookie

Path Parameters

id*string

Header Parameters

X-Org-Id?string

Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).

Formatuuid

X-Space-Id?string

Space ID. Required for space-scoped routes (agents, runs, schedules, and space-scoped module routes). Not needed for API key auth (space resolved from key).

Request Body

application/json

name?string

cron_expression?string

timezone?string

enabled?boolean

input?object

generation_config_override?|

Temperature/reasoning overrides for scheduled runs. Pass null to clear.

model_id_override?string|null

proxy_id_override?string|null

version_override?|

Version selector (draft | published | version spec). Pass null to clear (back to the latest published version; the working copy is opt-in via draft only). draft requires WRITE authority on the agent, but only when this patch MOVES the selector: re-sending the value the row already holds decides nothing and is never refused, so a member editing the cron of someone else's draft schedule is not asked for an authority the request does not exercise.

connection_overrides?|

Per-integration connection sets frozen on the schedule, one array of 1..20 connection ids per integration. Pass null to clear. Same array shape, same bounds and same cascade layer as on create. Its keys are judged against the definition the row fires after the patch, whenever the map or version_override moves: a key it does not declare is a 400 invalid_request.

dependency_overrides?|

Per-dependency version overrides frozen on the schedule (#666/#686). Shape: { "@scope/dep": "draft" | "<semver|dist-tag>" }; skill or integration ids. Pass null to clear. Each value must be draft or a resolvable version spec — same rule as on create. WRITE authority is proved per KEY and only for the keys this patch MOVES: a draft entry whose value the row already holds was proved at the write that introduced it, and re-sending it decides nothing.

actor?|

Re-point the schedule's execution identity (#738). Provide exactly one of userId (an org member) or endUserId (an end-user of this space). Omit to leave the actor unchanged — it cannot be cleared. Changing the actor resets frozen connection_overrides unless this patch also supplies them. Requires schedules:write; changing it to ANOTHER member (userId other than the caller's) also requires the org role owner or admin on the user's own credential (an API key or a third-party OAuth client is refused) — else 403 forbidden with param: actor. A schedule already running as another member takes the same for any patch, this field included.

curl -X PATCH "https://your-instance/api/schedules/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "string",
  "packageId": "string",
  "userId": "string",
  "endUserId": "string",
  "orgId": "string",
  "spaceId": "string",
  "name": "string",
  "enabled": true,
  "disabled_reason": "actor_invalid",
  "cron_expression": "string",
  "timezone": "string",
  "input": {},
  "generation_config_override": {
    "temperature": 0,
    "reasoning_level": "off"
  },
  "model_id_override": "string",
  "proxy_id_override": "string",
  "version_override": "string",
  "connection_overrides": {
    "property1": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "property2": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  },
  "dependency_overrides": {
    "property1": "string",
    "property2": "string"
  },
  "last_run_at": "2019-08-24T14:15:22Z",
  "next_run_at": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "actor_name": "string",
  "actor_type": "user",
  "running_runs": 0,
  "unread_count": 0,
  "last_run_number": 0
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing session",
  "code": "unauthorized",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "code": "forbidden",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Agent '@acme/reporter' has no published version",
  "code": "no_published_version",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}