Books

Books, their units and pages, and a book’s PDF export.

Prefix /cdna-api/books ReferenceBook model GuideThe Books module

About books

A book is a three-level tree: the book holds units, and a unit holds pages. All three share the Pages module’s storage, so each keeps its content in revisions and renders through its layout’s areas.

Hierarchy Three levels

Book, unit and page. Units and pages have their own routes and pages here.

The Books module

Revisions Yes

Book, unit and page each keep their content in revisions.

Revisions, publishing and approval

Custom URLs No

Books have no custom URLs; their path is the chain of slugs.

Taxonomy, URLs and SEO

Custom fields Yes

Books, units and pages take custom fields.

Custom fields

PDF export Yes

A book can be exported as a PDF; the export runs in the background and its state can be read.

The Books module

Key fields

id: integer; The book id.
name: string; The live revision's name.
slug: string; The book's path segment.
unitsCount, pagesCount: integer; How many units and pages the book holds. Computed.
children: Unit[]; The book's units.
activeRevision: Revision; The live revision.
published: datetime; When the book went, or goes, public.

Learn more

GuideThe Books module GuideRevisions, publishing and approval ReferenceBook model

List books#

GET /cdna-api/books/books

Lists books. Without limit every match comes back.

Access: Admin users and integrations, with an OAuth access token or an API key.
Model: Book, in the Reference

Parameters

propertiesquery: selector; The fields and relations to return, such as {id,name,slug,unitsCount,pagesCount}.
filtersquery: name=value; Any stored field, or a relation with a dot, such as parent.id=12. Prefix the name with !, >, <, % or |. Use stored field names exactly as in the model, and compare totalCount with the unfiltered list's to confirm a filter applied.
orderByquery: string; field:ASC or field:DESC, comma-separated. Stored fields only.
limitquery: integer; Records per response. There is no default.
offsetquery: integer; Records to skip.
retrieveUnpublishedquery: 1; Include unpublished records.

Example

List books

GET /cdna-api/books/books?limit=2&properties={id,name,slug,unitsCount,pagesCount} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "totalCount": 15,
  "data": [
    {
      "id": 1677,
      "name": "The APIs: REST, GraphQL and custom endpoints",
      "slug": "apis",
      "unitsCount": 6,
      "pagesCount": 6
    },
    {
      "id": 1590,
      "name": "Choosing how to build",
      "slug": "choosing-how-to-build",
      "unitsCount": 4,
      "pagesCount": 4
    }
  ]
}

Open in Postman docs Real response from this documentation site

Learn more

GuideFilters, ordering and paging FAQMy filter returned every record

Show a book#

GET /cdna-api/books/book/{id}

Reads one book by its id.

Access: Admin users and integrations, with an OAuth access token or an API key.
Model: Book, in the Reference

Parameters

idpathrequired: integer; The book id.
propertiesquery: selector; The fields and relations to return, such as {id,name,slug,unitsCount,pagesCount}.

Example

Show a book

GET /cdna-api/books/book/1677?properties={id,name,slug,unitsCount,pagesCount} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": {
    "id": 1677,
    "name": "The APIs: REST, GraphQL and custom endpoints",
    "slug": "apis",
    "unitsCount": 6,
    "pagesCount": 6
  }
}

Open in Postman docs Real response from this documentation site

Learn more

GuideShaping the response with properties FAQMy properties fields come back as "Error: Getter for property … not found", or glued together

Read a book’s PDF export state#

GET /cdna-api/books/book/{id}

Reads the state of the book’s PDF export through the regular show route. exportPdfStatus is generate_pdfs, merging, success, error, or null when no export has run; exportPdfPath is the finished file. Postman’s older exportStatus is no longer a field.

Access: Admin users and integrations, with an OAuth access token or an API key.
Model: Book, in the Reference

Parameters

idpathrequired: integer; The book id.
propertiesquery: selector; The fields and relations to return, such as {id,exportPdfStatus,exportPdfPath,exportPdfDate}.

Example

Read a book’s PDF export state

GET /cdna-api/books/book/1677?properties={id,exportPdfStatus,exportPdfPath,exportPdfDate} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": {
    "id": 1677,
    "exportPdfStatus": "",
    "exportPdfPath": null,
    "exportPdfDate": null
  }
}

Open in Postman docs Real response from this documentation site

Learn more

GuideShaping the response with properties FAQMy properties fields come back as "Error: Getter for property … not found", or glued together

Create a book#

POST /cdna-api/books/book

Creates a book.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

revisionsbody: object; A new revision: name, layout and areas, or text for a record with a body. Areas left out are empty.

Example

Create a book

POST /cdna-api/books/book HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "revisions": {
    "name": "Test from API 208"
  }
}

Response 200 OK

{
  "result": "success",
  "data": {
    "book": {
      "unitsCount": 0,
      "pagesCount": 0,
      "units": [],
      "lastRevision": 494,
      "name": "Test from API 342",
      "fullSlug": "/test-from-api-342",
      "fullPath": "/test-from-api-342",
      "id": 100,
      "slug": "test-from-api-342",
      "publishAt": null
    }
  },
  "message": "The Book has been added successfully."
}

Open in Postman docs Saved response from the Postman collection, shortened

Learn more

GuidepatchRevision, revisions, or a revision by id How-toImport records so that running the import twice changes nothing FAQ"Could not find the referenced record with id 0"

Edit a book#

PUT /cdna-api/books/book/{id}

Changes a book. Fields left out keep their values.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

idpathrequired: integer; The book id.
revisionsbody: object; A new revision: name, layout and areas, or text for a record with a body. Areas left out are empty.

A revisions object makes a new revision that is not live unless the request also sends "activeRevision": true, and it holds only the areas sent. To change some areas and keep the rest, use patchRevision with originRevision.

Example

Edit a book

PUT /cdna-api/books/book/1 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "revisions": {
    "name": "Changed book title from API 435"
  }
}

Response 200 OK

{
  "result": "success",
  "data": {
    "book": {
      "unitsCount": 4,
      "pagesCount": 1,
      "units": [
        3,
        32
      ],
      "lastRevision": 496,
      "name": "Changed book title from API 312",
      "fullSlug": "/test-book",
      "fullPath": "/test-book",
      "id": 1,
      "slug": "test-book",
      "publishAt": null
    }
  },
  "message": "The Book has been saved successfully."
}

Open in Postman docs Saved response from the Postman collection, shortened

Learn more

GuideRevisions, publishing and approval ReferenceCollection operations GuidepatchRevision, revisions, or a revision by id GuideWriting areas How-toChange one area of a page without touching the rest FAQMy edit saved, but the site did not change FAQUpdating one area emptied the others

Delete a book#

DELETE /cdna-api/books/book/{id}

Deletes a book.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

idpathrequired: integer; The book id.

Example

Delete a book

DELETE /cdna-api/books/book/53 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": [],
  "message": "The Book has successfully been deleted."
}

Open in Postman docs Saved response from the Postman collection

Learn more

GuideRetries and writes that may have applied FAQMy DELETE timed out: did it go through?

Duplicate a book#

POST /cdna-api/books/duplicate-book/{id}

Copies a book. The copy is unpublished.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

idpathrequired: integer; The book id.

Example

Duplicate a book

POST /cdna-api/books/duplicate-book/24365?properties={id,units} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": {
    "book": {
      "id": 24428,
      "units": [
        24429
      ]
    }
  },
  "message": "The Book has successfully been duplicated."
}

Open in Postman docs Saved response from the Postman collection

Export a book as a PDF#

POST /cdna-api/books/export-book-pdf/{id}

Starts a PDF export of the book. The export runs in the background; read its progress from the book’s exportPdfStatus. The saved response below predates the field’s rename and shows it as exportStatus.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

idpathrequired: integer; The book id.

Example

Export a book as a PDF

POST /cdna-api/books/export-book-pdf/24365?properties={id,exportPdfStatus,exportPdfPath} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": {
    "book": {
      "id": 24365,
      "exportStatus": "generate_pdfs",
      "exportPdfPath": null
    }
  },
  "message": "The export of the book PDF has been started. Once the export is completed, it will be attached to the book."
}

Open in Postman docs Saved response from the Postman collection

Check that a book slug is free#

POST /cdna-api/books/books/check-slug

Answers {"result":"success"} when no book uses the slug. A slug in use, or one with characters a slug cannot have, answers HTTP 200 too, with "result": "error" and a message.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

slugbodyrequired: string; The slug to check.
idbody: integer; A record to leave out of the check, when renaming it.
sitebody: integer; The site to check in.

Example

Check that a book slug is free

POST /cdna-api/books/books/check-slug HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "slug": "start-here"
}

Response 200 OKIn use

{
  "result": "error",
  "message": "A record with this slug already exists"
}

Real response from this documentation site

In Books

Units6 endpoints

Units, the middle level of a book: a book holds units, and a unit holds pages.

Pages7 endpoints

Book pages, the leaf level of a book.