---
title: "Batch upsert across all domains"
method: POST
path: "/v1/sync/push"
tags: ["sync"]
---

# Batch upsert across all domains

`POST /v1/sync/push`

## Request

- Base URL: `https://api.ditto.audio` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ditto.audio/v1/sync/push`
- Auth: HTTP bearer

## Request body

- SyncPushDto
  - `books` UpsertBookDto[]
    - `bookId` string, required: client book id (stable across devices)
    - `title` string, required
    - `author` string
    - `format` string
    - `chapterCount` number
    - `contentHash` string: sha-256 of the book file
    - `coverImageUrl` string
    - `addedAtMs` number: client add time, ms epoch
    - `deleted` boolean: tombstone — remove from cloud library
  - `progress` UpsertProgressDto[]
    - `bookId` string
    - `chapterIndex` number
    - `paragraphIndex` number
    - `cfi` string: epub.js CFI (web reader)
    - `percentComplete` number: 0..1
    - `totalReadingTimeMs` number
    - `lastReadAtMs` number
  - `bookmarks` UpsertBookmarkDto[]
    - `clientId` string, required: client bookmark id
    - `bookId` string, required
    - `chapterIndex` number
    - `paragraphIndex` number
    - `cfi` string
    - `label` string
    - `note` string
    - `createdAtMs` number
    - `deleted` boolean
  - `annotations` UpsertAnnotationDto[]
    - `clientId` string, required: client annotation id
    - `bookId` string, required
    - `kind` 'highlight' | 'note' | 'clipping', required
    - `chapterIndex` number
    - `paragraphIndex` number
    - `cfi` string
    - `selectedText` string
    - `color` string
    - `noteContent` string
    - `chapterTitle` string
    - `createdAtMs` number
    - `deleted` boolean
  - `models` UpsertModelRefDto[]
    - `modelId` string, required
    - `category` string
    - `isDefault` boolean
    - `lastUsedAtMs` number
    - `deleted` boolean
  - `audioChunks` UpsertAudioChunkDto[]
    - `bookId` string, required
    - `chapterIndex` number, required
    - `paragraphIndex` number, required
    - `voiceId` string, required
    - `speed` number
    - `sampleRate` number
    - `sentenceSamples` number[]
    - `contentHash` string
    - `deleted` boolean
  - `settings` UpdateSettingsDto
    - `syncEnabled` boolean
    - `settings` object: opaque client settings blob

## Response `201`

---

[API](https://skmtc.dev/ditto/apis/ditto-audio-api.md) · [All operations](https://skmtc.dev/ditto/apis/ditto-audio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ditto/apis/ditto-audio-api/revisions/30c8d7c218da?raw)