Create a schedule

Create a cron schedule for an agent.

POST/api/agents/{scope}/{name}/schedules

Authorization

better-auth.session_token<token>

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

In: cookie

Path Parameters

scope*string

Package scope (e.g. @myorg)

Match^@[a-z0-9][a-z0-9-]*$

name*string

Package name

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

Cron expression (e.g. '0 9 * * 1-5')

Length1 <= length

timezone?string

Default"UTC"

input?object

generation_config_override?

Temperature/reasoning overrides applied to every run fired by this schedule.

model_id_override?string

Override the persisted model on every run triggered by this schedule.

proxy_id_override?string

Override the persisted proxy on every run triggered by this schedule.

version_override?string

Which agent definition every run triggered by this schedule executes: draft, published, or a version spec (exact version, dist-tag, or semver range). Omitting it is identical to published (latest published version; the working copy is opt-in via draft only). draft requires WRITE authority on the agent at THIS write — 403 draft_not_writable otherwise — and is not re-checked at fire time, the way connection_overrides are frozen here too. The selected definition (manifest + prompt) is resolved at each fire — a schedule inheriting (published) on a never-published agent skips the fire and logs a warning until a version is published or draft is selected.

connection_overrides?

Per-integration connection sets frozen on the schedule row (the launch-override layer of every fire). Map of sets: { "@scope/integration": ["<connection_id>", ...] }, 1..20 per integration, always an ARRAY. Cascade, first layer with a set wins: admin pin → enforced org default → launch override (this run's picks, or the firing schedule's — a scheduled fire carries no run override) → member pin → soft org default → fallback (the schedule actor's single OWN connection — a connection shared by another member is never bound without an explicit pick). Under an admin pin or an enforced org default the set must name only connections of that governing set, which it then narrows (override_outranked otherwise, see 409). Stored on package_schedules.connection_overrides and replayed on every fire. Empty arrays and ids that are not uuids are refused here, and so is a key that names no integration the fired agent declares (400 invalid_request).

dependency_overrides?

Per-dependency version overrides frozen on the schedule row (#666/#686). Shape: { "@scope/dep": "draft" | "<semver|dist-tag>" }; keys may name a declared skill OR integration. Forwarded to each fired run so it resolves dependencies exactly as the schedule froze them. Each value must be draft or a resolvable version spec (semver range, exact version, or dist-tag); the protected tags latest and published are refused at this write rather than failing at every fire. A draft entry requires WRITE authority on THAT dependency, proved at THIS write (403 draft_not_writable naming it) and never re-checked at fire time — the authority belongs to the principal who wrote the schedule, frozen exactly as connection_overrides are. A key that names no declared skill or integration of the effective manifest is a 400 naming the key, and it is raised BEFORE the authority gate — a typo is a malformed request, not a missing grant.

actor?|

Execution identity for runs this schedule fires (#738). Provide exactly one of userId (an org member) or endUserId (an end-user of this space). Omit to default to the calling identity. The actor must be able to run agents in this space (the check every fire repeats) — else 400. Requires schedules:write; naming 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.

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

{
  "id": "sched_cm1abc456def789",
  "packageId": "@acme/email-sorter",
  "userId": "usr_r3t5w8y1z6",
  "endUserId": null,
  "orgId": "org_r3t5w8y1z6",
  "spaceId": "spc_9c1f4a2e-7b30-4d58-9a61-2e5c8f0b3d47",
  "name": "Weekday morning sort",
  "enabled": true,
  "disabled_reason": null,
  "cron_expression": "0 9 * * 1-5",
  "timezone": "Europe/Paris",
  "input": {
    "folder": "inbox",
    "maxEmails": 50
  },
  "generation_config_override": null,
  "model_id_override": null,
  "proxy_id_override": null,
  "version_override": null,
  "connection_overrides": null,
  "dependency_overrides": null,
  "last_run_at": null,
  "next_run_at": "2026-01-16T09:00:00Z",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z",
  "actor_name": "Pierre",
  "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"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/rate-limited",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. Please try again shortly.",
  "code": "rate_limited",
  "request_id": "req_abc123",
  "retry_after": 30
}