---
title: "Recommend newCardsPerDay from a deadline"
method: POST
path: "/plan/new-cards"
---

# Recommend newCardsPerDay from a deadline

`POST /plan/new-cards`

## Request

- Base URL: `https://fluidrecall.com/api/v1`
- URL: `https://fluidrecall.com/api/v1/plan/new-cards`
- Auth: one of:
  - HTTP bearer
  - HTTP dpop

Routine read. Does not write. Given a deadline and card counts, returns recommended newCardsPerDay (ceil of remaining new cards ÷ study days through the deadline, clamped to 0–9999). There is no silent default of 20. This is new-card trickle math. Review load grows, so treat the number as a floor: Muse may raise N or negotiate more study time. Call this before createDeck when the person has a deadline, and again after bulk card adds. Send remainingNewCards, totalCards, or deckId. When deckId is set, remaining new cards and current N come from that owned deck unless you override them. Another token's deck is 404. Prefer a YYYY-MM-DD deadline so timezone does not shift the date. Create still requires an explicit newCardsPerDay; this call only helps you choose it.

## Request body

- DeadlinePlanRequest
  - `deadline` string, required: YYYY-MM-DD preferred. A UTC instant ending in Z is converted to the study day in timezone.
  - `asOf` string: UTC ISO-8601 timestamp ending in Z
  - `timezone` string: IANA name. Defaults to the account timezone.
  - `dayBoundaryHour` integer
  - `remainingNewCards` integer
  - `totalCards` integer
  - `alreadyLearned` integer
  - `skipWeekends` boolean
  - `studyDaysPerWeek` integer
  - `bufferStudyDays` integer: Reserve this many study days at the end of the window as review-only buffer.
  - `currentNewCardsPerDay` integer, nullable: Compare this N to the recommendation. Omit to use the deck's effective N when deckId is set.
  - `deckId` string, uuid: Fill remaining new cards and current N from this owned deck unless you override them.

## Response `200`

Recommended N, days remaining, projected finish, on-track, and coaching.

- DeadlinePlan
  - `deadline` string, required: Deadline study day as YYYY-MM-DD.
  - `asOf` string, required: UTC ISO-8601 timestamp ending in Z
  - `asOfStudyDay` string, required: Study day of asOf as YYYY-MM-DD.
  - `timezone` string, required
  - `dayBoundaryHour` integer, required
  - `remainingNewCards` integer, required
  - `alreadyLearned` integer, required
  - `totalCards` integer, required
  - `calendarDaysUntilDeadline` integer, required
  - `studyDaysUntilDeadline` integer, required
  - `recommendedNewCardsPerDay` integer, required: ceil(remainingNewCards / studyDaysUntilDeadline), clamped to 0–9999. Not a default of 20. A floor from the deadline.
  - `currentNewCardsPerDay` integer, nullable, required
  - `projectedFinishDateAtCurrent` string, nullable, required: YYYY-MM-DD of the last new-card introduction at the current N. Null if current N is missing or 0.
  - `projectedFinishDateAtRecommended` string, nullable, required
  - `onTrack` boolean, nullable, required: True when current N finishes remaining new cards by the deadline. Null when there is no current N.
  - `pace` 'done' | 'overdue' | 'faster' | 'on_track' | 'slower' | 'unknown', required
  - `countsFromDeck` boolean, required
  - `applied` boolean, required
  - `deckId` string, uuid, nullable, required
  - `deck` object, nullable, required: The patched deck after apply. Null on preview.
  - `assumptions` string[], required
  - `coaching` string, required

## Other responses

- `400`: Invalid body or missing card counts.
- `401`: Missing or wrong token.
- `404`: No deck with that id for this token.

---

[API](https://skmtc.dev/fluidrecall/apis/fluid-recall.md) · [All operations](https://skmtc.dev/fluidrecall/apis/fluid-recall/llms.txt) · [OpenAPI document](https://skmtc.dev/fluidrecall/apis/fluid-recall/revisions/7bf2563c3d2a?raw)