Storyblok Tags API

openapi: 3.1.0
info:
  title: Storyblok Content Delivery API v2 Assets Tags API
  description: The Storyblok Content Delivery API v2 is a REST API that enables developers to fetch published content from a Storyblok space for delivery to end users across web, mobile, and other channels. It provides access to stories, datasources, links, tags, and asset metadata through predictable endpoints with token-based authentication. The API supports filtering, pagination, full-text search, and relation resolution, allowing developers to retrieve precisely the content their application needs. It is optimized for performance and available across multiple regional endpoints to minimize latency for global deployments.
  version: '2'
  contact:
    name: Storyblok Support
    url: https://www.storyblok.com/contact
  termsOfService: https://www.storyblok.com/legal/terms-of-service
servers:
- url: https://api.storyblok.com/v2/cdn
  description: Global Production Server
- url: https://api-us.storyblok.com/v2/cdn
  description: US Production Server
- url: https://api-ap.storyblok.com/v2/cdn
  description: Asia-Pacific Production Server
- url: https://api-ca.storyblok.com/v2/cdn
  description: Canada Production Server
- url: https://api-cn.storyblok.com/v2/cdn
  description: China Production Server
security:
- apiToken: []
tags:
- name: Tags
paths:
  /tags:
    get:
      operationId: listTags
      summary: List all tags
      description: Returns a list of all tags used in published stories within the space. Tags can be used to filter stories by calling the stories endpoint with the with_tag parameter.
      tags:
      - Tags
      parameters:
      - $ref: '#/components/parameters/Token'
      - name: starts_with
        in: query
        description: Filter tags by prefix. Only tags whose name starts with the given value are returned.
        required: false
        schema:
          type: string
      - name: cv
        in: query
        description: Cache version timestamp to bypass CDN caching.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: A list of tags was returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: The request was not authenticated. Ensure the token query parameter contains a valid public or preview API token for the space.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Tag:
      type: object
      description: A tag label attached to stories for filtering and categorization.
      properties:
        name:
          type: string
          description: The tag name as it appears on stories.
        taggings_count:
          type: integer
          description: Number of published stories that have this tag applied.
    Error:
      type: object
      description: Error response returned when an API request fails.
      properties:
        error:
          type: string
          description: Human-readable error message describing what went wrong.
  parameters:
    Token:
      name: token
      in: query
      description: The API access token for the space. Use the public token to access published content or the preview token to access draft content.
      required: true
      schema:
        type: string
      example: your-public-token
  securitySchemes:
    apiToken:
      type: apiKey
      in: query
      name: token
      description: Public API token for accessing published content, or Preview API token for accessing draft and published content. Tokens are scoped to a specific Storyblok space.
externalDocs:
  description: Storyblok Content Delivery API v2 Documentation
  url: https://www.storyblok.com/docs/api/content-delivery/v2