API Reference

Units

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

Prefix /cdna-api/books ReferenceUnit model GuideThe Books module
Units in Postman

List units#

GET /cdna-api/books/book/{parent.id}/units

Lists units. Without limit every match comes back.

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

Parameters

parent.idpathrequired
integer
The book id.
propertiesquery
selector
The fields and relations to return, such as {id,name,slug,position}.
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 units 
GET /cdna-api/books/book/1677/units?limit=2&properties={id,name,slug,position} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "totalCount": 6,
  "data": [
    {
      "id": 1678,
      "name": "The REST API",
      "slug": "rest",
      "position": 1
    },
    {
      "id": 1679,
      "name": "The GraphQL API",
      "slug": "graphql-api",
      "position": 2
    }
  ]
}
Open in Postman docs Real response from this documentation site

Learn more

GuideFilters, ordering and paging FAQMy filter returned every record

Show a unit#

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

Reads one unit by its id.

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

Parameters

idpathrequired
integer
The unit id.
propertiesquery
selector
The fields and relations to return, such as {id,name,slug,position}.

Example

Show a unit 
GET /cdna-api/books/unit/1678?properties={id,name,slug,position} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "data": {
    "id": 1678,
    "name": "The REST API",
    "slug": "rest",
    "position": 1
  }
}
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 unit#

POST /cdna-api/books/unit

Creates a unit.

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

Parameters

bookbody
number
The book, by id.
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 unit 
POST /cdna-api/books/unit HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "book": 7,
  "revisions": {
    "name": "Test Unit from API 68"
  }
}
Response 200 OK 
{
  "result": "success",
  "data": {
    "unit": {
      "pagesCount": 0,
      "book": 7,
      "pages": [],
      "lastRevision": 497,
      "name": "Test Unit from API 16",
      "fullSlug": "/test-from-api-177/test-unit-from-api-16",
      "fullPath": "/test-from-api-177/test-unit-from-api-16",
      "id": 101,
      "slug": "test-unit-from-api-16",
      "publishAt": null
    }
  },
  "message": "The Unit 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 unit#

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

Changes a unit. Fields left out keep their values.

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

Parameters

idpathrequired
integer
The unit id.
customFieldsbody
object
Custom field values by name; the others keep their values.
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 unit 
PUT /cdna-api/books/unit/3 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "customFields": {
    "ancillary": true
  },
  "revisions": {
    "name": "Changed unit title from API 301"
  }
}
Response 200 OK 
{
  "result": "success",
  "data": {
    "unit": {
      "pagesCount": 1,
      "book": 1,
      "pages": [
        2
      ],
      "lastRevision": 498,
      "name": "Changed unit title from API 603",
      "fullSlug": "/test-book/test-unit",
      "fullPath": "/test-book/test-unit",
      "id": 3,
      "slug": "test-unit",
      "publishAt": null
    }
  },
  "message": "The Unit 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 unit#

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

Deletes a unit.

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

Parameters

idpathrequired
integer
The unit id.

Example

Delete a unit 
DELETE /cdna-api/books/unit/50 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "data": [],
  "message": "The Unit 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?

Check that a unit slug is free#

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

Answers {"result":"success"} when no unit 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. Slugs are unique per parent, so parent is required.

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.
parentbodyrequired
integer
The parent the slug must be unique under.
sitebody
integer
The site to check in.

Example

Check that a unit slug is free 
POST /cdna-api/books/units/check-slug HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "slug": "api-sandbox-unit",
  "parent": 1599
}
Response 200 OKFree 
{
  "result": "success"
}
Real response from this documentation site