API conventions

Response envelopes

Resource fields describe the cardinality of a successful response. Operation-specific output is kept separate from resource data.

{
  "items": [
    {
      "id": "pub_123"
    }
  ],
  "nextToken": null,
  "context": {
    "path": "/v1/publications",
    "method": "GET",
    "requestId": "req_123",
    "authentication": {
      "sub": "user_123",
      "scopeId": "scope_123"
    }
  }
}

{
  "item": {
    "id": "pub_123"
  },
  "context": {
    "path": "/v1/publications/pub_123",
    "method": "GET",
    "requestId": "req_123",
    "authentication": {
      "sub": "user_123",
      "scopeId": "scope_123"
    }
  }
}

{
  "item": {
    "id": "pub_123"
  },
  "result": {
    "objectKey": "publications/pub_123/book.epub",
    "uploadUrl": "https://example.com/upload"
  },
  "context": {
    "path": "/v1/publications",
    "method": "POST",
    "requestId": "req_123",
    "authentication": {
      "sub": "user_123",
      "scopeId": "scope_123"
    }
  }
}

Names and values

Field types

JSON types are significant and clients should not coerce fields based on their names or contents. In particular:

Pagination

The endpoints below use cursor pagination. Send the response's nextToken unchanged as the nextToken query parameter in the next request. A null value means there are no more pages. Clients must not inspect, modify, or persist a token as a permanent cursor.

The limit parameter accepts an integer from 1 to 50. Other list endpoints are not currently paginated and return their complete result set.

GET /v1/publications?limit=10&nextToken=TOKEN_FROM_PREVIOUS_RESPONSE

Uploads and processing

Publication and asset creation return short-lived presigned S3 upload sessions. Upload each file with an HTTP PUT to uploadUrl, copying every entry in requiredHeaders exactly. The URL expires after the number of seconds in expiresIn.

await fetch(uploadSession.uploadUrl, {
  method: 'PUT',
  headers: uploadSession.requiredHeaders,
  body: file
})

Publication upload statuses

Poll the publication or edition resource until uploadStatus reaches a terminal value. The create request must include the correct edition.type: EPUB, PDF, or Audio. LPF audiobook packages use Audio.

Errors

Error responses use error for a machine-readable code and message for a human-readable explanation. The request ID is context.requestId; it is not a top-level field. Use the HTTP status and error code for client control flow, and include the request ID when reporting an error. Do not match message text.

details is present on validation error responses, including ZOD_ERROR. The path and code fields on an individual detail are optional. Errors raised before authentication completes can return a context without authentication.

{
  "error": "ZOD_ERROR",
  "message": "Invalid payload sent to API",
  "context": {
    "path": "/v1/publications",
    "method": "POST",
    "requestId": "req_123",
    "authentication": {
      "sub": "user_123",
      "scopeId": "scope_123"
    }
  },
  "details": [
    {
      "message": "Expected string, received number",
      "path": [
        "edition",
        "title"
      ],
      "code": "invalid_type"
    },
    {
      "message": "Expected string, received null",
      "path": [
        "collectionIds",
        0
      ],
      "code": "invalid_type"
    }
  ]
}