---
title: "schedule wake"
method: POST
path: "/api/v1/agent-wake/schedule_wake"
tags: ["agent-wake"]
---

# schedule wake

`POST /api/v1/agent-wake/schedule_wake`

## Request

- Base URL: `https://cloudforbots.com`
- URL: `https://cloudforbots.com/api/v1/agent-wake/schedule_wake`
- Auth: HTTP bearer

Schedule a wake-up for your agent. At the time you pick, Agent Wake POSTs your saved state (notes, thread ID, next step) to your callback URL, or holds it for check_wakes. Use it so a later, fresh session picks up where this one stopped. Call once without confirm to preview what will be saved, show the user, then call again with confirm=true.

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `when` string, required: When to wake: "in 30 minutes", "in 2 hours", "in 3 days", or an ISO time like 2026-10-16T14:00:00Z. Between 1 minute and 365 days out.
  - `repeat_minutes` integer: Optional. Repeat every N minutes after the first wake (free: 60+, Pro: 5+).
  - `state` object: What your future session needs: goal, progress, next step, IDs. Free up to 8 KB, Pro up to 64 KB.
  - `thread_id` string: Optional conversation or task ID to resume.
  - `callback_url` string: Optional public https URL to POST the wake to (for example your agent runner webhook). Without it, collect wakes with check_wakes.
  - `inbox` string: Your private inbox name (12+ chars, keep it secret, reuse it every session). Optional if you send an API key: then the key is your inbox.
  - `confirm` boolean: false or missing = preview only, nothing saved. true = save the wake.

## Response `200`

Tool result (always includes request_id).

- object

## Other responses

- `400`: Bad JSON
- `401`: Missing or bad key
- `403`: Key limits (scopes) do not allow this tool or action
- `409`: Same Idempotency-Key still running
- `422`: Idempotency-Key reused on another route
- `429`: Over 20 requests/second for this key, or free daily limit
- `504`: Tool did not answer in time; retry with the same Idempotency-Key

---

[API](https://skmtc.dev/cloudforbots/apis/cloud-for-bots-api.md) · [All operations](https://skmtc.dev/cloudforbots/apis/cloud-for-bots-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cloudforbots/apis/cloud-for-bots-api/revisions/1afdb5648693?raw)