> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a taxonomy element



## OpenAPI

````yaml https://thetradedesk.narrativeconnectors.com/openapi.json put /taxonomies/elements/{element_id}
openapi: 3.0.2
info:
  title: The Trade Desk Connector API
  version: '2026-10-07'
  description: >-
    The Trade Desk connector API.


    Every operation except `/interfaces` and `/version` needs a Narrative API
    token in the

    `Authorization: Bearer <token>` header. A request without the header gets a
    403 with an empty body.
servers:
  - url: https://thetradedesk.narrativeconnectors.com
    description: Production
  - url: https://thetradedesk-dev.narrativeconnectors.com
    description: Development
security:
  - smithy.api.httpBearerAuth: []
paths:
  /taxonomies/elements/{element_id}:
    put:
      tags:
        - taxonomies
      summary: Update a taxonomy element
      operationId: UpdateTaxonomyElement
      parameters:
        - name: element_id
          in: path
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaxonomyElementRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyElement'
        '400':
          description: >-
            - The request is invalid. `error` is `bad_payload` when the body or
            a parameter cannot be read, or `invalid_request` when the request is
            well-formed but cannot be applied.

            - A dataset attached to the taxonomy element has a schema the
            connector cannot use. `debug` holds the validation errors keyed by
            dataset id.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BadRequestError'
                  - $ref: '#/components/schemas/InvalidDatasetSchemaError'
        '403':
          description: >-
            The token is missing, invalid or expired, or the company has not
            installed the app. A request without an `Authorization: Bearer`
            header gets an empty body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: >-
            The resource does not exist, or an id in the path is not a valid
            UUID.
        '500':
          description: Unexpected failure.
        '502':
          description: The Narrative API or The Trade Desk API failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamError'
components:
  schemas:
    UpdateTaxonomyElementRequest:
      type: object
      properties:
        buyable:
          type: boolean
        data_rates:
          type: array
          items:
            $ref: '#/components/schemas/CreateDataRateRequest'
          description: Data rates cannot be changed once the element is active.
        datasets:
          type: array
          items:
            type: integer
            description: Narrative dataset id.
            format: int64
          description: Datasets not already attached are validated and attached.
        description:
          type: string
        display_name:
          type: string
        parent_element_id:
          type: string
      required:
        - buyable
        - data_rates
        - datasets
        - display_name
    TaxonomyElement:
      type: object
      properties:
        buyable:
          type: boolean
        children:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyElement'
        connections:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyElementConnection'
        created_at:
          type: string
          format: date-time
        data_rates:
          type: array
          items:
            $ref: '#/components/schemas/DataRate'
        description:
          type: string
          nullable: true
        display_name:
          type: string
        element_id:
          type: string
        parent_element_id:
          type: string
          nullable: true
        statistics:
          description: Null while the element is a draft.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/TaxonomyElementStatistics'
        status:
          $ref: '#/components/schemas/ElementStatus'
        updated_at:
          type: string
          format: date-time
        compliance_status:
          $ref: '#/components/schemas/ComplianceStatus'
      required:
        - buyable
        - children
        - compliance_status
        - connections
        - created_at
        - data_rates
        - description
        - display_name
        - element_id
        - parent_element_id
        - statistics
        - status
        - updated_at
    BadRequestError:
      type: object
      description: >-
        The request is invalid. `error` is `bad_payload` when the body or a
        parameter cannot be read, or

        `invalid_request` when the request is well-formed but cannot be applied.
      properties:
        error:
          type: string
          description: '`bad_payload` or `invalid_request`.'
        error_description:
          type: string
      required:
        - error
        - error_description
    InvalidDatasetSchemaError:
      type: object
      description: >-
        A dataset attached to the taxonomy element has a schema the connector
        cannot use. `debug` holds the

        validation errors keyed by dataset id.
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
        debug:
          description: Validation errors keyed by dataset id.
      required:
        - debug
        - detail
        - instance
        - status
        - title
        - type
    ForbiddenError:
      type: object
      description: >-
        The token is missing, invalid or expired, or the company has not
        installed the app. A request without an

        `Authorization: Bearer` header gets an empty body.
      properties:
        error:
          type: string
          description: '`forbidden` or `app_not_installed`.'
        error_description:
          type: string
    UpstreamError:
      type: object
      description: The Narrative API or The Trade Desk API failed.
      properties:
        error:
          type: string
          description: '`upstream_error`.'
        error_description:
          type: string
      required:
        - error
        - error_description
    CreateDataRateRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateDataRateRequestAdvertiser'
        - $ref: '#/components/schemas/CreateDataRateRequestPartner'
        - $ref: '#/components/schemas/CreateDataRateRequestSystem'
      discriminator:
        propertyName: type
        mapping:
          create_data_rate_advertiser: '#/components/schemas/CreateDataRateRequestAdvertiser'
          create_data_rate_partner: '#/components/schemas/CreateDataRateRequestPartner'
          create_data_rate_system: '#/components/schemas/CreateDataRateRequestSystem'
    TaxonomyElementConnection:
      description: A dataset attached to a taxonomy element.
      oneOf:
        - $ref: '#/components/schemas/TaxonomyElementConnectionDraft'
        - $ref: '#/components/schemas/TaxonomyElementConnectionSynchronized'
      discriminator:
        propertyName: type
        mapping:
          connection_draft: '#/components/schemas/TaxonomyElementConnectionDraft'
          connection_synchronized: '#/components/schemas/TaxonomyElementConnectionSynchronized'
    DataRate:
      description: >-
        A data rate on a taxonomy element. The variant says who the rate applies
        to.
      oneOf:
        - $ref: '#/components/schemas/DataRateAdvertiser'
        - $ref: '#/components/schemas/DataRatePartner'
        - $ref: '#/components/schemas/DataRateSystem'
      discriminator:
        propertyName: type
        mapping:
          data_rate_advertiser: '#/components/schemas/DataRateAdvertiser'
          data_rate_partner: '#/components/schemas/DataRatePartner'
          data_rate_system: '#/components/schemas/DataRateSystem'
    TaxonomyElementStatistics:
      type: object
      properties:
        active_ids_count:
          type: integer
          format: int64
        active_ids_count_expanded:
          type: boolean
        audience_size:
          type: integer
          format: int64
        received_ids_count:
          type: integer
          format: int64
        updated_at:
          type: string
          format: date-time
          nullable: true
      required:
        - active_ids_count
        - active_ids_count_expanded
        - audience_size
        - received_ids_count
        - updated_at
    ElementStatus:
      type: string
      enum:
        - archived
        - active
        - draft
        - pending
    ComplianceStatus:
      type: string
      description: >-
        The Trade Desk compliance review status. Values use The Trade Desk's
        casing.
      enum:
        - Approved
        - Denied
        - NotInQueue
        - Pending
    CreateDataRateRequestAdvertiser:
      allOf:
        - $ref: '#/components/schemas/CreateAdvertiserDataRateRequest'
        - $ref: '#/components/schemas/CreateDataRateRequestMixin'
    CreateDataRateRequestPartner:
      allOf:
        - $ref: '#/components/schemas/CreatePartnerDataRateRequest'
        - $ref: '#/components/schemas/CreateDataRateRequestMixin'
    CreateDataRateRequestSystem:
      allOf:
        - $ref: '#/components/schemas/CreateSystemDataRateRequest'
        - $ref: '#/components/schemas/CreateDataRateRequestMixin'
    TaxonomyElementConnectionDraft:
      allOf:
        - $ref: '#/components/schemas/DraftConnection'
        - $ref: '#/components/schemas/TaxonomyElementConnectionMixin'
    TaxonomyElementConnectionSynchronized:
      allOf:
        - $ref: '#/components/schemas/SynchronizedConnection'
        - $ref: '#/components/schemas/TaxonomyElementConnectionMixin'
    DataRateAdvertiser:
      allOf:
        - $ref: '#/components/schemas/AdvertiserDataRate'
        - $ref: '#/components/schemas/DataRateMixin'
    DataRatePartner:
      allOf:
        - $ref: '#/components/schemas/PartnerDataRate'
        - $ref: '#/components/schemas/DataRateMixin'
    DataRateSystem:
      allOf:
        - $ref: '#/components/schemas/SystemDataRate'
        - $ref: '#/components/schemas/DataRateMixin'
    CreateAdvertiserDataRateRequest:
      type: object
      properties:
        cpm_rate:
          type: number
          format: double
        percent_of_media_cost_rate:
          type: number
          maximum: 9.99
          minimum: 0
          format: double
        rate_type:
          $ref: '#/components/schemas/RateType'
        advertiser_id:
          type: string
          description: The Trade Desk advertiser id.
      required:
        - advertiser_id
        - cpm_rate
        - percent_of_media_cost_rate
        - rate_type
    CreateDataRateRequestMixin:
      type: object
      properties:
        type:
          type: string
      required:
        - type
    CreatePartnerDataRateRequest:
      type: object
      properties:
        cpm_rate:
          type: number
          format: double
        percent_of_media_cost_rate:
          type: number
          maximum: 9.99
          minimum: 0
          format: double
        rate_type:
          $ref: '#/components/schemas/RateType'
        partner_id:
          type: string
          description: The Trade Desk partner id.
      required:
        - cpm_rate
        - partner_id
        - percent_of_media_cost_rate
        - rate_type
    CreateSystemDataRateRequest:
      type: object
      properties:
        cpm_rate:
          type: number
          format: double
        percent_of_media_cost_rate:
          type: number
          maximum: 9.99
          minimum: 0
          format: double
        rate_type:
          $ref: '#/components/schemas/RateType'
      required:
        - cpm_rate
        - percent_of_media_cost_rate
        - rate_type
    DraftConnection:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        dataset_id:
          type: integer
          description: Narrative dataset id.
          format: int64
        status:
          $ref: '#/components/schemas/DraftConnectionStatus'
        updated_at:
          type: string
          format: date-time
      required:
        - created_at
        - dataset_id
        - status
        - updated_at
    TaxonomyElementConnectionMixin:
      type: object
      properties:
        type:
          type: string
      required:
        - type
    SynchronizedConnection:
      type: object
      properties:
        connection_id:
          type: string
          description: Connection Id must be in UUID format.
        connection_status:
          $ref: '#/components/schemas/ConnectionStatus'
        created_at:
          type: string
          format: date-time
        dataset_id:
          type: integer
          description: Narrative dataset id.
          format: int64
        status:
          $ref: '#/components/schemas/SynchronizedConnectionStatus'
        updated_at:
          type: string
          format: date-time
      required:
        - connection_id
        - connection_status
        - created_at
        - dataset_id
        - status
        - updated_at
    AdvertiserDataRate:
      type: object
      properties:
        batch:
          description: Null until the rate has been sent to The Trade Desk.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DataRateBatch'
        cpm_rate:
          type: number
          format: double
        element_id:
          type: string
        percent_of_media_cost_rate:
          type: number
          format: double
          nullable: true
        rate_type:
          $ref: '#/components/schemas/RateType'
        advertiser_id:
          type: string
          description: The Trade Desk advertiser id.
      required:
        - advertiser_id
        - batch
        - cpm_rate
        - element_id
        - percent_of_media_cost_rate
        - rate_type
    DataRateMixin:
      type: object
      properties:
        type:
          type: string
      required:
        - type
    PartnerDataRate:
      type: object
      properties:
        batch:
          description: Null until the rate has been sent to The Trade Desk.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DataRateBatch'
        cpm_rate:
          type: number
          format: double
        element_id:
          type: string
        percent_of_media_cost_rate:
          type: number
          format: double
          nullable: true
        rate_type:
          $ref: '#/components/schemas/RateType'
        partner_id:
          type: string
          description: The Trade Desk partner id.
      required:
        - batch
        - cpm_rate
        - element_id
        - partner_id
        - percent_of_media_cost_rate
        - rate_type
    SystemDataRate:
      type: object
      properties:
        batch:
          description: Null until the rate has been sent to The Trade Desk.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DataRateBatch'
        cpm_rate:
          type: number
          format: double
        element_id:
          type: string
        percent_of_media_cost_rate:
          type: number
          format: double
          nullable: true
        rate_type:
          $ref: '#/components/schemas/RateType'
      required:
        - batch
        - cpm_rate
        - element_id
        - percent_of_media_cost_rate
        - rate_type
    RateType:
      type: string
      enum:
        - cpm
        - percent_of_media_cost
        - hybrid
    DraftConnectionStatus:
      type: string
      enum:
        - archived
        - draft
    ConnectionStatus:
      type: string
      enum:
        - active
        - archived
    SynchronizedConnectionStatus:
      type: string
      enum:
        - archived
        - synchronized
    DataRateBatch:
      type: object
      description: The Trade Desk data-rate batch the rate was sent in.
      properties:
        id:
          type: string
        approval_status:
          type: string
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ApprovalStatus'
        created_at:
          type: string
          format: date-time
          nullable: true
        estimated_process_at:
          type: string
          format: date-time
          nullable: true
        processed_at:
          type: string
          format: date-time
          nullable: true
        processing_status:
          type: string
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ProcessingStatus'
        updated_at:
          type: string
          format: date-time
          nullable: true
      required:
        - approval_status
        - created_at
        - estimated_process_at
        - id
        - processed_at
        - processing_status
        - updated_at
    ApprovalStatus:
      type: string
      enum:
        - not_reviewed
        - approved
        - denied
    ProcessingStatus:
      type: string
      enum:
        - not_started
        - in_progress
        - successful
        - failed
  securitySchemes:
    smithy.api.httpBearerAuth:
      type: http
      description: HTTP Bearer authentication
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.