API Reference

Categories

The shared category tree that pages, posts and other records are filed under.

Prefix /cdna-api/common ReferenceCategory model GuideTaxonomy, URLs and SEO
Categories in Postman

List categories#

GET /cdna-api/common/categories

Lists categories. Without limit every match comes back.

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

Parameters

propertiesquery
selector
The fields and relations to return, such as {id,name,slug,parent{id}}.
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.

Example

List categories 
GET /cdna-api/common/categories?limit=2&properties={id,name,slug,parent{id}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "totalCount": 19,
  "data": [
    {
      "id": 4,
      "name": "Documentation",
      "slug": "documentation",
      "parent": null
    },
    {
      "id": 13,
      "name": "APIs and JavaScript",
      "slug": "apis-and-javascript",
      "parent": {
        "id": 7
      }
    }
  ]
}
Open in Postman docs Real response from this documentation site

Learn more

GuideFilters, ordering and paging FAQMy filter returned every record

List root categories#

GET /cdna-api/common/categories

Lists the categories at the top of the tree. An empty relation is filtered with the bare key and NULL: parent=NULL.

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

Parameters

propertiesquery
selector
The fields and relations to return, such as {id,name,slug,parent{id}}.
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.

Example

List root categories 
GET /cdna-api/common/categories?parent=NULL&limit=2&properties={id,name,slug,parent{id}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "totalCount": 5,
  "data": [
    {
      "id": 1,
      "name": "Test Category",
      "slug": "test-category",
      "parent": null
    },
    {
      "id": 4,
      "name": "Documentation",
      "slug": "documentation",
      "parent": null
    }
  ]
}
Open in Postman docs Real response from this documentation site

Learn more

GuideFilters, ordering and paging FAQMy filter returned every record

Show a category#

GET /cdna-api/common/category/{id}

Reads one category by its id.

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

Parameters

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

Example

Show a category 
GET /cdna-api/common/category/13?properties={id,name,slug,parent{id}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "data": {
    "id": 13,
    "name": "APIs and JavaScript",
    "slug": "apis-and-javascript",
    "parent": {
      "id": 7
    }
  }
}
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 category#

POST /cdna-api/common/category

Creates a category.

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

Parameters

parentbody
number
The parent record, by id.
namebody
string
The name.

Example

Create a category 
POST /cdna-api/common/category HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "parent": 9,
  "name": "New category from API"
}
Response 200 OK 
{
  "result": "success",
  "data": {
    "category": {
      "id": 633,
      "name": "New category from API",
      "slug": "new-category-from-api",
      "created": "2020-03-11T01:28:31+00:00",
      "modified": "2020-03-11T01:28:31+00:00",
      "parent": 9,
      "children": []
    }
  },
  "message": "The Category has been added successfully."
}
Open in Postman docs Saved response from the Postman collection

Learn more

How-toImport records so that running the import twice changes nothing FAQ"Could not find the referenced record with id 0"

Edit a category#

PUT /cdna-api/common/category/{id}

Changes a category. Fields left out keep their values.

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

Parameters

idpathrequired
integer
The category id.
namebody
string
The name.

Example

Edit a category 
PUT /cdna-api/common/category/633 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "name": "Changed category from API"
}
Response 200 OK 
{
  "result": "success",
  "data": {
    "category": {
      "id": 633,
      "name": "Changed category from API",
      "slug": "new-category-from-api",
      "created": "2020-03-11T01:28:31+00:00",
      "modified": "2020-03-11T01:29:56+00:00",
      "parent": 9,
      "children": []
    }
  },
  "message": "The Category has been saved successfully."
}
Open in Postman docs Saved response from the Postman collection

Learn more

FAQ"Could not find the referenced record with id 0"

Delete a category#

DELETE /cdna-api/common/category/{id}

Deletes a category.

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

Parameters

idpathrequired
integer
The category id.

Example

Delete a category 
DELETE /cdna-api/common/category/633 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "data": [],
  "message": "The Category 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 category slug is free#

POST /cdna-api/common/check-category-slug

Answers {"result":"success"} when no category 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 category slug is free 
POST /cdna-api/common/check-category-slug HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "slug": "api-sandbox-category"
}
Response 200 OKFree 
{
  "result": "success"
}
Real response from this documentation site