ImportReadingProgressRequest

POST /api/v1/reading-progress/import request body.

accept_stem_matchesboolean

A stem match (v01.cbr renamed to v01.cbz) is reported either way, but only written when this is set: two files can share a stem, and applying it silently risks writing progress onto the wrong one.

conflict_policyConflictPolicy

How a conflict between an imported value and an existing row is resolved.

Possible values: [newest, furthest, skip_existing, overwrite]

dry_runboolean

Compute and report the outcome without writing anything.

file objectrequired

The whole export: one user's reading state, self-describing enough to be matched back against a differently organised library.

exported_atstring<date-time>required

formatstringrequired

Example: codex-reading-progress

includes_sessionsbooleanrequired

series object[]

Array [

books object[]

Array [

completions object[]

Array [

completed_atstring<date-time>required

idstring<uuid>required

started_atstring<date-time>required

]

file_hashstring

Empty when the book was never analyzed; never treated as a value to match on in that case.

file_namestringrequired

Example: v01.cbz

partial_hashstring

pathstringrequired

Relative to the series folder, so a series move does not invalidate it.

Example: Vol 01/v01.cbz

progress object

The live resume position for one book. Retains r2_progression: it is the only place the EPUB locator survives, since sessions strip it.

completedbooleanrequired

completed_at(string | null)<date-time>nullable

current_pageinteger<int32>required

progress_percentage(number | null)<double>nullable

r2_progressionstring | nullnullable

started_atstring<date-time>required

updated_atstring<date-time>required

sessions object[]

Omitted entirely (not an empty array) when the export was taken with include_sessions=false.

Array [

active_duration_ms(integer | null)<int64>nullable

client_ended_atstring<date-time>required

client_started_atstring<date-time>required

device_idstringrequired

device_namestring | nullnullable

duration_sourcestringrequired

"measured", "inferred", or "unknown".

Example: measured

idstring<uuid>required

kindstringrequired

"progress", "completed", or "reset".

Example: progress

pages_read(integer | null)<int32>nullable

passinteger<int32>required

server_recorded_atstring<date-time>required

to_page(integer | null)<int32>nullable

to_percentage(number | null)<double>nullable

]

]

external_ids object[]

Array [

idstringrequired

Example: 12345

sourcestringrequired

plugin:<name>, comicinfo, epub, or manual.

Example: plugin:mangabaka

]

library_relative_pathstringrequired

The series path as stored, relative to the library root.

Example: shonen/Naruto

namestringrequired

Example: Naruto

notesstring | nullnullable

rating(integer | null)<int32>nullable

rating_updated_at(string | null)<date-time>nullable

When the rating was last changed. The newest conflict policy needs it to tell a stale rating from a fresh one; a file without it never overwrites an existing rating except under overwrite.

]

versioninteger<int32>required

Example: 1

hash_modeHashMode

How aggressively hashes are used to match a book.

Possible values: [off, verify, match]

reattach_sessionsboolean

When a session or completion in the file already exists as the importer's own row but is not on a live book (its book was hard-deleted, leaving book_id null, or the scanner marked it deleted after the file moved), move it onto the matched book instead of skipping it.

source_preferencestring[]

External-id sources to try, in order, before falling back to path and then normalized name. An empty list skips straight to path matching.

ImportReadingProgressRequest

{
  "accept_stem_matches": true,
  "conflict_policy": "newest",
  "dry_run": true,
  "file": {
    "exported_at": "2024-07-29T15:51:28.071Z",
    "format": "codex-reading-progress",
    "includes_sessions": true,
    "series": [
      {
        "books": [
          {
            "completions": [
              {
                "completed_at": "2024-07-29T15:51:28.071Z",
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "started_at": "2024-07-29T15:51:28.071Z"
              }
            ],
            "file_hash": "string",
            "file_name": "v01.cbz",
            "partial_hash": "string",
            "path": "Vol 01/v01.cbz",
            "progress": {
              "completed": true,
              "completed_at": "2024-07-29T15:51:28.071Z",
              "current_page": 0,
              "progress_percentage": 0,
              "r2_progression": "string",
              "started_at": "2024-07-29T15:51:28.071Z",
              "updated_at": "2024-07-29T15:51:28.071Z"
            },
            "sessions": "Unknown Type: array,null"
          }
        ],
        "external_ids": [
          {
            "id": "12345",
            "source": "plugin:mangabaka"
          }
        ],
        "library_relative_path": "shonen/Naruto",
        "name": "Naruto",
        "notes": "string",
        "rating": 0,
        "rating_updated_at": "2024-07-29T15:51:28.071Z"
      }
    ],
    "version": 1
  },
  "hash_mode": "off",
  "reattach_sessions": true,
  "source_preference": [
    "string"
  ]
}