Deployments

A deployment runs an agent automatically on a cron schedule. Each fire creates a new session from a fixed first input (input_template), subject to its own budget. Use deployments for recurring, unattended work.

The deployment object

string

Unique id (e.g. dep_01H...).

string

The agent to run.

integer | null

Pinned agent version each run uses. null means every fire tracks the agent’s current_version.

string

Cron expression defining the schedule, read in timezone.

string

IANA zone the cron is read in (default "UTC"), so 0 9 * * 1 stays 09:00 local across a daylight-saving shift.

string

Text used as the session’s first input on each run.

integer

Per-run session budget, in micro-USD. Always set — it is required at create.

string

Completion window for scheduled runs.

string | null

URL POSTed with the session.idle envelope when a fire goes idle. A non-null value has a webhook endpoint behind it, listed by GET /v1/webhooks with events: ["deployment.on_idle"]; POST /v1/webhooks/{id}/rotate returns the secret these deliveries are signed with, and GET /v1/webhooks/{id}/deliveries is their log. This field is the authority: if the endpoint behind it is re-pointed elsewhere, the push is refused rather than sent to the other URL.

string | null

The persona every fire speaks as, as an idn_ id. null runs each fire as no persona.

boolean

Whether the schedule is active — what you asked for.

string

Whether anything will act on it — what you get. scheduled (a clock is watching it), paused (enabled: false), or unscheduled (enabled, but no clock runs schedules on this installation, so it will never fire on its own).

string | null

Next fire time, and null unless schedule_status is scheduled — a date nothing will honour is worse than none. An unscheduled deployment still fires on demand with POST /v1/deployments/{id}/run.

string

Creation timestamp.

Create a deployment

POST /v1/deployments → 201 Created.

string

required

The agent to run on schedule.

integer

Pin runs to a specific agent version for staged rollout or rollback. Omit to always track the agent’s current_version.

string

required

Cron expression (e.g. 0 9 * * 1 = Mondays at 09:00), read in timezone.

string

IANA zone the cron is read in. Defaults to UTC.

string

required

The input each run sends to its session.

integer

required

Per-run budget in micro-USD. There is no default: an unbudgeted schedule could spend without a ceiling, so it must be stated.

string

Completion window (immediate | priority | loose). Defaults to the agent’s window.

string

URL POSTed with the session.idle envelope each time a fire goes idle. Defaults to null, which pushes nothing. Setting it provisions the webhook endpoint the pushes are delivered through, so they inherit the signature, the retry schedule, the auto-disable and the delivery log.

string

The persona every fire speaks as — an idn_ id or the persona’s name, exactly as when creating a session. The agent must already hold a grant to it. It is resolved at create and stored as the id, so the response echoes idn_… even when you sent a name, and renaming the persona later cannot re-point the schedule. Defaults to null: the fire runs as no persona.

boolean

Start active. Defaults to true.

curl -fsSL https://api.vetta.sh/v1/deployments \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "agent_id": "agt_01H8XK...",
    "agent_version": 2,
    "cron": "0 9 * * 1",
    "input_template": "Summarize last week'\''s refunds and publish a report.",
    "budget_micro_usd": 3000000,
    "window": "loose"
  }'

{
  "id": "dep_01H9EF...",
  "object": "deployment",
  "agent_id": "agt_01H8XK...",
  "agent_version": 2,
  "cron": "0 9 * * 1",
  "input_template": "Summarize last week's refunds and publish a report.",
  "budget_micro_usd": 3000000,
  "window": "loose",
  "timezone": "America/New_York",
  "on_idle": null,
  "identity": null,
  "enabled": true,
  "schedule_status": "scheduled",
  "next_run_at": "2026-08-24T13:00:00Z",
  "created_at": "2026-08-20T17:00:00Z"
}

Retrieve & list

GET /v1/deployments/{id}   # retrieve one -> 200
GET /v1/deployments        # list (cursor-paginated) -> 200

See Pagination.

Update a deployment

PATCH /v1/deployments/{id} → 200 OK. Scope agents:write. A partial update — send only the fields you are changing. Every field of the deployment is patchable except agent_id: repointing a schedule at a different agent would silently change what the cron does while keeping its history, so create a new deployment instead.

string

New cron expression. Recomputes next_run_at.

string

IANA zone the cron is read in.

string

The message each fire starts with.

integer

Pin a different agent version.

integer

Per-run cap, in micro-USD.

string

The idle-push URL, or null to stop pushing — null deletes the endpoint behind it and its signing secret. A new URL re-points the endpoint and re-enables it, so this is how a target that auto-disabled after repeated failures is brought back.

string

The persona each fire speaks as, or null to run as none. Re-validated against the agent’s grants.

boolean

The schedule switch — the same state pause and resume toggle.

curl -fsSL -X PATCH https://api.vetta.sh/v1/deployments/dep_01H9EF... \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "cron": "0 9 * * 1-5", "timezone": "Europe/London" }'

Returns the full deployment object, including the recomputed next_run_at and schedule_status. Errors — validation_failed (400) for an unparseable cron, an unknown timezone, an attempt to change agent_id, or an identity the agent does not hold; not_found (404), including an identity that does not exist.

Pause & resume

POST /v1/deployments/{id}/pause and POST /v1/deployments/{id}/resume → 200 OK. Toggle the schedule without deleting the deployment.

Response

{ "id": "dep_01H9EF...", "enabled": false, "schedule_status": "paused", "next_run_at": null }

Run once, now

POST /v1/deployments/{id}/run → 202 Accepted. Fires the deployment immediately, whatever its schedule says — including while it is paused or unscheduled. Every fire, scheduled or manual, is an ordinary session carrying this deployment’s deployment_id.

List runs

GET /v1/deployments/{id}/runs → 200 OK. Lists the sessions produced by this deployment, newest first. Cursor-paginated.

Response

{
  "data": [
    { "session_id": "ses_01H9GG...", "status": "idle", "started_at": "2026-08-24T09:00:02Z" }
  ],
  "has_more": false,
  "next_cursor": null
}

Delete a deployment

DELETE /v1/deployments/{id} → 200 OK. Removes the schedule. Sessions it already created are retained.

Response

{ "id": "dep_01H9EF...", "object": "deployment", "deleted": true }

Introduction

Core resources

Platform

Identity

The deployment object

Create a deployment

Retrieve & list

Update a deployment

Pause & resume

Run once, now

List runs

Delete a deployment

​The deployment object

​Create a deployment

​Retrieve & list

​Update a deployment

​Pause & resume

​Run once, now

​List runs

​Delete a deployment

The deployment object

Create a deployment

Retrieve & list

Update a deployment

Pause & resume

Run once, now

List runs

Delete a deployment