# Create Schedule (/reference-api/schema/schedules/create-schedule)

## Example scheduler server [#example-scheduler-server]

Install the runtime (including scheduler dependencies) and SQLite support:

```bash
uv pip install -U "agno[os]" sqlalchemy
export OS_SECURITY_KEY="your-agentos-key"
```

Save as `schedule_api.py` and run `python schedule_api.py`. This function-only workflow needs no model key:

```python
from agno.db.sqlite import SqliteDb
from agno.os import AgentOS
from agno.workflow import Step, StepInput, StepOutput, Workflow


def echo(step_input: StepInput) -> StepOutput:
    return StepOutput(content=str(step_input.input))


db = SqliteDb(db_file="tmp/schedule-api.db")
workflow = Workflow(id="scheduled-echo", db=db, steps=[Step(name="Echo", executor=echo)])
agent_os = AgentOS(
    db=db,
    workflows=[workflow],
    scheduler=True,
    scheduler_base_url="http://127.0.0.1:7777",
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="schedule_api:app", host="127.0.0.1", port=7777)
```

Creating this schedule enables it and schedules execution every day at 09:00 UTC:

```bash
curl --fail-with-body http://127.0.0.1:7777/schedules \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Daily echo","cron_expr":"0 9 * * *","timezone":"UTC","endpoint":"/workflows/scheduled-echo/runs","payload":{"message":"Scheduled hello"}}'
```

Keep its returned `id` for the schedule APIs. `endpoint` must be a local path, with no full URL, whitespace or control characters. Target a served code component or an available published database component; draft-only and archived database targets return **409**.

## Scheduler prerequisites [#scheduler-prerequisites]

Configure an AgentOS-level database with schedule methods. The [example scheduler server](/reference-api/schema/schedules/create-schedule#example-scheduler-server) uses SQLite. Database-backed schedule CRUD is available without starting the scheduler; execution requires `scheduler=True`, a running application lifespan and a `scheduler_base_url` matching the server's address.

Owners come from authenticated identity. Configured authorization uses `schedules:read`, `schedules:write` and `schedules:delete`. Creating, repointing, enabling or triggering a run schedule also requires permission to run its target. Non-run targets require admin permission when that authorization is enforced. An inaccessible record can return **404**; insufficient permission returns **403**.

For run endpoints, the executor sets `stream=false` and `background=true`, forwards the schedule owner and discards payload user overrides and version pins. See [Scheduler](/agent-os/scheduler/overview).

## `POST /schedules`

**Summary:** Create Schedule

### Authentication

- Option 1: `HTTPBearer` — HTTP bearer

### Parameters

None.

### Request body

Required: yes.

#### `application/json`

Schema `ScheduleCreate` (object).

**Top-level fields**
- `cron_expr` (string; required)
- `description` (string | null; optional)
- `endpoint` (string; required)
- `max_retries` (integer; optional; default `0`)
- `method` (string; optional; default `"POST"`)
- `name` (string; required)
- `payload` (object | null; optional)
- `retry_delay_seconds` (integer; optional; default `60`)
- `timeout_seconds` (integer; optional; default `3600`)
- `timezone` (string; optional; default `"UTC"`)

### Responses

#### `201`

Successful Response

**`application/json`**

Schema `ScheduleResponse` (object).

**Top-level fields**
- `created_at` (integer | null; optional)
- `cron_expr` (string; required)
- `description` (string | null; optional)
- `disabled_reason` (string | null; optional)
- `enabled` (boolean; required)
- `endpoint` (string; required)
- `id` (string; required)
- `managed_by` (string | null; optional)
- `max_retries` (integer; required)
- `method` (string; required)
- `name` (string; required)
- `next_run_at` (integer | null; optional)
- `payload` (object | null; optional)
- `retry_delay_seconds` (integer; required)
- `target_id` (string | null; optional)
- `target_type` (string | null; optional)
- `timeout_seconds` (integer; required)
- `timezone` (string; required)
- `updated_at` (integer | null; optional)
- `user_id` (string | null; optional)

#### Other responses

- `422` — Validation Error `application/json`: Schema `HTTPValidationError` (object).