Resource overviewLocalized hierarchical navigation backed by stable shared concepts.

AuthenticationPublic reads or private writes

Common workflowCreate the category concept and locale term, then assign the shared category ID to posts.

Key type: Public or private key

List localized categories. Cursor pagination is the default; page and per_page opt into exact numbered pagination and cannot be combined with after or limit. Omitted locale uses the organization primary/default locale; v1 does not fall back across locales.

Authorization

ApiKeyAuth

x-api-key<token>

Organization API key. Each key selects exactly one organization; do not send an organization ID separately. Public keys use the cli_blog_pk_ prefix and are intended for published-content delivery reads. Private keys use the cli_blog_sk_ prefix, belong only in trusted environments, and are required for write, publish, delete, and editorial-state workflows when their scopes allow it.

In: header

Query Parameters

after?string

Opaque cursor returned by the previous category list page.

limit?|

Maximum categories to return. Defaults to 20. The maximum accepted value is 100.

page?|

One-based exact page number. Supplying page selects numbered pagination and cannot be combined with after or limit.

per_page?|

Items per numbered page. Requires page, defaults to 20, and cannot be combined with after or limit.

locale?string

BCP 47 locale tag to list, for example en-US or es-MX. Categories and tags are shared concepts with localized variants; omitted locale uses organization defaults.

include?array<string>

Optional related data to include. Use translations to see available localized variants.

Response Body

`application/json`

curl -X GET "https://example.com/v1/categories"

{  "object": "list",  "has_more": true,  "next_cursor": "string",  "page": 0,  "per_page": 0,  "total_items": 0,  "total_pages": 0,  "data": [    {      "id": "string",      "object": "taxonomy_term",      "organization_id": "string",      "taxonomy_type": "string",      "parent_taxonomy_term_id": "string",      "locale": "string",      "name": "string",      "slug": "string",      "description": "string",      "seo_title": "string",      "seo_description": "string",      "canonical_url": "string",      "focus_keyphrase": "string",      "seo_keywords": [        "string"      ],      "robots_index": true,      "robots_follow": true,      "open_graph_title": "string",      "open_graph_description": "string",      "open_graph_media_asset_id": "string",      "twitter_title": "string",      "twitter_description": "string",      "twitter_media_asset_id": "string",      "schema_type": "string",      "metadata": null,      "created_at": "string",      "updated_at": "string",      "translations": [        {          "id": "string",          "locale": "string",          "name": "string",          "slug": "string"        }      ]    }  ]}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Create category

Key type: Private key

Send a JSON body to create a localized category. Its stable shared ID can be assigned to posts across locales. Omit locale to use the organization primary/default locale.

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Reader-facing category or tag name.

slug?string

Optional slug. If omitted, Cli Blog derives one from name.

locale?string

BCP 47 locale tag for this term variant, such as en-US or es-MX. Omit it to use the organization's primary/default locale.

translation_of_id?|

Existing shared category or tag concept ID whose localized variants this term belongs to.

parent_taxonomy_term_id?|

Parent shared category concept ID. Only categories support parents.

description?|

Optional category or tag description.

seo_title?|

Optional search result title override.

seo_description?|

Optional search result description override.

canonical_url?|

Canonical URL override for the preferred term archive URL.

focus_keyphrase?|

Primary editorial SEO keyphrase for the term archive.

seo_keywords?array<string>

Editorial SEO keywords for analysis and tooling.

robots_index?boolean

Whether crawlers should index the term archive.

robots_follow?boolean

Whether crawlers should follow term archive links.

open_graph_title?|

Open Graph title override for social previews.

open_graph_description?|

Open Graph description override for social previews.

open_graph_media_asset_id?|

Media asset ID used for Open Graph previews.

twitter_title?|

X/Twitter title override for social previews.

twitter_description?|

X/Twitter description override for social previews.

twitter_media_asset_id?|

Media asset ID used for X/Twitter previews.

schema_type?|

Structured-data schema type, default CollectionPage.

metadata?unknown

Integration-defined JSON object for data not modeled by v1 fields. Maximum serialized size: 32 KB.

Response Body

`application/json`

curl -X POST "https://example.com/v1/categories" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "id": "string",  "object": "taxonomy_term",  "organization_id": "string",  "taxonomy_type": "string",  "parent_taxonomy_term_id": "string",  "locale": "string",  "name": "string",  "slug": "string",  "description": "string",  "seo_title": "string",  "seo_description": "string",  "canonical_url": "string",  "focus_keyphrase": "string",  "seo_keywords": [    "string"  ],  "robots_index": true,  "robots_follow": true,  "open_graph_title": "string",  "open_graph_description": "string",  "open_graph_media_asset_id": "string",  "twitter_title": "string",  "twitter_description": "string",  "twitter_media_asset_id": "string",  "schema_type": "string",  "metadata": null,  "created_at": "string",  "updated_at": "string",  "translations": [    {      "id": "string",      "locale": "string",      "name": "string",      "slug": "string"    }  ]}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Retrieve category

Key type: Public or private key

Retrieve a category by its stable shared ID or locale-scoped slug. Omitted locale uses the organization primary/default locale; v1 does not automatically fall back to another locale.

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Path Parameters

id*string

Shared category concept ID or locale-scoped slug.

Query Parameters

locale?string

BCP 47 locale tag used for category slug lookup.

include?array<string>

Optional related data to include. Use translations to see available localized variants.

Response Body

`application/json`

curl -X GET "https://example.com/v1/categories/string"

{  "id": "string",  "object": "taxonomy_term",  "organization_id": "string",  "taxonomy_type": "string",  "parent_taxonomy_term_id": "string",  "locale": "string",  "name": "string",  "slug": "string",  "description": "string",  "seo_title": "string",  "seo_description": "string",  "canonical_url": "string",  "focus_keyphrase": "string",  "seo_keywords": [    "string"  ],  "robots_index": true,  "robots_follow": true,  "open_graph_title": "string",  "open_graph_description": "string",  "open_graph_media_asset_id": "string",  "twitter_title": "string",  "twitter_description": "string",  "twitter_media_asset_id": "string",  "schema_type": "string",  "metadata": null,  "created_at": "string",  "updated_at": "string",  "translations": [    {      "id": "string",      "locale": "string",      "name": "string",      "slug": "string"    }  ]}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Update category

Key type: Private key

Send a JSON body to update a localized category or its category parent.

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Reader-facing category or tag name.

slug?string

Optional slug. If omitted, Cli Blog derives one from name.

locale?string

BCP 47 locale tag for this term variant, such as en-US or es-MX. Omit it to use the organization's primary/default locale.

translation_of_id?|

Existing shared category or tag concept ID whose localized variants this term belongs to.

parent_taxonomy_term_id?|

Parent shared category concept ID. Only categories support parents.

description?|

Optional category or tag description.

seo_title?|

Optional search result title override.

seo_description?|

Optional search result description override.

canonical_url?|

Canonical URL override for the preferred term archive URL.

focus_keyphrase?|

Primary editorial SEO keyphrase for the term archive.

seo_keywords?array<string>

Editorial SEO keywords for analysis and tooling.

robots_index?boolean

Whether crawlers should index the term archive.

robots_follow?boolean

Whether crawlers should follow term archive links.

open_graph_title?|

Open Graph title override for social previews.

open_graph_description?|

Open Graph description override for social previews.

open_graph_media_asset_id?|

Media asset ID used for Open Graph previews.

twitter_title?|

X/Twitter title override for social previews.

twitter_description?|

X/Twitter description override for social previews.

twitter_media_asset_id?|

Media asset ID used for X/Twitter previews.

schema_type?|

Structured-data schema type, default CollectionPage.

metadata?unknown

Integration-defined JSON object for data not modeled by v1 fields. Maximum serialized size: 32 KB.

Response Body

`application/json`

curl -X POST "https://example.com/v1/categories/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "object": "taxonomy_term",  "organization_id": "string",  "taxonomy_type": "string",  "parent_taxonomy_term_id": "string",  "locale": "string",  "name": "string",  "slug": "string",  "description": "string",  "seo_title": "string",  "seo_description": "string",  "canonical_url": "string",  "focus_keyphrase": "string",  "seo_keywords": [    "string"  ],  "robots_index": true,  "robots_follow": true,  "open_graph_title": "string",  "open_graph_description": "string",  "open_graph_media_asset_id": "string",  "twitter_title": "string",  "twitter_description": "string",  "twitter_media_asset_id": "string",  "schema_type": "string",  "metadata": null,  "created_at": "string",  "updated_at": "string",  "translations": [    {      "id": "string",      "locale": "string",      "name": "string",      "slug": "string"    }  ]}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Delete category

Key type: Private key

Delete a localized category.

Authorization

ApiKeyAuth

x-api-key<token>

In: header

`application/json`

curl -X DELETE "https://example.com/v1/categories/string"

{  "deleted": true,  "id": "string"}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Categories

200application/json

400application/json

401application/json

403application/json

422application/json

429application/json

201application/json

400application/json

401application/json

403application/json

409application/json

429application/json

200application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

200application/json

401application/json

403application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`