Topical Clusters API
Build topical authority by grouping content into clusters with internal linking.
3 min read
Topical Clusters API
Build topical authority by grouping content into clusters with pillar/supporting structure and internal linking.
List Clusters
GET /api/v1/topical-clusters
Response
idstring
Unique identifier for the cluster.
namestring
Display name of the cluster.
descriptionstring
Optional description of the cluster's topic focus.
pillarEntityIdstring
The entity ID of the pillar content piece for this cluster.
memberCountnumber
Total number of members (pillar + supporting) in the cluster.
Get Cluster
GET /api/v1/topical-clusters/:id
Returns the cluster including its members and internal links.
Response
idstring
Unique identifier for the cluster.
namestring
Display name of the cluster.
descriptionstring
Optional description of the cluster's topic focus.
pillarEntityIdstring
The entity ID of the pillar content piece.
memberCountnumber
Total number of members in the cluster.
membersobject[]
Array of cluster members.
members[].entityIdstring
The entity ID of the member content piece.
members[].titlestring
Title of the member content piece.
members[].rolestring
Role within the cluster: `"pillar"` or `"supporting"`.
linksobject[]
Array of internal links between cluster members.
links[].fromstring
Entity ID of the linking (source) content piece.
links[].tostring
Entity ID of the linked (target) content piece.
links[].anchorTextstring
The anchor text used for the internal link.
Create Cluster
POST /api/v1/topical-clusters
Request Body
namestringrequired
Display name for the new cluster.
descriptionstring
Optional description of the cluster's topic focus.
pillarEntityIdstring
The entity ID to assign as the pillar content piece.
Add Member
POST /api/v1/topical-clusters/:id/members
entityIdstringrequired
The entity ID to add as a cluster member.
rolestring
The member's role in the cluster. Can be `"pillar"` or `"supporting"`.
Warning
Each cluster can only have one pillar member. Setting a new member's role to `"pillar"` will demote the existing pillar to `"supporting"`.
Create Internal Link
POST /api/v1/topical-clusters/:id/links
fromstringrequired
Entity ID of the source content piece (the page that contains the link).
tostringrequired
Entity ID of the target content piece (the page being linked to).
anchorTextstring
The anchor text to use for the internal link.
Note
Both `from` and `to` entities must be existing members of the cluster. Add them as members first if needed.
Was this helpful?