# Operating schedules

Create, replace, pause, resume, read and delete namespace-owned schedules through the API.

A schedule starts new runs on an interval or cron trigger. It is a durable, namespace-owned resource. The current CLI has no schedule command, so use HTTP or the matching gRPC operations.

## Trigger and policies

An interval carries seconds and nanoseconds. A cron trigger carries its expression. The config also supplies the deployed workflow type, input payload and optional search attributes.

- `Skip`: Overlap: ignore a tick while an earlier run remains active. Default.
- `BufferOne`: Overlap: keep at most one pending tick.
- `CancelPrevious`: Overlap: cancel the preceding run when a tick fires.
- `AllowAll`: Overlap: allow concurrent runs.
- `One`: Catch-up: start one representative missed tick. Default.
- `All`: Catch-up: start all missed ticks.
- `Skip (catch-up)`: Catch-up: discard missed ticks.


The server stamps the authorized namespace on every triggered run. A replacement cannot move a schedule to another tenant.

## Create

Deploy the first-workflow example, then create an interval schedule with its typed input. This example uses an unauthenticated local evaluation server. An authenticated deployment must add its bearer through the chosen client's credential handling.

**Terminal — start the deployed greeting every five minutes**

```bash
curl --fail-with-body -sS -X POST http://127.0.0.1:8080/schedules \
  -H 'content-type: application/json' \
  --data-binary '{"namespace":"default","config":{"namespace":"default","request_id":null,"payload":{"content_type":"application/json","bytes":[123,34,116,114,105,103,103,101,114,34,58,123,34,73,110,116,101,114,118,97,108,34,58,123,34,112,101,114,105,111,100,34,58,123,34,115,101,99,115,34,58,51,48,48,44,34,110,97,110,111,115,34,58,48,125,125,125,44,34,119,111,114,107,102,108,111,119,95,116,121,112,101,34,58,34,103,114,101,101,116,95,118,105,115,105,116,111,114,34,44,34,105,110,112,117,116,34,58,123,34,99,111,110,116,101,110,116,95,116,121,112,101,34,58,34,74,115,111,110,34,44,34,98,121,116,101,115,34,58,91,49,50,51,44,51,52,44,49,49,48,44,57,55,44,49,48,57,44,49,48,49,44,51,52,44,53,56,44,51,52,44,54,53,44,49,48,48,44,57,55,44,51,52,44,52,52,44,51,52,44,49,48,49,44,49,49,48,44,49,49,54,44,49,48,52,44,49,49,55,44,49,49,53,44,49,48,53,44,57,55,44,49,49,53,44,49,49,54,44,49,48,53,44,57,57,44,51,52,44,53,56,44,49,49,54,44,49,49,52,44,49,49,55,44,49,48,49,44,49,50,53,93,125,44,34,111,118,101,114,108,97,112,95,112,111,108,105,99,121,34,58,34,83,107,105,112,34,44,34,99,97,116,99,104,95,117,112,95,112,111,108,105,99,121,34,58,34,79,110,101,34,125]}}}'
```


Read the returned schedule id and state. The API generates the UUID; do not construct one from the workflow's display name.

## Read and control

**Terminal — use the schedule_id returned at creation**

```bash
curl --fail-with-body -sS "http://127.0.0.1:8080/schedules?namespace=default"
curl --fail-with-body -sS -X POST "http://127.0.0.1:8080/schedules/$SCHEDULE_ID/pause?namespace=default"
curl --fail-with-body -sS -X POST "http://127.0.0.1:8080/schedules/$SCHEDULE_ID/resume?namespace=default"
```


- `POST /schedules`: Create. JSON body has namespace and a config protocol envelope. Returns 201 with the schedule id and state.
- `GET /schedules?namespace=NAME`: List namespace-owned schedules.
- `GET /schedules/ID?namespace=NAME`: Describe one schedule.
- `PUT /schedules/ID`: Replace using namespace and a complete config envelope. Path supplies the schedule id.
- `DELETE /schedules/ID?namespace=NAME`: Delete the schedule.
- `POST /schedules/ID/pause?namespace=NAME`: Pause firing and retain state.
- `POST /schedules/ID/resume?namespace=NAME`: Resume firing.


Pause stops firing while keeping state. Resume permits later firing according to the trigger and catch-up policy. Delete removes the schedule resource; inspect any execution it already started separately.

## Replace

The update operation takes a complete replacement config in the same envelope as create. The id comes from the path. Keep the owning namespace unchanged.

## Choose a workloop instead

Use a workloop when one continuing identity needs carried state, health invariants and retirement. A schedule starts distinct workflow executions with their own input and history.