Article Tags

A tag is a free-form label scoped to your org. Articles attach to tags many-to-many. Tags are flat (no hierarchy) and reusable across knowledge bases and categories — use them to slice content by audience, surface area, or any orthogonal axis that doesn’t fit the category tree.

When to reach for tags

Audience slicing

b2b, b2c, enterprise — surface different subsets of the same KB to different chatbots.

Search filters

Let users narrow KB search by topic without rebuilding your category tree.

Internal flags

needs-review, legal-approved, stale — workflow state that doesn’t belong on the status field.

Anatomy

{
  "object": "article_tag",
  "id": "5d694e14-5440-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "customer-facing",
  "created_at": "2026-05-22T14:00:00Z"
}

Tags carry just an id, a name, and a creation timestamp. There is no description, color, or hierarchy. The name is unique per org.

The two surfaces

Tags live behind two related endpoints:

Tag CRUD

POST /article-tags, GET /article-tags, DELETE /article-tags/{id} manage the tag rows themselves — create reusable labels, list them, retire them.

Article tag assignments

GET /articles/{id}/tags returns the tags on one article. PUT /articles/{id} /tags replaces the full set of assignments in a single call.

There is no “add a single tag to an article” endpoint — assignments are replaced as a set. Send the full list of tag_ids you want the article to carry.

Creating tags

curl https://api.awardee.com/v1/article-tags \
  -X POST \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Content-Type: application/json" \
  -d '{ "name": "customer-facing" }'

const res = await fetch("https://api.awardee.com/v1/article-tags", {
  method: "POST",
  headers: {
    Authorization: "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "customer-facing" }),
})
const tag = await res.json()

import requests

res = requests.post(
    "https://api.awardee.com/v1/article-tags",
    headers={
        "Authorization": "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e",
        "Content-Type": "application/json",
    },
    json={"name": "customer-facing"},
)
tag = res.json()

Listing tags

GET /article-tags paginates. Pass search to fuzzy-match on name.

curl "https://api.awardee.com/v1/article-tags?search=customer&page_size=50" \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

const res = await fetch(
  "https://api.awardee.com/v1/article-tags?search=customer&page_size=50",
  { headers: { Authorization: `Bearer ${API_KEY}` } }
)
const { data } = await res.json()

import requests

res = requests.get(
    "https://api.awardee.com/v1/article-tags",
    params={"search": "customer", "page_size": 50},
    headers={"Authorization": f"Bearer {API_KEY}"},
)
data = res.json()["data"]

Assigning tags to an article

PUT /articles/{id}/tags replaces the assignment set. Send the complete list of tag_ids you want; anything not in the list is unassigned.

curl https://api.awardee.com/v1/articles/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/tags \
  -X PUT \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": [
      "5d694e14-5440-4f5d-9e8a-7c3b2a1d0f9e",
      "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e"
    ]
  }'

await fetch(`https://api.awardee.com/v1/articles/${ARTICLE_ID}/tags`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tag_ids: [
      "5d694e14-5440-4f5d-9e8a-7c3b2a1d0f9e",
      "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    ],
  }),
})

import requests

requests.put(
    f"https://api.awardee.com/v1/articles/{ARTICLE_ID}/tags",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "tag_ids": [
            "5d694e14-5440-4f5d-9e8a-7c3b2a1d0f9e",
            "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
        ]
    },
)

To clear all tags from an article, send {"tag_ids": []}. To add a single tag to an article that already has tags, first GET /articles/{id}/tags, append the new id, then PUT the full list back.

List endpoints (GET /articles) return tag_names inline on each article. Use that to avoid a follow-up tag lookup for every row.

Deleting a tag

DELETE /article-tags/{id} removes the tag and unassigns it from every article that carried it. Articles themselves are untouched. There is no soft-delete — recreate the tag and re-assign if you change your mind.

curl https://api.awardee.com/v1/article-tags/5d694e14-5440-4f5d-9e8a-7c3b2a1d0f9e \
  -X DELETE \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

await fetch(`https://api.awardee.com/v1/article-tags/${TAG_ID}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` },
})

import requests

requests.delete(
    f"https://api.awardee.com/v1/article-tags/{TAG_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

A 204 confirms the delete. The articles that had the tag remain — only the assignment rows are dropped.

Get started

Identity

Concepts

Webhooks

Chatbots

Customers

Articles

Article Categories

Knowledge Bases

Conversations

Conversation Tags

Submissions

Pages

QR Codes

QR Groups

Products

Objects

Custom Domains

Custom Domain Routes

Team

Article Tags

When to reach for tags

Audience slicing

Search filters

Internal flags

Anatomy

The two surfaces

Tag CRUD

Article tag assignments

Creating tags

Listing tags

Assigning tags to an article

Deleting a tag

​When to reach for tags

Audience slicing

Search filters

Internal flags

​Anatomy

​The two surfaces

Tag CRUD

Article tag assignments

​Creating tags

​Listing tags

​Assigning tags to an article

​Deleting a tag

When to reach for tags

Anatomy

The two surfaces

Creating tags

Listing tags

Assigning tags to an article

Deleting a tag