HubSpot CMS Tags API

openapi: 3.0.1
info:
  title: HubSpot CMS Tags
  description: vNext REST API for Public Blog services
  version: 2026-09
  x-hubspot-product-tier-requirements:
    marketing: PROFESSIONAL
    sales: FREE
    service: FREE
    cms: STARTER
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
  x-hubspot-api-use-case: Retrieve all blog tags as a part of a content audit, then update specific tags
    to support an upcoming company rebrand.
  x-hubspot-introduction: Use the blog tags API to create and manage available blog post tags for easy
    sorting and filtering on your site.
servers:
- url: https://api.hubapi.com
tags:
- name: Basic
- name: Batch
- name: Multi-language
paths:
  /cms/blogs/2026-09/authors/cursor:
    get:
      tags:
      - Basic
      operationId: get-/cms/blogs/2026-09/authors/cursor_/cms/blogs/v3/authors/cursor
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CursorPagedResultBlogAuthorLong'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/authors/cursor/query:
    get:
      tags:
      - Basic
      operationId: get-/cms/blogs/2026-09/authors/cursor/query_/cms/blogs/v3/authors/cursor/query
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CursorPagedResultBlogAuthorLong'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/posts/cursor:
    get:
      tags:
      - Basic
      operationId: get-/cms/blogs/2026-09/posts/cursor_/cms/blogs/v3/posts/cursor
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CursorPagedResultBlogPostLong'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/posts/cursor/query:
    get:
      tags:
      - Basic
      operationId: get-/cms/blogs/2026-09/posts/cursor/query_/cms/blogs/v3/posts/cursor/query
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CursorPagedResultBlogPostLong'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags:
    get:
      tags:
      - Basic
      summary: Get all Blog Tags
      description: 'Get the list of blog tags. Supports paging and filtering. This method would be useful
        for an integration that examined these models and used an external service to suggest edits.

        '
      operationId: get-/cms/blogs/2026-09/tags_getPage
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalTagForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
    post:
      tags:
      - Basic
      summary: Create a new Blog Tag
      description: Create a new Blog Tag.
      operationId: post-/cms/blogs/2026-09/tags_create
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/Tag'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Tag'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/batch/archive:
    post:
      tags:
      - Batch
      summary: Delete a batch of Blog Tags
      description: Delete the Blog Tag objects identified in the request body.
      operationId: post-/cms/blogs/2026-09/tags/batch/archive_archiveBatch
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/BatchInputString'
        required: true
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/batch/create:
    post:
      tags:
      - Batch
      summary: Create a batch of Blog Tags
      description: Create the Blog Tag objects detailed in the request body.
      operationId: post-/cms/blogs/2026-09/tags/batch/create_createBatch
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/BatchInputTag'
        required: true
      responses:
        '201':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BatchResponseTag'
        '207':
          description: multiple statuses
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BatchResponseTagWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/batch/read:
    post:
      tags:
      - Batch
      summary: Retrieve a batch of Blog Tags
      description: Retrieve the Blog Tag objects identified in the request body.
      operationId: post-/cms/blogs/2026-09/tags/batch/read_readBatch
      parameters:
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/BatchInputString'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BatchResponseTag'
        '207':
          description: multiple statuses
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BatchResponseTagWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/batch/update:
    post:
      tags:
      - Batch
      summary: Update a batch of Blog Tags
      description: Update the Blog Tag objects identified in the request body.
      operationId: post-/cms/blogs/2026-09/tags/batch/update_updateBatch
      parameters:
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/BatchInputJsonNode'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BatchResponseTag'
        '207':
          description: multiple statuses
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BatchResponseTagWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/cursor:
    get:
      tags:
      - Basic
      operationId: get-/cms/blogs/2026-09/tags/cursor_/cms/blogs/v3/tags/cursor
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CursorPagedResultTagLong'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/cursor/query:
    get:
      tags:
      - Basic
      operationId: get-/cms/blogs/2026-09/tags/cursor/query_/cms/blogs/v3/tags/cursor/query
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CursorPagedResultTagLong'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/multi-language/attach-to-lang-group:
    post:
      tags:
      - Multi-language
      summary: Attach a Blog Tag to a multi-language group
      description: Attach a Blog Tag to a multi-language group.
      operationId: post-/cms/blogs/2026-09/tags/multi-language/attach-to-lang-group_attachToLangGroup
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/AttachToLangPrimaryRequestVNext'
        required: true
      responses:
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/multi-language/create-language-variation:
    post:
      tags:
      - Multi-language
      summary: Create a new language variation
      description: Create a new language variation from an existing Blog Tag
      operationId: post-/cms/blogs/2026-09/tags/multi-language/create-language-variation_createLangVariation
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/TagCloneRequestVNext'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Tag'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/multi-language/detach-from-lang-group:
    post:
      tags:
      - Multi-language
      summary: Detach a Blog Tag from a multi-language group
      description: Detach a Blog Tag from a multi-language group.
      operationId: post-/cms/blogs/2026-09/tags/multi-language/detach-from-lang-group_detachFromLangGroup
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/DetachFromLangGroupRequestVNext'
        required: true
      responses:
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/multi-language/set-new-lang-primary:
    put:
      tags:
      - Multi-language
      summary: Set a new primary language
      description: Set a Blog Tag as the primary language of a multi-language group.
      operationId: put-/cms/blogs/2026-09/tags/multi-language/set-new-lang-primary_setLangPrimary
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/SetNewLanguagePrimaryRequestVNext'
        required: true
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/multi-language/update-languages:
    post:
      tags:
      - Multi-language
      summary: Update languages of multi-language group
      description: Explicitly set new languages for each Blog Tag in a multi-language group.
      operationId: post-/cms/blogs/2026-09/tags/multi-language/update-languages_updateLangs
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/UpdateLanguagesRequestVNext'
        required: true
      responses:
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
  /cms/blogs/2026-09/tags/{objectId}:
    get:
      tags:
      - Basic
      summary: Retrieve a Blog Tag
      description: Retrieve the Blog Tag object identified by the id in the path.
      operationId: get-/cms/blogs/2026-09/tags/{objectId}_getById
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Tag'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
    delete:
      tags:
      - Basic
      summary: Delete a Blog Tag
      description: Delete the Blog Tag object identified by the id in the path.
      operationId: delete-/cms/blogs/2026-09/tags/{objectId}_archive
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
    patch:
      tags:
      - Basic
      summary: Update a Blog Tag
      description: 'Sparse updates a single Blog Tag object identified by the id in the path.

        All the column values need not be specified. Only the that need to be modified can be specified.

        '
      operationId: patch-/cms/blogs/2026-09/tags/{objectId}_update
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          '*/*':
          

# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-cms-tags-api-openapi.yml