Skip to main content

ReadingSessionDto

One reading session measured by a client.

activeDurationMsinteger,null<int64>nullable

Active reading time in milliseconds, measured by the reader.

Must be time the reader actually spent reading, with the timer paused while the app is backgrounded, the screen is locked, or the reader has been idle past the timeout. Wall-clock elapsed is not this value, and anything larger than the session's own span is clamped to it.

Example: 934000
bookIdstring<uuid>required

The book this session belongs to.

Example: 550e8400-e29b-41d4-a716-446655440002
clientEndedAtstring<date-time>required

When this session ended, by the client's clock.

This is what orders sessions against each other, so it must reflect when the reading happened rather than when it is being submitted. A session read offline and synced hours later still sorts by when it was read.

Example: 2026-08-14T19:20:45Z
clientStartedAtstring<date-time>required

When this session began, by the client's clock.

Example: 2026-08-14T19:02:11Z
deviceIdstringrequired

Stable identifier for the device that produced this session.

Example: 8f3d1c7a-2b44-4e51-9c2a-1f7d3e5b9a01
deviceNamestring | nullnullable

Human-readable device name, for the reading statistics UI.

Example: Ash's iPhone
idstring<uuid>required

Client-generated identifier for this session.

Submitting the same id twice is a no-op, so a batch whose response was lost can be replayed without double-counting the reading.

Example: 550e8400-e29b-41d4-a716-446655440000
kindReadingSessionKindDto (string)required

What this session asserts.

Possible values: [progress, completed, reset]

pagesReadinteger,null<int32>nullable

Distinct pages advanced through during this session.

Example: 31
r2Progressionstring | nullnullable

R2Progression JSON (Readium standard) for EPUB position sync.

toPageinteger,null<int32>nullable

Page reached, for comics and PDF (1-indexed).

Example: 42
toPercentagenumber,null<double>nullable

Fraction read, for EPUB (0.0 to 1.0).

Example: 0.45
ReadingSessionDto
{
  "activeDurationMs": 934000,
  "bookId": "550e8400-e29b-41d4-a716-446655440002",
  "clientEndedAt": "2026-08-14T19:20:45Z",
  "clientStartedAt": "2026-08-14T19:02:11Z",
  "deviceId": "8f3d1c7a-2b44-4e51-9c2a-1f7d3e5b9a01",
  "deviceName": "Ash's iPhone",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "progress",
  "pagesRead": 31,
  "r2Progression": "string",
  "toPage": 42,
  "toPercentage": 0.45
}