Ditto Audio Sync/library API

openapi: 3.2.0
info:
  title: ditto.audio Sync/library API
  description: Cloud API behind ditto.audio. The reader (reader.ditto.audio) and the voice studio (studio.ditto.audio) are separate apps sharing this one backend — see /docs/reader and /docs/inference for each app’s public surface. Third-party integrations want /docs/public (rendered for humans at https://ditto.audio/docs).
  version: '1.0'
  contact: {}
servers: []
tags:
- name: sync/library
  description: Reader cloud sync — books, reading progress, file backup
paths:
  /v1/sync/books:
    get:
      operationId: SyncLibraryController_list
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: List your cloud library (each book annotated with rendered-audio coverage)
      tags:
      - sync/library
  /v1/sync/books/{bookId}:
    get:
      operationId: SyncLibraryController_get
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Get one library book
      tags:
      - sync/library
    put:
      operationId: SyncLibraryController_upsert
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBookDto'
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Add/update a book in your library
      tags:
      - sync/library
    delete:
      operationId: SyncLibraryController_remove
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      security:
      - bearer: []
      summary: Remove a book from your library (+ its cloud file)
      tags:
      - sync/library
  /v1/sync/books/{bookId}/progress:
    get:
      operationId: SyncLibraryController_getProgress
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Get reading progress for a book
      tags:
      - sync/library
    put:
      operationId: SyncLibraryController_putProgress
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertProgressDto'
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Update reading progress for a book
      tags:
      - sync/library
  /v1/sync/books/{bookId}/bookmarks:
    get:
      operationId: SyncLibraryController_bookmarks
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      - name: includeDeleted
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      tags:
      - sync/library
      summary: Sync library controller bookmarks
      x-summary-source: derived
  /v1/sync/books/{bookId}/annotations:
    get:
      operationId: SyncLibraryController_annotations
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      - name: includeDeleted
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      tags:
      - sync/library
      summary: Sync library controller annotations
      x-summary-source: derived
  /v1/sync/books/{bookId}/audio:
    get:
      operationId: SyncLibraryController_audio
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      tags:
      - sync/library
      summary: Sync library controller audio
      x-summary-source: derived
  /v1/sync/books/{bookId}/file/presign:
    post:
      operationId: SyncLibraryController_presignFile
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresignBlobDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Presigned PUT to upload the book file to your cloud
      tags:
      - sync/library
  /v1/sync/books/{bookId}/file/confirm:
    post:
      operationId: SyncLibraryController_confirmFile
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmBlobDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Confirm the upload landed (records size + hash)
      tags:
      - sync/library
  /v1/sync/books/{bookId}/file:
    get:
      operationId: SyncLibraryController_downloadFile
      parameters:
      - name: bookId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Presigned URL to download the cloud book file
      tags:
      - sync/library
components:
  schemas:
    ConfirmBlobDto:
      type: object
      properties:
        s3Key:
          type: string
        contentHash:
          type: string
      required:
      - s3Key
    PresignBlobDto:
      type: object
      properties:
        fileName:
          type: string
          example: mybook.epub
        contentType:
          type: string
        contentHash:
          type: string
      required:
      - fileName
    UpdateBookDto:
      type: object
      properties:
        bookId:
          type: string
          description: client book id (stable across devices)
        title:
          type: string
        author:
          type: string
        format:
          type: string
          example: epub
        chapterCount:
          type: number
        contentHash:
          type: string
          description: sha-256 of the book file
        coverImageUrl:
          type: string
        addedAtMs:
          type: number
          description: client add time, ms epoch
        deleted:
          type: boolean
          description: tombstone — remove from cloud library
    UpsertProgressDto:
      type: object
      properties:
        bookId:
          type: string
        chapterIndex:
          type: number
        paragraphIndex:
          type: number
        cfi:
          type: string
          description: epub.js CFI (web reader)
        percentComplete:
          type: number
          description: 0..1
        totalReadingTimeMs:
          type: number
        lastReadAtMs:
          type: number
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: ditto_sk_live_… API key, ditto_oat_… OAuth access token, or a session JWT
      type: http
      description: An API key (`ditto_sk_live_…`, made at https://ditto.audio/account/api-keys) authenticates /v1/audio/* and /v1/reader/*; an OAuth connection's one-hour access token (`ditto_oat_…`) holds the audio:read and audio:speech scopes only. Account routes (/v1/api-keys, /v1/usage, /v1/subscription) take the signed-in session's token (a JWT) only.