Tags API References

Tags are the shared labels applied across events, videos, blogs, podcasts, resources, external content, courses, learning paths, collections, and forum posts. A tag belongs to your community and can be attached to any number of these items.

Notes that apply to every endpoint on this page:

Tag names are case-sensitive. Design and design are two distinct tags.
Deleting a tag archives it rather than erasing it. Archived tags stop appearing in every read endpoint and in the dashboard.
Attaching a tag to a piece of content is not done here — use the relevant content endpoint (for example Add a New Video) or the dashboard.

Get All Tags

URL: https://api.gradual-api.com/public-api/v1/tags

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
name, string, optional, case-insensitive partial match on the tag name

Note: The tags are returned in order of creation date, newest first. Archived tags are excluded.

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "tagId": "6553ce608b3f645e79d95034",
            "tagName": "Getting Started",
            "tagCreatedAt": "2024-11-14T10:30:00.000Z",
            "tagUpdatedAt": "2024-11-14T10:30:00.000Z"
        },
        {
            "tagId": "6553ce608b3f645e79d95011",
            "tagName": "Design",
            "tagCreatedAt": "2024-11-02T08:15:00.000Z",
            "tagUpdatedAt": "2024-11-02T08:15:00.000Z"
        }
    ]
}

Get a Tag

URL: https://api.gradual-api.com/public-api/v1/tags/{tagId}

HTTP Method: GET

Content type: application/json

Tier: Medium

Path Parameters:

tagId, string, required, the id of the tag

Response Example:

{
    "tagId": "6553ce608b3f645e79d95034",
    "tagName": "Getting Started",
    "tagCreatedAt": "2024-11-14T10:30:00.000Z",
    "tagUpdatedAt": "2024-11-14T10:30:00.000Z",
    "tagInUse": true,
    "tagUsageTotal": 7,
    "tagUsage": {
        "events": 3,
        "videos": 1,
        "blogs": 0,
        "podcasts": 0,
        "resources": 2,
        "externalContents": 0,
        "forumPosts": 1,
        "forumTopics": 0,
        "courses": 0,
        "learningPaths": 0,
        "collections": 0
    }
}

Notes:

tagUsage counts the items of each type that currently carry this tag; tagUsageTotal is their sum.
tagInUse is broader than tagUsageTotal > 0. A tag that backs a forum topic or a pinned forum post is in use even when every count is 0. Use tagInUse — not the counts — to decide whether a delete needs a targetTagId.
An unknown, archived, or other community's tag id returns 404.
This endpoint is rated Medium, not Light, even though it addresses a single tag: computing tagUsage queries every content type the tag could be attached to.

Create a Tag

URL: https://api.gradual-api.com/public-api/v1/tags

HTTP Method: POST

Content type: application/json

Tier: Medium

Request Body Parameters:

name, string, required, the tag name (leading and trailing whitespace is trimmed)

Request Body Example:

{
    "name": "Getting Started"
}

Response Example:

{
    "tagId": "6553ce608b3f645e79d95034",
    "tagName": "Getting Started",
    "tagCreatedAt": "2024-11-14T10:30:00.000Z",
    "tagUpdatedAt": "2024-11-14T10:30:00.000Z"
}

Notes:

A tag whose name already exists in your community is rejected with a 409 error. Use GET /tags?name=... first if you need to check.
Because names are case-sensitive, creating design when Design exists succeeds and produces a second tag. Normalise casing on your side if you want a single tag per label.
Reusing the name of an archived tag is allowed and creates a new, active tag.
Any parameter other than name is rejected with a 400 error.

Rename a Tag

URL: https://api.gradual-api.com/public-api/v1/tags/{tagId}

HTTP Method: PATCH

Content type: application/json

Tier: Medium

Path Parameters:

tagId, string, required, the id of the tag

Request Body Parameters:

name, string, required, the new tag name (trimmed)

Request Body Example:

{
    "name": "Onboarding"
}

Response Example:

{
    "tagId": "6553ce608b3f645e79d95034",
    "tagName": "Onboarding",
    "tagCreatedAt": "2024-11-14T10:30:00.000Z",
    "tagUpdatedAt": "2024-11-20T09:02:00.000Z"
}

Notes:

Renaming updates the tag everywhere it is used; no content needs to be re-tagged.
Search results reflect the new name shortly after the request completes, not instantly — the rename is propagated to the search index asynchronously.
Renaming to a name already used by another active tag is rejected with a 409 error.
Sending the tag's current name is a no-op and returns 200.

Delete a Tag

URL: https://api.gradual-api.com/public-api/v1/tags/{tagId}

HTTP Method: DELETE

Content type: application/json

Tier: Medium

Path Parameters:

tagId, string, required, the id of the tag to delete

Query Parameters:

targetTagId, string, optional, another tag to move everything onto before deleting. Required when the tag is in use.

Response Example:

{
    "tagId": "6553ce608b3f645e79d95034",
    "tagName": "Onboarding",
    "tagCreatedAt": "2024-11-14T10:30:00.000Z",
    "tagUpdatedAt": "2024-11-20T09:02:00.000Z",
    "tagArchived": true,
    "tagReassignedToTagId": "6553ce608b3f645e79d95011"
}

Notes:

Deleting archives the tag. It disappears from the read endpoints and the dashboard, but nothing is permanently erased.
If the tag is attached to any content, or backs a forum topic or pinned forum post, the request is rejected with a 409 error unless you supply targetTagId. This is deliberate — it prevents a single call from silently untagging a large amount of content. Check tagInUse on GET /tags/{tagId} first.
When targetTagId is supplied, every item carrying the deleted tag is moved to the target tag, and forum topics and pinned posts are remapped to it. Items that already carried both tags keep the target exactly once.
If the tag is not in use, targetTagId may be omitted and tagReassignedToTagId is null.
targetTagId must be a different, active tag in your own community; otherwise the request is rejected with 400 or 404.

Content

Forum