drupal Taxonomy Terms API

openapi: 3.1.0
info:
  title: 'Drupal JSON: Comments Taxonomy Terms API'
  description: The Drupal JSON:API module is a core component that exposes all Drupal entity types and bundles as a standards-compliant JSON:API interface, requiring no configuration to enable. Each entity bundle receives a unique URL path following the pattern /jsonapi/{entity_type}/{bundle}, and the module supports GET, POST, PATCH, and DELETE operations for full CRUD access. It supports filtering, sorting, pagination, sparse fieldsets, includes for relationship resolution, translations, revisions, and file uploads out of the box. All resource identifiers use entity UUIDs rather than numeric IDs. The JSON:API module is the recommended approach for most decoupled and headless Drupal applications due to its adherence to the open JSON:API specification (jsonapi.org) and its compatibility with the broader JSON:API client ecosystem.
  version: '1.1'
  contact:
    name: Drupal Community
    url: https://www.drupal.org/community
  termsOfService: https://www.drupal.org/about/legal
servers:
- url: https://example.com/jsonapi
  description: Drupal JSON:API Base (replace with your Drupal installation base URL)
security:
- basicAuth: []
- oAuth2:
  - content
tags:
- name: Taxonomy Terms
  description: JSON:API endpoints for taxonomy term entities across all configured vocabularies.
paths:
  /taxonomy_term/{vocabulary}:
    get:
      operationId: listTaxonomyTerms
      summary: List taxonomy terms by vocabulary
      description: Retrieves a collection of taxonomy terms for a specific vocabulary bundle. Replace {vocabulary} with the machine name of the vocabulary (e.g., tags, categories). Supports filtering, sorting, pagination, and includes.
      tags:
      - Taxonomy Terms
      parameters:
      - $ref: '#/components/parameters/VocabularyBundle'
      - $ref: '#/components/parameters/JsonApiAccept'
      - $ref: '#/components/parameters/FilterPath'
      - $ref: '#/components/parameters/FilterValue'
      - $ref: '#/components/parameters/SortParam'
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/IncludeParam'
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Collection of taxonomy terms returned successfully.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JsonApiCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /taxonomy_term/{vocabulary}/{uuid}:
    get:
      operationId: getTaxonomyTerm
      summary: Get a taxonomy term
      description: Retrieves a single taxonomy term by vocabulary bundle and UUID. Returns the term's name, description, weight, and any configured relationships such as parent terms.
      tags:
      - Taxonomy Terms
      parameters:
      - $ref: '#/components/parameters/VocabularyBundle'
      - $ref: '#/components/parameters/EntityUuid'
      - $ref: '#/components/parameters/JsonApiAccept'
      - $ref: '#/components/parameters/IncludeParam'
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Taxonomy term returned successfully.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JsonApiSingleResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /taxonomy/term/{id}:
    get:
      operationId: getTaxonomyTerm
      summary: Get a taxonomy term
      description: Retrieves a single taxonomy term entity by its numeric ID. Returns the term's name, vocabulary, description, and any additional fields configured on the term bundle.
      tags:
      - Taxonomy Terms
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/AcceptFormat'
      responses:
        '200':
          description: Taxonomy term returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyTerm'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound_2'
    patch:
      operationId: updateTaxonomyTerm
      summary: Update a taxonomy term
      description: Updates an existing taxonomy term entity by its numeric ID. Only the fields included in the request body are modified. Requires taxonomy management permissions and authentication.
      tags:
      - Taxonomy Terms
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/ContentTypeFormat'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxonomyTermInput'
      responses:
        '200':
          description: Taxonomy term updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyTerm'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden_2'
        '404':
          $ref: '#/components/responses/NotFound_2'
    delete:
      operationId: deleteTaxonomyTerm
      summary: Delete a taxonomy term
      description: Permanently deletes a taxonomy term entity by its numeric ID. Requires taxonomy management permissions and authentication.
      tags:
      - Taxonomy Terms
      parameters:
      - $ref: '#/components/parameters/EntityId'
      responses:
        '204':
          description: Taxonomy term deleted successfully. No content returned.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden_2'
        '404':
          $ref: '#/components/responses/NotFound_2'
  /taxonomy/term:
    post:
      operationId: createTaxonomyTerm
      summary: Create a taxonomy term
      description: Creates a new taxonomy term in a specified vocabulary. The request body must include the term name and target vocabulary. Requires taxonomy management permissions and authentication.
      tags:
      - Taxonomy Terms
      parameters:
      - $ref: '#/components/parameters/ContentTypeFormat'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxonomyTermInput'
      responses:
        '201':
          description: Taxonomy term created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyTerm'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden_2'
components:
  parameters:
    AcceptFormat:
      name: Accept
      in: header
      required: false
      description: The desired response serialization format. Defaults to application/json. Use application/hal+json for HAL+JSON hypermedia format.
      schema:
        type: string
        enum:
        - application/json
        - application/hal+json
        - application/xml
        default: application/json
    VocabularyBundle:
      name: vocabulary
      in: path
      required: true
      description: The machine name of the taxonomy vocabulary bundle (e.g., tags, categories, topics).
      schema:
        type: string
        example: tags
    FilterPath:
      name: filter[name][path]
      in: query
      required: false
      description: The dotted field path to filter on, e.g. title, status, uid.name, or field_tags.name for nested relationship fields.
      schema:
        type: string
        example: status
    EntityId:
      name: id
      in: path
      required: true
      description: The numeric ID of the entity.
      schema:
        type: integer
        minimum: 1
    ContentTypeFormat:
      name: Content-Type
      in: header
      required: true
      description: The serialization format of the request body. Must match the format of the data being sent.
      schema:
        type: string
        enum:
        - application/json
        - application/hal+json
        default: application/json
    FieldsParam:
      name: fields[node--article]
      in: query
      required: false
      description: Sparse fieldset parameter to limit which attributes are returned, reducing response payload size. Replace node--article with the relevant resource type. Value is a comma-separated list of field names.
      schema:
        type: string
        example: title,body,created
    PageLimit:
      name: page[limit]
      in: query
      required: false
      description: The maximum number of resources to return in a single page. Used for cursor-based pagination.
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 50
    EntityUuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the entity. JSON:API always uses UUID as the identifier, not the numeric entity ID.
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
    SortParam:
      name: sort
      in: query
      required: false
      description: Sort the results by the given field. Prefix with - for descending order. For example, sort=title for ascending by title or sort=-created for descending by creation date.
      schema:
        type: string
        example: -created
    JsonApiAccept:
      name: Accept
      in: header
      required: false
      description: The JSON:API media type. Include this header to receive a properly formatted JSON:API response.
      schema:
        type: string
        default: application/vnd.api+json
    FilterValue:
      name: filter[name][value]
      in: query
      required: false
      description: The value to filter against.
      schema:
        type: string
        example: '1'
    PageOffset:
      name: page[offset]
      in: query
      required: false
      description: The number of resources to skip before beginning to return results. Used in combination with page[limit] for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    IncludeParam:
      name: include
      in: query
      required: false
      description: A comma-separated list of relationship paths to include in the response. For example, include=uid resolves the author relationship, and include=field_tags includes related taxonomy terms inline.
      schema:
        type: string
        example: uid,field_tags
  responses:
    BadRequest:
      description: The request body or query parameters are invalid.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorResponse'
    NotFound:
      description: The requested resource does not exist or is inaccessible.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorResponse'
    NotFound_2:
      description: The requested entity does not exist or is not accessible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest_2:
      description: The request body or parameters are invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden_2:
      description: The authenticated user does not have permission to perform this operation on this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication is required to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The authenticated user lacks permission to perform this operation.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorResponse'
  schemas:
    IntegerValue:
      type: object
      description: Drupal field value wrapper for an integer value.
      properties:
        value:
          type: integer
          description: The integer value.
    TextContent:
      type: object
      description: Drupal text field value with optional summary and text format.
      properties:
        value:
          type: string
          description: The full text content, may include HTML markup depending on format.
        summary:
          type: string
          description: Optional trimmed summary of the text content.
        format:
          type: string
          description: The text format machine name applied to this field (e.g., basic_html, full_html, plain_text).
    TaxonomyTermInput:
      type: object
      description: Request body for creating or updating a taxonomy term.
      required:
      - name
      - vid
      properties:
        vid:
          type: array
          description: The target vocabulary machine name.
          items:
            $ref: '#/components/schemas/TargetId'
        name:
          type: array
          description: The display name of the taxonomy term.
          items:
            $ref: '#/components/schemas/StringValue'
        description:
          type: array
          description: Optional description for the term.
          items:
            $ref: '#/components/schemas/TextContent'
        parent:
          type: array
          description: Optional parent term reference for hierarchical vocabularies.
          items:
            $ref: '#/components/schemas/TargetId'
    JsonApiLinks:
      type: object
      description: Navigation links included in JSON:API responses.
      properties:
        self:
          type: object
          description: Link to the current resource or collection.
          properties:
            href:
              type: string
              format: uri
              description: The URL of the current resource.
        related:
          type: object
          description: Link to a related resource.
          properties:
            href:
              type: string
              format: uri
              description: The URL of the related resource.
    ErrorResponse:
      type: object
      description: Standard error response returned for 4xx HTTP error codes.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
    TargetId:
      type: object
      description: Drupal entity reference value wrapper pointing to a related entity.
      properties:
        target_id:
          type: integer
          description: The numeric ID of the referenced entity.
    JsonApiSingleResponse:
      type: object
      description: A JSON:API response containing a single resource object.
      properties:
        jsonapi:
          type: object
          description: JSON:API version metadata.
          properties:
            version:
              type: string
              description: The JSON:API specification version.
              example: '1.0'
        data:
          $ref: '#/components/schemas/JsonApiResourceObject'
        included:
          type: array
          description: Array of included related resources when using the include parameter.
          items:
            $ref: '#/components/schemas/JsonApiResourceObject'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    JsonApiErrorResponse:
      type: object
      description: A JSON:API error response containing one or more error objects.
      properties:
        errors:
          type: array
          description: Array of error objects describing the problems encountered.
          items:
            $ref: '#/components/schemas/JsonApiError'
        jsonapi:
          type: object
          properties:
            version:
              type: string
              example: '1.0'
    JsonApiCollection:
      type: object
      description: A JSON:API collection response containing multiple resource objects.
      properties:
        jsonapi:
          type: object
          description: JSON:API version metadata.
          properties:
            version:
              type: string
              description: The JSON:API specification version.
              example: '1.0'
        data:
          type: array
          description: Array of resource objects.
          items:
            $ref: '#/components/schemas/JsonApiResourceObject'
        included:
          type: array
          description: Array of included related resources when using the include parameter.
          items:
            $ref: '#/components/schemas/JsonApiResourceObject'
        links:
          $ref: '#/components/schemas/JsonApiCollectionLinks'
        meta:
          type: object
          description: Non-standard meta-information about the response, such as total result count.
          properties:
            count:
              type: integer
              description: Total number of matching resources across all pages.
    StringValue:
      type: object
      description: Drupal field value wrapper for a string value.
      properties:
        value:
          type: string
          description: The string value.
    TaxonomyTerm:
      type: object
      description: A Drupal taxonomy term entity used for categorizing and tagging content within a vocabulary.
      properties:
        tid:
          type: array
          description: The numeric taxonomy term ID.
          items:
            $ref: '#/components/schemas/IntegerValue'
        uuid:
          type: array
          description: The universally unique identifier of the term.
          items:
            $ref: '#/components/schemas/StringValue'
        vid:
          type: array
          description: Reference to the vocabulary this term belongs to.
          items:
            $ref: '#/components/schemas/TargetId'
        name:
          type: array
          description: The display name of the taxonomy term.
          items:
            $ref: '#/components/schemas/StringValue'
        description:
          type: array
          description: Optional description for the taxonomy term.
          items:
            $ref: '#/components/schemas/TextContent'
        weight:
          type: array
          description: Integer weight controlling term ordering within the vocabulary.
          items:
            $ref: '#/components/schemas/IntegerValue'
        parent:
          type: array
          description: Reference to parent term(s) for hierarchical vocabularies.
          items:
            $ref: '#/components/schemas/TargetId'
    JsonApiResourceObject:
      type: object
      description: A JSON:API resource object representing a single Drupal entity.
      required:
      - type
      - id
      properties:
        type:
          type: string
          description: The JSON:API resource type in the format {entity_type}--{bundle}, e.g. node--article, taxonomy_term--tags.
          example: node--article
        id:
          type: string
          format: uuid
          description: The UUID of the resource.
        attributes:
          type: object
          description: The resource's field values excluding entity references. Keys are field machine names.
        relationships:
          type: object
          description: The resource's entity reference fields expressed as relationship objects with data containing type and id.
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    JsonApiError:
      type: object
      description: A single JSON:API error object.
      properties:
        status:
          type: string
          description: The HTTP status code for this error.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        detail:
          type: string
          description: A human-readable explanation specific to this error occurrence.
        source:
          type: object
          description: An object containing a reference to the source of the error.
          properties:
            pointer:
              type: string
              description: A JSON Pointer to the associated entity in the request body.
            parameter:
              type: string
              description: The query parameter that caused the error.
    JsonApiCollectionLinks:
      type: object
      description: Pagination links for collection responses.
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the current page.
        first:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the first page of results.
        prev:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the previous page of results.
        next:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the next page of results.
        last:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the last page of results.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Drupal username and password.
    cookieAuth:
      type: apiKey
      in: cookie
      name: SESS
      description: Cookie-based session authentication obtained via Drupal login.
    oAuth2:
      type: oauth2
      description: OAuth 2.0 via the Simple OAuth module.
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            content: Access and manage content entities
            user: Access and manage user entities
externalDocs:
  description: Drupal JSON:API Module Documentation
  url: https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module/api-overview