---
title: "Create Reminder"
method: POST
path: "/v1/teams/{team_id}/reminders"
tags: ["schedules"]
---

# Create Reminder

`POST /v1/teams/{team_id}/reminders`

Do this later — in that conversation, or as a fresh workspace item.

The caller supplies the business task and the time. Stormy owns the
execution provider, model, session verification, authority, and the durable
schedule definition. Which of the two shapes this is comes from one field,
`session_id`, and the receipt always says which one was written.

## Path parameters

- `team_id` string, uuid, required

## Headers

- `authorization` string, nullable
- `x-darwin-token` string, nullable

## Request body

- CreateReminderRequest — Do this later. TWO SHAPES, and the only difference is where it lands. `session_id` PRESENT — come back to that conversation. The woken turn joins the session's own FIFO, so it holds everything that was said and answers where the question was asked. This is 1,707 of the 2,122 schedules this product has ever written. `session_id` ABSENT — a fresh, clean item scoped to the workspace. No conversation is resumed and nothing is interrupted. 415 of 2,122, and it was already the path `scheduler._dispatch_schedule` took for an untargeted `agent.run`; it simply had no door on this route. WHY THE SECOND SHAPE HAD TO EXIST HERE, and it is not a convenience. This field was mandatory, and `_current_session_id` raises when `STORMY_MCP_SESSION_ID` is unset — which it always is in the `./kk` seat, because a seat is not a durable turn. So the seat's only scheduling verb refused, every time. A refusal there does not fail safe: measured in the live seat on 2026-08-15, the model answered the refusal by running `nohup bash -c 'sleep 30 && echo ... > bg_task_30s.log' &` and reporting "Yes! I have dispatched a background task." A process that dies with the container, a log nobody reads, and a confident false receipt. The cure for that is not a better refusal, it is a shape that works. Sibling of `/schedules`, which stays the general form: any kind, on a cron or an interval. RECURRENCE IS DELIBERATELY NOT HERE — 2,121 of 2,122 rows are `{"type": "once"}` and 544 of 544 recorded agent calls asked for one wake. A repeating job is infrastructure and goes through `/schedules`.
  - `session_id` string, uuid, nullable
  - `message` string, required
  - `next_run_at` string, date-time, nullable
  - `in_seconds` integer, nullable
  - `dedupe_key` string, required
  - `tag` string

## Response `201`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/stormy/apis/stormy-control-plane.md) · [All operations](https://skmtc.dev/stormy/apis/stormy-control-plane/llms.txt) · [OpenAPI document](https://skmtc.dev/stormy/apis/stormy-control-plane/revisions/b09e3c4ee2af?raw)