Management API

Categories

Read, update and delete categories.

Categories sort documents for your readers, like sections of a blog. A category can have a parent, so you can nest them. Its description goes to writers with every brief in it. Create categories with a category intent.

A category has an id, name, slug, description, the parent’s id in categoryId (or null) and its projectId.

Endpoints#

GET/categories

Lists the project’s categories.

curl "https://api.pmkin.io/categories" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"

Response: 200 OK

[
  {
    "categoryId": null,
    "description": "Guides to choosing and running a headless CMS.",
    "id": "6701c3d4e5f6a7b8c9d0e1f2",
    "name": "Headless CMS",
    "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
    "slug": "headless-cms"
  },
  {
    "categoryId": "6701c3d4e5f6a7b8c9d0e1f2",
    "description": "What headless CMS plans cost.",
    "id": "6701c3d4e5f6a7b8c9d0e1f3",
    "name": "Pricing",
    "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
    "slug": "pricing"
  }
]

Get a category#

GET/categories/:id

Returns one category.

Path parameters

idstringrequired: The category’s id.

Errors

NotFound404: No category with this id in the token’s project.

curl "https://api.pmkin.io/categories/6701c3d4e5f6a7b8c9d0e1f2" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"

Response: 200 OK

{
  "categoryId": null,
  "description": "Guides to choosing and running a headless CMS.",
  "id": "6701c3d4e5f6a7b8c9d0e1f2",
  "name": "Headless CMS",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "slug": "headless-cms"
}

Update a category#

PATCH/categories/:id

Replaces the category’s name, slug, description and parent. Send all of them: leaving out categoryId makes the category top-level.

Path parameters

idstringrequired: The category’s id.

Body

namestringrequired: The category’s name.
slugstringrequired: Lowercase letters, numbers and single hyphens, unique in the project.
descriptionstringrequired: What the category covers. Writers get it with each brief.
categoryIdstring: The parent category’s id. Leave it out for a top-level category.

Errors

BadRequest422: The slug is taken, the parent doesn’t exist in this project, or the category would be its own parent.
NotFound404: No category with this id in the token’s project.

curl -X PATCH "https://api.pmkin.io/categories/6701c3d4e5f6a7b8c9d0e1f2" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Guides to choosing and running a headless CMS.",
  "name": "Headless CMS",
  "slug": "headless-cms"
}'

Response: 200 OK

{
  "categoryId": null,
  "description": "Guides to choosing and running a headless CMS.",
  "id": "6701c3d4e5f6a7b8c9d0e1f2",
  "name": "Headless CMS",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "slug": "headless-cms"
}

Delete a category#

DELETE/categories/:id

Deletes the category and returns it. Its documents lose their category and its child categories become top-level.

Path parameters

idstringrequired: The category’s id.

Errors

NotFound404: No category with this id in the token’s project.

curl -X DELETE "https://api.pmkin.io/categories/6701c3d4e5f6a7b8c9d0e1f2" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"

Response: 200 OK

{
  "categoryId": null,
  "description": "Guides to choosing and running a headless CMS.",
  "id": "6701c3d4e5f6a7b8c9d0e1f2",
  "name": "Headless CMS",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "slug": "headless-cms"
}

Endpoints#

List categories#

Get a category#

Update a category#

Delete a category#