---
title: "Schedule API"
description: "Register schedules and inspect or operate their runs."
category: "Reference"
---

Base URL: your SDK-facing API, locally `http://localhost:8081`. Read [authentication and conventions](/docs/api) first. [Download OpenAPI 3.0](/openapi.yaml) for the full machine-readable contract.

## GET /schedules

List the application's schedules



**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `status` | query | No | string |  |
| `cursor` | query | No | string |  |
| `limit` | query | No | integer |  |

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | A page of schedules, each with a recent-run health summary | [ScheduleListResponse](/docs/api/schemas#schedulelistresponse) |
| `400` | Invalid status filter or limit | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `401` | Missing or invalid API key | [ProblemDetails](/docs/api/schemas#problemdetails) |

## PUT /schedules/{name}

Create or update a schedule

Idempotent upsert keyed on the application-scoped, case-insensitive name.

An unchanged body returns `200` without bumping `definitionVersion` or
moving `nextRunAt`, so re-applying the same schedule on every deploy is a
no-op. A changed body returns `200` with a new version and a re-planned
next run. A new name returns `201`. Re-applying an archived schedule
brings it back Active.

`definition` is validated by the same rules as `POST /pipelines`.


**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | path | Yes | string | Application-scoped schedule name, matched case-insensitively. |

### Request body

Required.

Content type: `application/json`. [ScheduleUpsertRequest](/docs/api/schemas#scheduleupsertrequest)

```yaml
$ref: "#/components/schemas/ScheduleUpsertRequest"
```

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | The existing schedule was updated or left unchanged | [Schedule](/docs/api/schemas#schedule) |
| `201` | A new schedule was created | [Schedule](/docs/api/schemas#schedule) |
| `400` | Validation failed, with per-field messages | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `401` | Missing or invalid API key | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `500` | The schedule could not be stored | [ProblemDetails](/docs/api/schemas#problemdetails) |

## GET /schedules/{name}

Get one schedule



**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | path | Yes | string | Application-scoped schedule name, matched case-insensitively. |

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Definition, policies, next and last run, health summary | [Schedule](/docs/api/schemas#schedule) |
| `400` | Invalid schedule name | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `401` | Missing or invalid API key | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `404` | No such schedule in this application | [ProblemDetails](/docs/api/schemas#problemdetails) |

## GET /schedules/{name}/runs

List a schedule's run history



**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | path | Yes | string | Application-scoped schedule name, matched case-insensitively. |
| `cursor` | query | No | string |  |
| `limit` | query | No | integer |  |

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | A page of runs, newest first | [ScheduleRunListResponse](/docs/api/schemas#schedulerunlistresponse) |
| `400` | Invalid schedule name or limit | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `401` | Missing or invalid API key | — |
| `404` | No such schedule in this application | [ProblemDetails](/docs/api/schemas#problemdetails) |

## POST /schedules/{name}/pause

Pause a schedule

Stops creating pipelines. The definition and history are kept.

**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | path | Yes | string | Application-scoped schedule name, matched case-insensitively. |

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | The paused schedule | [Schedule](/docs/api/schemas#schedule) |
| `401` | Missing or invalid API key | — |
| `404` | No such schedule in this application | [ProblemDetails](/docs/api/schemas#problemdetails) |

## POST /schedules/{name}/resume

Resume a schedule

Recomputes `nextRunAt` from now, so a schedule paused for a week does not
wake up owing a week of ticks whatever its catch-up policy says.


**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | path | Yes | string | Application-scoped schedule name, matched case-insensitively. |

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | The resumed schedule | [Schedule](/docs/api/schemas#schedule) |
| `400` | The stored schedule can no longer be planned | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `401` | Missing or invalid API key | — |
| `404` | No such schedule in this application | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `409` | The schedule has no future run (a Once schedule already past) | [ProblemDetails](/docs/api/schemas#problemdetails) |

## POST /schedules/{name}/archive

Archive a schedule

Terminal. Re-applying the definition with PUT brings it back Active.

**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | path | Yes | string | Application-scoped schedule name, matched case-insensitively. |

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | The archived schedule | [Schedule](/docs/api/schemas#schedule) |
| `401` | Missing or invalid API key | — |
| `404` | No such schedule in this application | [ProblemDetails](/docs/api/schemas#problemdetails) |

## POST /schedules/{name}/trigger

Run a schedule immediately

Creates a run with `trigger: Manual` right away. It does not move the
schedule's cursor, and overlap and catch-up policies do not apply — a
manual run was explicitly asked for. The optional `input` replaces the
first stage's input.


**Authentication:** `ApiKeyAuth`

### Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `name` | path | Yes | string | Application-scoped schedule name, matched case-insensitively. |

### Request body

Optional.

Content type: `application/json`. [ScheduleTriggerRequest](/docs/api/schemas#scheduletriggerrequest)

```yaml
$ref: "#/components/schemas/ScheduleTriggerRequest"
```

### Responses

| Status | Meaning | Schema |
| --- | --- | --- |
| `201` | The manual run and its pipeline | [ScheduleTriggerResponse](/docs/api/schemas#scheduletriggerresponse) |
| `400` | Invalid payload | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `401` | Missing or invalid API key | — |
| `404` | No such schedule in this application | [ProblemDetails](/docs/api/schemas#problemdetails) |
| `409` | The schedule is archived | [ProblemDetails](/docs/api/schemas#problemdetails) |