Management API

Clusters

Group documents into topic clusters and track progress.

A topic cluster groups the documents that cover one subject, such as a pillar page and the articles around it. Clusters track how much of the topic is published, so you can see what’s missing. Create clusters with a cluster intent, and add documents to one by setting their clusterId.

Limits#

A project can have at most 200 clusters.
A name can be at most 100 characters and must be unique in the project, ignoring case.
A description can be at most 2,000 characters.
A cluster can have at most 50 keywords of 100 characters each.

Endpoints#

List clusters#

GET/clusters

Lists the project’s clusters by name, each with progress: how many of its documents are published, of how many.

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

Response: 200 OK

[
  {
    "createdAt": "2026-10-01T08:00:00.000Z",
    "description": "Everything a buyer asks before choosing a headless CMS.",
    "id": "6702d4e5f6a7b8c9d0e1f2a3",
    "keywords": [
      "headless cms",
      "headless cms pricing"
    ],
    "name": "Headless CMS",
    "progress": {
      "published": 3,
      "total": 8
    },
    "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
    "updatedAt": "2026-10-05T14:30:00.000Z"
  }
]

Get a cluster#

GET/clusters/:id

Returns the cluster with its progress and its documents (id, title, status and slug each, at most 200), so you can see what the topic covers and what’s missing.

Path parameters

idstringrequired: The cluster’s id.

Errors

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

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

Response: 200 OK

{
  "createdAt": "2026-10-01T08:00:00.000Z",
  "description": "Everything a buyer asks before choosing a headless CMS.",
  "id": "6702d4e5f6a7b8c9d0e1f2a3",
  "keywords": [
    "headless cms",
    "headless cms pricing"
  ],
  "name": "Headless CMS",
  "progress": {
    "published": 3,
    "total": 8
  },
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "updatedAt": "2026-10-05T14:30:00.000Z",
  "documents": [
    {
      "id": "6704a1f0c2b3d4e5f6a7b8c9",
      "slug": "headless-cms-pricing",
      "status": "drafting",
      "title": "Headless CMS pricing"
    },
    {
      "id": "66fe91a2b3c4d5e6f7a8b9c0",
      "slug": "what-is-a-headless-cms",
      "status": "published",
      "title": "What is a headless CMS?"
    }
  ]
}

Update a cluster#

PATCH/clusters/:id

Changes the fields you send.

Path parameters

idstringrequired: The cluster’s id.

Body

namestring: At most 100 characters, unique in the project ignoring case.
descriptionstring | null: What the topic covers. At most 2,000 characters. null clears it.
keywordsstring[] | null: Keywords the topic targets. At most 50, each at most 100 characters. null clears them.

Errors

BadRequest422: The name is empty, too long or taken, or the description or keywords are too long.
NotFound404: No cluster with this id in the token’s project.

curl -X PATCH "https://api.pmkin.io/clusters/6702d4e5f6a7b8c9d0e1f2a3" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "keywords": [
    "headless cms",
    "headless cms pricing",
    "headless cms comparison"
  ]
}'

Response: 200 OK

{
  "createdAt": "2026-10-01T08:00:00.000Z",
  "description": "Everything a buyer asks before choosing a headless CMS.",
  "id": "6702d4e5f6a7b8c9d0e1f2a3",
  "keywords": [
    "headless cms",
    "headless cms pricing",
    "headless cms comparison"
  ],
  "name": "Headless CMS",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "updatedAt": "2026-10-09T12:00:00.000Z"
}

Delete a cluster#

DELETE/clusters/:id

Deletes the cluster and returns it. Its documents stay and leave the cluster.

Path parameters

idstringrequired: The cluster’s id.

Errors

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

curl -X DELETE "https://api.pmkin.io/clusters/6702d4e5f6a7b8c9d0e1f2a3" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"

Response: 200 OK

{
  "createdAt": "2026-10-01T08:00:00.000Z",
  "description": "Everything a buyer asks before choosing a headless CMS.",
  "id": "6702d4e5f6a7b8c9d0e1f2a3",
  "keywords": [
    "headless cms",
    "headless cms pricing"
  ],
  "name": "Headless CMS",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "updatedAt": "2026-10-05T14:30:00.000Z"
}