Colibrio Cirrus

Publications

GET/v1/publicationsGet all publications.

Parameters

Name	Type	Description	Required
limit	integer	Maximum number of resources to return. Must be between 1 and 50.	No
nextToken	string	Opaque continuation token returned by the previous page.	No
search	string	Querystring parameter.	No
collectionId	string	Querystring parameter.	No
statuses	string	Querystring parameter.	No
formats	string	Querystring parameter.	No
sortBy	string	Querystring parameter.	No
sortDirection	string	Querystring parameter.	No

Request Body Fields

Name	Type	Options	Required
limit	number	Any	No
nextToken	string	Any	No
search	string	Any	No
collectionId	string	Any	No
statuses	enum[]	draftlive	No
formats	enum[]	epub-reflowableepub-fixedpdfaudio	No
sortBy	enum	titleauthorcreatedAtIso	No
sortDirection	enum	ascdesc	No

curl -X GET "https://api.cirrusreader.com/v1/publications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Body Fields

Name	Type	Options	Required
items	object[]	Any	Yes
defaultPublicationId	string	Any	Yes
stats	object	Any	No
nextToken	string	Any	No
context	object	Any	Yes

Response 200

Publications were fetched successfully.

{
  "items": [
    {
      "title": "string",
      "author": [
        "string"
      ],
      "type": "EPUB",
      "isReflowable": true,
      "status": "draft",
      "uploadStatus": "upload_pending",
      "currentEditionId": "string",
      "publicationId": "string",
      "cover": "string",
      "createdAtIso": "2026-04-29T10:00:00.000Z",
      "collectionIds": [
        "string"
      ]
    }
  ],
  "defaultPublicationId": "string",
  "stats": {
    "publicationCount": 1,
    "publicationEditionCount": 1,
    "months": {
      "key": "value"
    }
  },
  "nextToken": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

POST/v1/publication-uploadsCreate an upload intent for a publication or publication edition.

Request Body Fields

Name	Type	Options	Required
uploadRequestId	uuid	Any	Yes
publicationFilename	string	Any	Yes
coverFilename	string	Any	No
publicationType	enum	EPUBPDFAudio	Yes

curl -X POST "https://api.cirrusreader.com/v1/publication-uploads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "uploadRequestId": "00000000-0000-4000-8000-000000000000",
  "publicationFilename": "string",
  "publicationType": "EPUB"
}'

Request Body

application/json

{
  "uploadRequestId": "00000000-0000-4000-8000-000000000000",
  "publicationFilename": "string",
  "publicationType": "EPUB"
}

Response Body Fields

Name	Type	Options	Required
result	object	Any	Yes
context	object	Any	Yes

Response 201

The publication upload intent was created successfully.

{
  "result": {
    "uploadRequestId": "00000000-0000-4000-8000-000000000000",
    "uploadMode": "single",
    "cover": {
      "objectKey": "string",
      "uploadUrl": "string",
      "expiresIn": 1,
      "requiredHeaders": {
        "Content-Type": "string"
      }
    },
    "objectKey": "string",
    "uploadUrl": "string",
    "expiresIn": 1,
    "requiredHeaders": {
      "Content-Type": "string"
    }
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 500

The request body or parameters failed validation.

{
  "error": "DB_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

POST/v1/publicationsCreate a publication and upload session.

Request Body Fields

Name	Type	Options	Required
language	string \| enum	EnglishFrenchGermanItalianSpanish	No
description	string	Any	No
sampleItems	string[]	Any	No
isForInternalReadingInstance	boolean	Any	No
uploadRequestId	uuid	Any	Yes
publicationFilename	string	Any	Yes
coverFilename	string	Any	No
collectionIds	string[]	Any	No
edition	object	Any	Yes

curl -X POST "https://api.cirrusreader.com/v1/publications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "uploadRequestId": "00000000-0000-4000-8000-000000000000",
  "publicationFilename": "string",
  "edition": {
    "title": "string",
    "author": [
      "string"
    ],
    "metadata": {},
    "type": "EPUB"
  }
}'

Request Body

application/json

{
  "uploadRequestId": "00000000-0000-4000-8000-000000000000",
  "publicationFilename": "string",
  "edition": {
    "title": "string",
    "author": [
      "string"
    ],
    "metadata": {},
    "type": "EPUB"
  }
}

Response Body Fields

Name	Type	Options	Required
item	object	Any	Yes
context	object	Any	Yes

Response 201

The publication upload session was created successfully.

{
  "item": {
    "id": "string",
    "language": "string",
    "description": "string",
    "sampleItems": [
      "string"
    ],
    "isForInternalReadingInstance": true,
    "editions": [
      {
        "id": "string",
        "type": "EPUB",
        "isReflowable": true,
        "editionCreated": "2026-04-29T10:00:00.000Z",
        "title": "string",
        "titleSource": "user",
        "author": [
          "string"
        ],
        "version": 1,
        "isCurrentVersion": true,
        "status": "draft",
        "editionNotes": "string",
        "key": "string",
        "uploadStatus": "upload_pending",
        "metadata": {
          "pageCount": "string",
          "fileSize": "string",
          "epubVersion": "string",
          "spreadBehaviour": "AUTO",
          "layoutType": "REFLOWABLE",
          "cover": "string",
          "coverImageAlt": "string",
          "isbn": "string",
          "publisher": "string"
        },
        "navigationData": [
          {
            "collectionType": "TOC",
            "collectionIndex": 1,
            "navigationItemId": 1,
            "title": "string",
            "depth": 1,
            "path": [
              1
            ],
            "pathKey": "string"
          }
        ]
      }
    ]
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 500

The request body or parameters failed validation.

{
  "error": "DB_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

GET/v1/publications/{id}Get publication by id

Parameters

Name	Type	Description	Required
id	string	Path parameter.	Yes

Request Body Fields

Name	Type	Options	Required
id	string	Any	Yes

curl -X GET "https://api.cirrusreader.com/v1/publications/ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Body Fields

Name	Type	Options	Required
item	object	Any	Yes
context	object	Any	Yes

Response 200

Publication fetched successfully.

{
  "item": {
    "id": "string",
    "language": "string",
    "description": "string",
    "sampleItems": [
      "string"
    ],
    "isForInternalReadingInstance": true,
    "editions": [
      {
        "id": "string",
        "type": "EPUB",
        "isReflowable": true,
        "editionCreated": "2026-04-29T10:00:00.000Z",
        "title": "string",
        "titleSource": "user",
        "author": [
          "string"
        ],
        "version": 1,
        "isCurrentVersion": true,
        "status": "draft",
        "editionNotes": "string",
        "key": "string",
        "uploadStatus": "upload_pending",
        "metadata": {
          "pageCount": "string",
          "fileSize": "string",
          "epubVersion": "string",
          "spreadBehaviour": "AUTO",
          "layoutType": "REFLOWABLE",
          "cover": "string",
          "coverImageAlt": "string",
          "isbn": "string",
          "publisher": "string"
        },
        "navigationData": [
          {
            "collectionType": "TOC",
            "collectionIndex": 1,
            "navigationItemId": 1,
            "title": "string",
            "depth": 1,
            "path": [
              1
            ],
            "pathKey": "string"
          }
        ]
      }
    ]
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 404

The requested API key could not be found.

{
  "error": "EMPTY_RESPONSE",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

PATCH/v1/publications/{id}Update a publication.

Parameters

Name	Type	Description	Required
id	string	Path parameter.	Yes

Request Body Fields

Name	Type	Options	Required
language	string \| enum	EnglishFrenchGermanItalianSpanish	No
description	string	Any	No
sampleItems	string[]	Any	No
isForInternalReadingInstance	boolean	Any	No

curl -X PATCH "https://api.cirrusreader.com/v1/publications/ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Body Fields

Name	Type	Options	Required
item	object	Any	Yes
context	object	Any	Yes

Response 200

The publication was updated successfully.

{
  "item": {
    "id": "string",
    "language": "string",
    "description": "string",
    "sampleItems": [
      "string"
    ],
    "isForInternalReadingInstance": true,
    "editions": [
      {
        "id": "string",
        "type": "EPUB",
        "isReflowable": true,
        "editionCreated": "2026-04-29T10:00:00.000Z",
        "title": "string",
        "titleSource": "user",
        "author": [
          "string"
        ],
        "version": 1,
        "isCurrentVersion": true,
        "status": "draft",
        "editionNotes": "string",
        "key": "string",
        "uploadStatus": "upload_pending",
        "metadata": {
          "pageCount": "string",
          "fileSize": "string",
          "epubVersion": "string",
          "spreadBehaviour": "AUTO",
          "layoutType": "REFLOWABLE",
          "cover": "string",
          "coverImageAlt": "string",
          "isbn": "string",
          "publisher": "string"
        },
        "navigationData": [
          {
            "collectionType": "TOC",
            "collectionIndex": 1,
            "navigationItemId": 1,
            "title": "string",
            "depth": 1,
            "path": [
              1
            ],
            "pathKey": "string"
          }
        ]
      }
    ]
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 500

The request body or parameters failed validation.

{
  "error": "DB_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

DELETE/v1/publications/{id}Delete publication by id

Parameters

Name	Type	Description	Required
id	string	Path parameter.	Yes

curl -X DELETE "https://api.cirrusreader.com/v1/publications/ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Body Fields

Name	Type	Options	Required
item	object	Any	Yes
context	object	Any	Yes

Response 200

Publication deleted successfully.

{
  "item": {
    "id": "string",
    "language": "string",
    "description": "string",
    "sampleItems": [
      "string"
    ],
    "isForInternalReadingInstance": true,
    "editions": [
      {
        "id": "string",
        "type": "EPUB",
        "isReflowable": true,
        "editionCreated": "2026-04-29T10:00:00.000Z",
        "title": "string",
        "titleSource": "user",
        "author": [
          "string"
        ],
        "version": 1,
        "isCurrentVersion": true,
        "status": "draft",
        "editionNotes": "string",
        "key": "string",
        "uploadStatus": "upload_pending",
        "metadata": {
          "pageCount": "string",
          "fileSize": "string",
          "epubVersion": "string",
          "spreadBehaviour": "AUTO",
          "layoutType": "REFLOWABLE",
          "cover": "string",
          "coverImageAlt": "string",
          "isbn": "string",
          "publisher": "string"
        },
        "navigationData": [
          {
            "collectionType": "TOC",
            "collectionIndex": 1,
            "navigationItemId": 1,
            "title": "string",
            "depth": 1,
            "path": [
              1
            ],
            "pathKey": "string"
          }
        ]
      }
    ]
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 404

The requested API key could not be found.

{
  "error": "EMPTY_RESPONSE",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

GET/v1/publications/{id}/editionsGet all editions for a publication.

Parameters

Name	Type	Description	Required
id	string	Path parameter.	Yes

Request Body Fields

Name	Type	Options	Required
id	string	Any	Yes

curl -X GET "https://api.cirrusreader.com/v1/publications/ID/editions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Body Fields

Name	Type	Options	Required
items	object[]	Any	Yes
context	object	Any	Yes

Response 200

Publication editions fetched successfully.

{
  "items": [
    {
      "id": "string",
      "type": "EPUB",
      "isReflowable": true,
      "editionCreated": "2026-04-29T10:00:00.000Z",
      "title": "string",
      "titleSource": "user",
      "author": [
        "string"
      ],
      "version": 1,
      "isCurrentVersion": true,
      "status": "draft",
      "editionNotes": "string",
      "key": "string",
      "uploadStatus": "upload_pending",
      "metadata": {
        "pageCount": "string",
        "fileSize": "string",
        "epubVersion": "string",
        "spreadBehaviour": "AUTO",
        "layoutType": "REFLOWABLE",
        "cover": "string",
        "coverImageAlt": "string",
        "isbn": "string",
        "publisher": "string"
      },
      "navigationData": [
        {
          "collectionType": "TOC",
          "collectionIndex": 1,
          "navigationItemId": 1,
          "title": "string",
          "depth": 1,
          "path": [
            1
          ],
          "pathKey": "string"
        }
      ]
    }
  ],
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

POST/v1/publications/{id}/editionsCreate an edition for a publication and upload session.

Parameters

Name	Type	Description	Required
id	string	Path parameter.	Yes

Request Body Fields

Name	Type	Options	Required
language	string \| enum	EnglishFrenchGermanItalianSpanish	No
description	string	Any	No
sampleItems	string[]	Any	No
isForInternalReadingInstance	boolean	Any	No
uploadRequestId	uuid	Any	Yes
publicationFilename	string	Any	Yes
coverFilename	string	Any	No
collectionIds	string[]	Any	No
edition	object	Any	Yes

curl -X POST "https://api.cirrusreader.com/v1/publications/ID/editions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "uploadRequestId": "00000000-0000-4000-8000-000000000000",
  "publicationFilename": "string",
  "edition": {
    "title": "string",
    "author": [
      "string"
    ],
    "metadata": {},
    "type": "EPUB"
  }
}'

Request Body

application/json

{
  "uploadRequestId": "00000000-0000-4000-8000-000000000000",
  "publicationFilename": "string",
  "edition": {
    "title": "string",
    "author": [
      "string"
    ],
    "metadata": {},
    "type": "EPUB"
  }
}

Response Body Fields

Name	Type	Options	Required
item	object	Any	Yes
context	object	Any	Yes

Response 201

The publication edition upload session was created successfully.

{
  "item": {
    "id": "string",
    "language": "string",
    "description": "string",
    "sampleItems": [
      "string"
    ],
    "isForInternalReadingInstance": true,
    "editions": [
      {
        "id": "string",
        "type": "EPUB",
        "isReflowable": true,
        "editionCreated": "2026-04-29T10:00:00.000Z",
        "title": "string",
        "titleSource": "user",
        "author": [
          "string"
        ],
        "version": 1,
        "isCurrentVersion": true,
        "status": "draft",
        "editionNotes": "string",
        "key": "string",
        "uploadStatus": "upload_pending",
        "metadata": {
          "pageCount": "string",
          "fileSize": "string",
          "epubVersion": "string",
          "spreadBehaviour": "AUTO",
          "layoutType": "REFLOWABLE",
          "cover": "string",
          "coverImageAlt": "string",
          "isbn": "string",
          "publisher": "string"
        },
        "navigationData": [
          {
            "collectionType": "TOC",
            "collectionIndex": 1,
            "navigationItemId": 1,
            "title": "string",
            "depth": 1,
            "path": [
              1
            ],
            "pathKey": "string"
          }
        ]
      }
    ]
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 500

The request body or parameters failed validation.

{
  "error": "DB_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

GET/v1/publications/{id}/editions/{editionid}Get edition by ID for a publication.

Parameters

Name	Type	Description	Required
id	string	Path parameter.	Yes
editionid	string	Path parameter.	Yes

curl -X GET "https://api.cirrusreader.com/v1/publications/ID/editions/EDITIONID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Body Fields

Name	Type	Options	Required
item	object	Any	Yes
context	object	Any	Yes

Response 200

Publication edition fetched successfully.

{
  "item": {
    "id": "string",
    "type": "EPUB",
    "isReflowable": true,
    "editionCreated": "2026-04-29T10:00:00.000Z",
    "title": "string",
    "titleSource": "user",
    "author": [
      "string"
    ],
    "version": 1,
    "isCurrentVersion": true,
    "status": "draft",
    "editionNotes": "string",
    "key": "string",
    "uploadStatus": "upload_pending",
    "metadata": {
      "pageCount": "string",
      "fileSize": "string",
      "epubVersion": "string",
      "spreadBehaviour": "AUTO",
      "layoutType": "REFLOWABLE",
      "cover": "string",
      "coverImageAlt": "string",
      "isbn": "string",
      "publisher": "string"
    },
    "navigationData": [
      {
        "collectionType": "TOC",
        "collectionIndex": 1,
        "navigationItemId": 1,
        "title": "string",
        "depth": 1,
        "path": [
          1
        ],
        "pathKey": "string"
      }
    ]
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

PATCH/v1/publications/{id}/editions/{editionid}Update an edition for a publication.

Parameters

Name	Type	Description	Required
id	string	Path parameter.	Yes
editionid	string	Path parameter.	Yes

Request Body Fields

Name	Type	Options	Required
isReflowable	boolean	Any	No
title	string	Any	No
author	string[]	Any	No
status	enum	draftlive	No
isCurrentVersion	boolean	Any	No
editionNotes	string	Any	No
metadata	object	Any	No
coverFilename	string	Any	No

curl -X PATCH "https://api.cirrusreader.com/v1/publications/ID/editions/EDITIONID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Body Fields

Name	Type	Options	Required
item	object	Any	Yes
result	object	Any	No
context	object	Any	Yes

Response 200

Publication editions fetched successfully.

{
  "item": {
    "id": "string",
    "type": "EPUB",
    "isReflowable": true,
    "editionCreated": "2026-04-29T10:00:00.000Z",
    "title": "string",
    "titleSource": "user",
    "author": [
      "string"
    ],
    "version": 1,
    "isCurrentVersion": true,
    "status": "draft",
    "editionNotes": "string",
    "key": "string",
    "uploadStatus": "upload_pending",
    "metadata": {
      "pageCount": "string",
      "fileSize": "string",
      "epubVersion": "string",
      "spreadBehaviour": "AUTO",
      "layoutType": "REFLOWABLE",
      "cover": "string",
      "coverImageAlt": "string",
      "isbn": "string",
      "publisher": "string"
    },
    "navigationData": [
      {
        "collectionType": "TOC",
        "collectionIndex": 1,
        "navigationItemId": 1,
        "title": "string",
        "depth": 1,
        "path": [
          1
        ],
        "pathKey": "string"
      }
    ]
  },
  "result": {
    "cover": {
      "objectKey": "string",
      "uploadUrl": "string",
      "expiresIn": 1,
      "requiredHeaders": {
        "Content-Type": "string"
      }
    }
  },
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 500

The request body or parameters failed validation.

{
  "error": "DB_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

POST/v1/publications/bulkPerform a batch operation for Publications.

Request Body Fields

Name	Type	Options	Required
operation	"deletePublications" \| "createPublications"	deletePublicationscreatePublications	Yes
params	object	Any	Yes

curl -X POST "https://api.cirrusreader.com/v1/publications/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "deletePublications",
  "params": {
    "publicationIds": [
      "string"
    ]
  }
}'

Request Body

application/json

{
  "operation": "deletePublications",
  "params": {
    "publicationIds": [
      "string"
    ]
  }
}

Response Body Fields

Name	Type	Options	Required
status	enum	okfail	Yes
context	object	Any	Yes

Response 201

The batch operation completed successfully.

{
  "status": "ok",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string",
    "authentication": {
      "requestId": "string",
      "authType": "apiKey",
      "sub": "string",
      "email": "string",
      "groups": "string",
      "keyId": "string",
      "organisationId": "string",
      "errorCode": "string",
      "error": "string",
      "user": {
        "id": "string",
        "sub": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "role": "Admin",
        "status": "Active",
        "onboarded": true,
        "userImage": "string",
        "billing": {
          "planId": "starter",
          "status": "incomplete",
          "billingAccessStatus": "enabled",
          "billingGracePeriodEndIso": "2026-04-29T10:00:00.000Z",
          "billingInterval": "month",
          "trialEndIso": "2026-04-29T10:00:00.000Z",
          "currentPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "cancelAtPeriodEnd": true,
          "publicationLimit": 1,
          "monthlyBandwidthLimitBytes": "string",
          "bandwidthPeriodStartIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodEndIso": "2026-04-29T10:00:00.000Z",
          "bandwidthPeriodUsedBytes": "string",
          "bandwidthPeriodCalculatedThroughIso": "2026-04-29T10:00:00.000Z",
          "bandwidthAccessStatus": "enabled"
        }
      },
      "scopeId": "string"
    }
  }
}

Error Responses

Response 400

The request body or parameters failed validation.

{
  "error": "QL_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  },
  "details": [
    {
      "message": "string"
    }
  ]
}

Response 401

The request is missing valid authentication credentials.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 403

The authenticated user is not allowed to access this resource.

{
  "error": "AUTHENTICATION_ERROR",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}

Response 405

The request method is not supported.

{
  "error": "UNSUPPORTED_METHOD",
  "message": "string",
  "context": {
    "path": "string",
    "method": "string",
    "requestId": "string"
  }
}