All endpoint paths below are relative to /api/v1, except /health.
The frontend's default API base URL is https://flashstep-api.onrender.com/api/v1.
JSON request bodies use Content-Type: application/json.
The v1.1.0 backend adds /sync/manifest and /sync/fetch without removing the
existing upload/download endpoints or requiring a database migration. Deploy
this backend before distributing the updated frontend. A frontend build can
override its base URL using --dart-define=API_BASE_URL=<base URL> for isolated
testing; this does not change the server's route prefix.
The v1.2.0 backend also adds paged /sync/reviews and a review-history
fingerprint to the first manifest page. Deploy it before distributing the
v1.2.0 frontend so review history and daily limits reconcile across devices.
Earlier clients continue using their existing sync routes; no migration is needed.
GET /health is outside /api/v1 and does not require authentication.
Response 200 OK:
{"status": "ok"}This checks HTTP service availability; it does not execute a database health query.
Protected routes require:
Authorization: Bearer <JWT_TOKEN>Registration, login, and the health check are public. All deck, card, sync,
analytics, account-edit, and /me routes require the header above, including
browsing or downloading public decks.
POST /auth/register
Request body:
{
"username": "john_doe",
"email": "john@example.com",
"password": "password123"
}Response 201 Created:
{
"user": {
"id": "uuid",
"username": "john_doe",
"email": "john@example.com",
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-21T10:00:00Z"
},
"token": "jwt_token"
}Registration email rules:
- Email addresses are trimmed and compared case-insensitively, including legacy mixed-case addresses already stored in the database.
- An email remains reserved while its user row exists, including a soft-deleted account. Concurrent requests for the same normalized email cannot create multiple accounts.
409 Conflictwith{"error":"email already exists"}indicates an email already in use. Invalid input and other registration failures return400.
POST /auth/login
Request body:
{
"email": "john@example.com",
"password": "password123"
}Response 200 OK:
{
"user": {
"id": "uuid",
"username": "john_doe",
"email": "john@example.com",
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-21T10:00:00Z"
},
"token": "jwt_token"
}GET /me
Response 200 OK:
{
"id": "uuid",
"username": "john_doe",
"email": "john@example.com",
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-21T10:00:00Z"
}PUT /auth/change-username
Request body:
{
"username": "new_username"
}Response 200 OK:
{
"message": "username updated successfully"
}Errors:
400 Bad Request: invalid request payload401 Unauthorized: missing or invalid token500 Internal Server Error: database failure
PUT /auth/change-password
Request body:
{
"old_password": "current_password",
"new_password": "new_secure_password"
}Response 200 OK:
{
"message": "password updated"
}Errors:
400 Bad Request: invalid request payload401 Unauthorized: old password incorrect or token missing/invalid
DELETE /auth/delete-account
Response 200 OK:
{
"message": "account deleted"
}Behavior notes:
- this endpoint performs a soft delete of the authenticated user,
- the account becomes unavailable for normal use immediately,
- permanent cleanup is handled later by backend maintenance.
POST /decks
Request body:
{
"title": "Biology",
"description": "Class 12 notes",
"is_public": false
}Response 201 Created:
{
"id": "deck_uuid"
}Validation notes:
titleis required- empty/blank descriptions may be stored as
null
GET /decks
Returns the authenticated user's own active decks only.
Response 200 OK:
[
{
"id": "deck_uuid",
"user_id": "user_uuid",
"title": "Biology",
"description": "Class 12 notes",
"is_public": false,
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-21T10:00:00Z",
"version": 1,
"is_deleted": false
}
]GET /decks/public
Returns public, non-deleted decks owned by other users.
Response 200 OK:
[
{
"id": "deck_uuid",
"user_id": "owner_uuid",
"title": "Operating Systems",
"description": "Short OS review deck",
"updated_at": "2026-03-24T10:00:00Z",
"version": 3,
"owner_username": "deck_owner",
"card_count": 24
}
]Behavior notes:
- excludes deleted decks,
- excludes decks owned by the requesting user,
card_countcounts active cards only,- optional
searchfilters titles using a case-insensitive SQLILIKEpattern surrounded by%; URL-encode the value (for example,/decks/public?search=Operating%20Systems), - blank/omitted search returns all matching public decks; results are ordered by
updated_atdescending, then title ascending. This endpoint is not paginated.
POST /decks/:id/download
Copies a public deck into the authenticated user's account.
Response 201 Created:
{
"deck": {
"id": "new_deck_uuid",
"user_id": "current_user_uuid",
"title": "Operating Systems",
"description": "Short OS review deck",
"is_public": false,
"created_at": "2026-03-24T10:00:00Z",
"updated_at": "2026-03-24T10:00:00Z",
"version": 1,
"is_deleted": false
},
"cards": [
{
"id": "new_card_uuid",
"deck_id": "new_deck_uuid",
"front": "What does a mutex do?",
"back": "It provides mutual exclusion for critical sections.",
"state": "new",
"interval": 0,
"ease_factor": 2.5,
"repetition_count": 0,
"due_timestamp": "2026-03-24T10:00:00Z",
"last_reviewed_at": null,
"created_at": "2026-03-24T10:00:00Z",
"updated_at": "2026-03-24T10:00:00Z",
"version": 1,
"is_deleted": false
}
],
"downloaded_from": "source_deck_uuid",
"source_owner_id": "owner_uuid",
"source_owner_username": "deck_owner"
}Behavior notes:
- the copied deck is owned by the downloader,
- the copied deck is created as
is_public=false, - copied cards receive new card IDs and belong to the new deck,
- the original public deck is unchanged,
- copied cards start with fresh review scheduling (
state=new, interval and repetition count zero, ease factor 2.5, due now, no previous review), - downloading your own public deck returns
400; an unavailable, private, or deleted source returns404. Invalid source UUIDs return400.
PUT /decks/:id
Supports deck rename and normal deck metadata edits.
Request body:
{
"title": "Biology Updated",
"description": "Updated notes",
"is_public": true,
"version": 1
}Response 200 OK:
{
"message": "updated"
}Errors:
400 Bad Request: invalid payload or empty title401 Unauthorized: invalid or missing JWT404 Not Found: deck not found for that user409 Conflict: version conflict
Behavior notes:
- this route is used for renaming decks,
versionmust be provided,- updates apply only to the owner's non-deleted deck,
- successful updates increment
versionand refreshupdated_at.
DELETE /decks/:id
Response 200 OK:
{
"message": "deleted"
}Behavior notes:
- delete is a logical delete (
is_deleted=true), - deleting a deck also logically deletes its child cards,
- deleted rows may still appear in sync payloads with
is_deleted=true, - the client may provide a short undo window before permanently removing the deck and cards from the local database.
POST /cards
Request body:
{
"deck_id": "deck_uuid",
"front": "What is DNA?",
"back": "Genetic material"
}Response 201 Created:
{
"id": "card_uuid"
}Validation notes:
deck_idmust be a valid UUID,frontandbackare required,- cards can only be created in the authenticated user's own active decks,
- a deck can contain at most 50 active cards.
The capacity check and insertion are one transaction with a parent-deck lock, shared with sync uploads. Concurrent creation cannot bypass the active-card limit.
Errors:
400 Bad Request: invalid JSON/UUID, blank front/back, or the deck already has 50 active cards401 Unauthorized: missing or invalid JWT403 Forbidden: missing, deleted, or unauthorized parent deck500 Internal Server Error: database/transaction failure
GET /decks/:deck_id/cards
Response 200 OK:
[
{
"id": "card_uuid",
"deck_id": "deck_uuid",
"front": "What is DNA?",
"back": "Genetic material",
"state": "new",
"due_timestamp": "2026-03-22T10:00:00Z",
"updated_at": "2026-03-21T10:00:00Z",
"version": 1,
"is_deleted": false
}
]Behavior notes:
- returns cards for either:
- one of the authenticated user's decks, or
- a public deck,
- deleted cards are excluded from normal listing,
- parent deck must also be active.
PUT /cards/:id
Supports changing the front/back content of a card.
Request body:
{
"front": "Updated Question",
"back": "Updated Answer",
"version": 1
}Response 200 OK:
{
"message": "updated"
}Errors:
400 Bad Request: invalid payload or empty front/back401 Unauthorized: invalid or missing JWT404 Not Found: card not found for that user409 Conflict: version conflict
Behavior notes:
versionmust be provided,- updates apply only if the card belongs to one of the user's active decks,
- successful updates increment
versionand refreshupdated_at.
DELETE /cards/:id
Response 200 OK:
{
"message": "deleted"
}Behavior notes:
- delete is a logical delete (
is_deleted=true), - only the targeted card is deleted,
- deleted rows may still appear in sync payloads with
is_deleted=true, - the client may provide a short undo window before permanently removing the card from the local database.
GET /sync/manifest?cursor=<deck UUID>&limit=500
Query parameters:
cursor: optional deck UUID; omit it for the first page. Subsequent pages return deck IDs strictly greater than this cursor.limit: integer from 1 through 500; omission or explicit0uses 500.
Response 200 OK:
{
"decks": [
{
"id": "11111111-1111-4111-8111-111111111111",
"fingerprint": "opaque revision digest"
}
],
"next_cursor": null,
"reviews_fingerprint": "opaque review-history digest"
}Only owned decks are returned, ordered by UUID, including deleted decks.
Fingerprints include the deck revision/timestamp/deletion flag and ordered
child-card IDs, parent IDs, revisions, timestamps, and deletion flags. Treat the
fingerprint as an opaque equality token, not a timestamp or authentication value.
No card bodies or review logs are returned. Empty results use decks: [].
The first page (without cursor) also includes reviews_fingerprint, an
opaque token that changes when immutable review history is appended. Later
manifest pages omit it. Earlier backend versions omit it on every page; clients
should continue deck reconciliation without review-history download in that case.
If more records exist, next_cursor is the last returned deck UUID. Pass it as
cursor in the next request; null means the manifest is complete.
Errors:
400 Bad Request: invalid UUID cursor or invalid/non-integer limit401 Unauthorized: missing or invalid JWT500 Internal Server Error: database/read failure
POST /sync/fetch
Request body:
{
"deck_ids": ["11111111-1111-4111-8111-111111111111"],
"limit": 500
}deck_ids: required array of 1–25 UUID entries. Every deck must belong to the authenticated account; public visibility does not grant access through sync. Duplicate IDs are deduplicated, but the input still cannot exceed 25 entries.cursor: optional card UUID; omit it for the first page. On later pages, supply the returnednext_cursorand keep the samedeck_ids.limit: integer from 1 through 500; omission or explicit0uses 500.- The request body is limited to 1 MiB; oversized bodies return
400.
Response 200 OK contains decks, cards, and next_cursor. Deck and card
objects have the complete record shapes shown under Download Changes below.
Each page repeats all selected deck records, ordered by deck UUID, even when
that page has no cards. cards contains up to limit records ordered by card
UUID across the entire selected set, not a separate limit/cursor for each deck.
Both arrays include tombstones. Empty card results use cards: [].
If more cards exist, next_cursor is the last returned card UUID; otherwise it
is null. Review logs, fingerprints, and the upload-only from_deck_deletion
marker are not included. Timestamp strings are UTC RFC3339 with available
fractional precision; nullable card dates and deck descriptions remain null.
Errors:
400 Bad Request: malformed/oversized JSON, missing or invalid deck IDs, more than 25 input IDs, any missing/unauthorized deck, invalid cursor or limit401 Unauthorized: missing or invalid JWT500 Internal Server Error: database/read/transaction failure
GET /sync/reviews?cursor=<review UUID>&limit=500
cursor: optional review-log UUID. Omit it for the first page; later pages return owned review logs with IDs strictly greater than the cursor.limit: integer from 1 through 500; omission or explicit0uses 500.
Response 200 OK:
{
"review_logs": [
{
"id": "11111111-1111-4111-8111-111111111111",
"user_id": "22222222-2222-4222-8222-222222222222",
"card_id": "33333333-3333-4333-8333-333333333333",
"rating": "good",
"previous_interval": 0,
"new_interval": 1,
"reviewed_at": "2026-03-24T10:00:00Z",
"device_id": null,
"created_at": "2026-03-24T10:00:00Z"
}
],
"next_cursor": null
}Only the authenticated account's review logs are returned, ordered by UUID.
Empty results use review_logs: []. If more exist, next_cursor is the last
returned review UUID. Repeated reads are safe because review-log IDs are stable
and retries of the same log do not create duplicates. The endpoint is read-only
and adds no table or column. New reviews arriving during pagination are detected
by a changed manifest fingerprint on the next sync.
Errors: 400 for an invalid cursor or limit, 401 for missing or invalid
authentication, and 500 for a database/read failure.
- Upload queued mutations in deck → card → review-log order. The updated frontend coalesces concurrent sync calls per account and uses batches of at most 200 records and approximately 1 MiB. These are client batching targets, not newly imposed limits on the legacy upload endpoint. An oversized single operation is attempted separately and retained if it fails.
- Read the manifest every sync and compare account-specific cached fingerprints. Fetch missing or changed decks in groups of up to 25.
- Merge every card page, including tombstones, while protecting still-queued local edits. Save the manifest's original fingerprint only after all pages for that group merge successfully. Invalidate fingerprints for decks with remaining pending edits; missing/corrupt metadata starts fresh reconciliation.
- When the first manifest page's review fingerprint changes, fetch review logs
through
/sync/reviewsand merge them by immutable ID. Save the fingerprint only after all pages merge and no local review upload remains pending. - Continue until card, review, and manifest cursors are
null. The endpoints do not hold a snapshot across HTTP requests; each fetch request has its own consistent read transaction. Changes arriving during paging are detected on the following sync. Interrupted downloads can safely restart.
Only a manifest 404/405 selects the older-backend fallback: call
GET /sync/download without since and reconcile the full response. Other
errors fail the sync for retry. A device-clock checkpoint can miss late offline
uploads, so the updated frontend does not use it to filter reconciliation.
Account changes stop further work; only acknowledged queue operations are removed.
POST /sync/upload
Request body:
{
"decks": [
{
"id": "uuid",
"user_id": "uuid",
"title": "Operating Systems",
"description": "Short OS review deck",
"is_public": false,
"created_at": "2026-03-24T10:00:00Z",
"updated_at": "2026-03-24T10:00:00Z",
"version": 1,
"is_deleted": false
}
],
"cards": [
{
"id": "uuid",
"deck_id": "uuid",
"front": "What does a mutex do?",
"back": "It provides mutual exclusion for critical sections.",
"state": "review",
"interval": 6,
"ease_factor": 2.5,
"repetition_count": 3,
"due_timestamp": "2026-03-30T10:00:00Z",
"last_reviewed_at": "2026-03-24T10:00:00Z",
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-24T10:00:00Z",
"version": 4,
"is_deleted": false
}
],
"review_logs": [
{
"id": "uuid",
"user_id": "uuid",
"card_id": "uuid",
"rating": "good",
"previous_interval": 2,
"new_interval": 6,
"reviewed_at": "2026-03-24T10:00:00Z",
"device_id": null,
"created_at": "2026-03-24T10:00:00Z"
}
]
}Response 200 OK:
{
"status": "synced",
"decks_processed": 1,
"cards_processed": 1,
"review_logs_processed": 1,
"server_time": "2026-03-24T10:00:01Z"
}Errors:
400 Bad Request: invalid payload/UUID, missing required fields, unauthorized references, cross-account deck/card/review-log ID collisions, review-loguser_idmismatch, or a deck exceeding the 50-active-card limit401 Unauthorized: invalid or missing JWT500 Internal Server Error: server/database error while applying sync
Upload behavior:
- Omitted entity arrays are treated as empty. Deck ownership comes from the
authenticated account; a deck's supplied
user_idis not used to assign ownership. Review-loguser_iddefaults to that account when omitted and must match when supplied. - Deck IDs, card IDs/parent deck IDs, and review-log IDs/card IDs are required
UUIDs. Active decks require a title; active cards require front and back.
Reviews require a rating (
again,hard,good, oreasy) and may supply a nullabledevice_idUUID. Reuse the same review-log ID when retrying. - Supply valid RFC3339 timestamps with fractional precision as needed. Current
normalization substitutes server time for missing/malformed
created_at,updated_at, and review timestamps; malformed optional card dates becomenull. Clients should preserve valid original timestamps for conflict resolution. - Each request is atomic: accepted deck/card changes, new review logs, affected progress, and relevant analytics commit together. Failed requests roll back; concurrent uploads for the same account are serialized. Separate HTTP batches are separate transactions, so a later failed batch does not undo earlier acknowledgments.
- Stale or equal-timestamp deck/card changes are ignored with a successful
response.
*_processedcounts describe input records, including ignored conflicts and duplicate logs; they are not counts of inserted/changed rows. Reconciliation is necessary to read the resolved server state. - A repeated review-log ID for the same account/card is an idempotent no-op, not an update to its rating or history. New logs and accepted edits to reviewed cards recompute affected progress; duplicate logs skip expensive recomputation.
- Only an accepted authorized deck deletion cascades to active child cards.
Whole-deck child tombstones can additionally send
from_deck_deletion: true; these are ignored while their parent is active, protecting separately batched children after a rejected/undone deck deletion. Individual-card deletes omit the marker. It is not stored in the database or returned in downloads. - Restore a deleted deck through a newer
is_deleted=falsedeck mutation. Restoring the deck does not automatically restore its cards: upload newer card mutations explicitly after the deck. An active card change against a deleted parent is ignored if stale relative to the parent, otherwise rejected. - A lost response can be retried with the original IDs and timestamps. An
upload response's
server_timeis UTC at whole-second precision; it is not a safe cross-device reconciliation checkpoint.
GET /sync/download?since=2026-03-21T00:00:00Z
Response 200 OK:
{
"decks": [
{
"id": "uuid",
"user_id": "uuid",
"title": "Operating Systems",
"description": "Short OS review deck",
"is_public": false,
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-24T10:00:00Z",
"version": 3,
"is_deleted": false
}
],
"cards": [
{
"id": "uuid",
"deck_id": "uuid",
"front": "What does a mutex do?",
"back": "It provides mutual exclusion for critical sections.",
"state": "review",
"interval": 6,
"ease_factor": 2.5,
"repetition_count": 3,
"due_timestamp": "2026-03-30T10:00:00Z",
"last_reviewed_at": "2026-03-24T10:00:00Z",
"created_at": "2026-03-21T10:00:00Z",
"updated_at": "2026-03-24T10:00:00Z",
"version": 4,
"is_deleted": false
}
]
}Query notes:
sinceaccepts RFC3339 timestamps, including fractional seconds. Invalid nonblank values return400; omitted/blank values use the Unix epoch.- Returns owned deck/card records whose individual
updated_atis strictly greater thansince, including deleted rows and cards in deleted decks. Omission therefore returns all post-epoch owned state. Public decks owned by someone else are not included. - Decks and cards are each ordered by
updated_at,created_at, then UUID. Empty arrays are[]; the response is not paginated and has no review logs. - Both record lists share one consistent read transaction. Response timestamps preserve available fractional precision in UTC RFC3339 form.
401indicates invalid/missing authentication; database/transaction failures return500.
Sync rules:
- local database is the source of truth while offline,
- the client uploads queued mutations first, then downloads server updates,
is_deleted=trueis part of normal sync state,- conflict resolution is last-write-wins using
updated_at, - if timestamps are equal, server data wins,
- direct edit routes increment version numbers; sync writes carry the supplied
version, and existing database triggers may refresh
updated_at. Preserve the server's returned revisions rather than assuming payload timestamps survive, - delete beats stale non-delete updates,
- deleted deck/card rows may continue syncing until all devices converge.
GET /analytics/dashboard?range_days=7|30|90
Returns the analytics dashboard payload for the authenticated user.
Response shape:
usernamerange_daysgenerated_at- current card/deck counters from the cloud database:
total_deckstotal_cardslearned_cardsmature_cardsnew_cardslearning_cardsreview_cardsdue_nowdue_next_24_hours
- range metrics from persisted analytics rollups:
reviews_todayreviews_in_rangeactive_days_in_rangeaverage_study_loadretention_ratebest_day_count
- long-term indicators:
current_streaklongest_interval_days
rating_breakdownreview_activityaccuracy_trenddeck_insights
Notes:
- dashboard data is server-backed,
- chart data is sourced from persisted 7 / 30 / 90 day rollups,
- current due/card counters are computed from live deck/card rows,
- the endpoint accepts only
7,30, or90.
Omitting range_days selects 30. Invalid/non-integer values return 400;
authentication failures return 401, and database failures return 500.
New review logs accepted through sync refresh persisted analytics in the same
upload transaction. Duplicate-log retries do not repeat that refresh.
GET /analytics/daily-review-count?from=YYYY-MM-DD&to=YYYY-MM-DD
Returns number of reviews per day from persisted daily analytics rows.
GET /analytics/average-session-length?from=YYYY-MM-DD&to=YYYY-MM-DD
Returns average daily review load across active study days in the selected range.
GET /analytics/accuracy-trends?from=YYYY-MM-DD&to=YYYY-MM-DD
Returns correctness percentage over time.
GET /analytics/deck-performance?deck_id=<UUID>
Returns all-time performance per deck using persisted user_progress rows.
review_logsremain the global synced source of truth for review history,user_progressstores per-user, per-deck summary progress,user_card_progressstores per-user, per-card score/state snapshots,analytics_daily_statsstores daily aggregated review history,analytics_rollupsstores the current 7 / 30 / 90 day dashboard rollups.
At 00:00 UTC, the backend recomputes analytics daily rows and dashboard rollups for active users.
{
"error": "error message"
}- The client persists the JWT and
user_idlocally after a successful login. - On app launch, the splash flow first checks for a stored session and re-enters the app without prompting for credentials again.
- The login screen should only reappear after an explicit logout or when
GET /mereturns an authentication failure such as401 Unauthorized/403 Forbidden. - Temporary connectivity failures must not be treated as logout events by the client.