Tags add flexible topic labels to posts. Use their shared IDs for assignments, and use localized variants for topic-page names, slugs, descriptions, and SEO fields.

Choose a surface

The API, Node SDK, and CLI manage the same tag concepts. Compare all Cli Blog tools.

Action	HTTP API	Node SDK	CLI	Description
List	`GET /v1/tags`	`blog.tags.list()` or `.paginate()`	`cli-blog tags list`	Page through localized tags
Create	`POST /v1/tags`	`blog.tags.create()`	`cli-blog tags create`	Create a tag or localized variant
Retrieve	`GET /v1/tags/{id}`	`blog.tags.get()`	`cli-blog tags get`	Get a tag by shared ID or localized slug
Update	`POST /v1/tags/{id}`	`blog.tags.update()`	`cli-blog tags update`	Change localized tag fields
Delete	`DELETE /v1/tags/{id}`	`blog.tags.delete()`	`cli-blog tags delete`	Delete a localized tag

Public and private keys can list and retrieve tags. Create, update, and delete actions require a private key with tag permission.

Create a tag

Create a tag before assigning its shared ID through a post's tag_ids field:

curl "https://api.cli-blog.com/v1/tags" \
  --header "x-api-key: $CLI_BLOG_PRIVATE_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "name": "Release notes",
    "slug": "release-notes",
    "locale": "en-US",
    "description": "Product, platform, and integration updates.",
    "robots_index": true
  }'

The response returns the shared concept ID:

{
  "id": "term_tag_3c09f1",
  "object": "taxonomy_term",
  "organization_id": "org_demo_acme",
  "taxonomy_type": "tag",
  "parent_taxonomy_term_id": null,
  "locale": "en-US",
  "name": "Release notes",
  "slug": "release-notes",
  "description": "Product, platform, and integration updates.",
  "seo_title": null,
  "seo_description": null,
  "canonical_url": null,
  "focus_keyphrase": null,
  "seo_keywords": [],
  "robots_index": true,
  "robots_follow": true,
  "open_graph_title": null,
  "open_graph_description": null,
  "open_graph_media_asset_id": null,
  "twitter_title": null,
  "twitter_description": null,
  "twitter_media_asset_id": null,
  "schema_type": "CollectionPage",
  "metadata": {},
  "created_at": "2026-07-11T17:15:00.000Z",
  "updated_at": "2026-07-11T17:15:00.000Z"
}

The SDK and CLI create the same resource:

import { CliBlog } from "@cli-blog/node";

const blog = new CliBlog({
  apiKey: process.env.CLI_BLOG_PRIVATE_API_KEY!,
  apiUrl: "https://api.cli-blog.com",
});

const tag = await blog.tags.create({
  name: "Release notes",
  locale: "en-US",
  description: "Product, platform, and integration updates.",
});

cli-blog tags create \
  --name "Release notes" \
  --locale en-US \
  --description "Product, platform, and integration updates." \
  --json

List and retrieve tags

Cursor pagination is the preferred list mode. Set limit up to 100, then pass next_cursor as after. Use numbered pagination only when a tag manager requires exact totals. See Pagination.

Omit locale to use the organization's primary locale. Cli Blog does not fall back to another locale in V1. Add include=translations when the current view needs every localized variant.

const firstPage = await blog.tags.list({
  locale: "en-US",
  include: "translations",
  limit: 50,
});

const tag = await blog.tags.get("release-notes", {
  locale: "en-US",
  include: "translations",
});

cli-blog tags list --locale en-US --include translations --limit 50 --json
cli-blog tags get release-notes --locale en-US --json

Add a translation

Pass an existing shared tag ID as translation_of_id. Posts keep the same tag_ids assignment across translations.

await blog.tags.create({
  name: "Notas de lanzamiento",
  slug: "notas-de-lanzamiento",
  locale: "es-MX",
  translation_of_id: "term_tag_3c09f1",
  description: "Actualizaciones del producto, la plataforma y las integraciones.",
});

Update and delete a tag

Pass locale when an ID or slug has localized variants. Tags do not accept parent_taxonomy_term_id; use Categories for hierarchy.

await blog.tags.update(
  "term_tag_3c09f1",
  { description: "Release notes for the product, API, SDK, and CLI." },
  { locale: "en-US" },
);

await blog.tags.delete("term_tag_3c09f1", { locale: "en-US" });

cli-blog tags update term_tag_3c09f1 \
  --locale en-US \
  --description "Release notes for the product, API, SDK, and CLI." \
  --json

cli-blog tags delete term_tag_3c09f1 --locale en-US --yes

Review post assignments before deleting a tag.

Tag fields

Field family	Fields and description
Identity	`id`, `object`, `organization_id`, and `taxonomy_type` identify the shared concept
Localization	`locale`, `name`, `slug`, `description`, and optional `translations` describe localized variants
Search and social	Search, canonical, robots, Open Graph, X/Twitter, keyword, and `schema_type` fields describe the topic archive
Integration data	`metadata` stores integration-defined JSON up to 32 KB when serialized
Timestamps	`created_at` and `updated_at` report ISO timestamps

Common errors

Status	Cause	Resolution
`400`	Unsupported locale, category-only parent field, or mixed pagination modes	Check the error `param` and remove unsupported fields
`401`	Missing or invalid API key	Send the organization key in `x-api-key`
`403`	Public key used for a write or private key lacks permission	Use a scoped private key
`404`	Shared ID or slug does not exist in the requested locale	Confirm the locale and identifier
`409`	Slug already exists in that locale	Choose a unique locale-scoped slug

Complete API operations

The operation reference lists every path, locale control, include, request field, response field, and error schema. Use Try it to open the request runner.

Key type: Public or private key

List localized tags. 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 tag list page.

limit?|

Maximum tags 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/tags"

{  "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 a tag

Key type: Private key

Send a JSON body to create a localized tag. 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/tags" \  -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 a tag

Key type: Public or private key

Retrieve a tag 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 tag concept ID or locale-scoped slug.

Query Parameters

locale?string

BCP 47 locale tag used for tag 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/tags/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 a tag

Key type: Private key

Send a JSON body to update a localized tag.

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/tags/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 a tag

Key type: Private key

Delete a localized tag.

Authorization

ApiKeyAuth

x-api-key<token>

In: header

`application/json`

curl -X DELETE "https://example.com/v1/tags/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"  }}

Tags

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

On this page

`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`