openapi: 3.0.1
info:
  title: Canto PIM bulk_products_catalogs options API
  description: "\n[Canto APIs](https://api.canto.com) enable seamless synchronization between the PIM + DAM and external systems that rely on accurate, up-to-date product content. \nThe API outlined here provides programmatic access to Canto’s Product Hub (PIM).  The Product Hub API allows authorized systems to create, retrieve, update, and manage rich product data for use across digital channels, e-commerce platforms, and other target or source systems. \n \n<b>Key Capabilities</b><br />\nThe Canto Product Hub API enables full product data management:\n1. Product Record Management:  Create, read, update, and delete product entries including structured metadata, taxonomy, categories, and references.\n2. Attribute & Schema Configuration:  Access and manage custom product attributes and classification structures\n3. Webhooks:  Trigger updates or publish product datasets to downstream systems and integration pipelines.\n \n<b>API Design</b>\n- The PIM API adheres to <b>RESTful principles</b>, supporting standard HTTP methods (GET, POST, PUT, PATCH, DELETE).\n- JSON is the default payload format for both requests and responses.\n\n<b>HTTP Status Code Conventions</b><br />\nBelow are general HTTP codes applicable across most endpoints:<br />\n- <b>200, 201, 204</b> – Successful operations (retrieval, creation, update, deletion).\n- <b>400</b> – Bad request. Input payloads did not conform to the expected schema or required parameters were missing.\n- <b>401 / 403</b> – Authentication or authorization failed.\n- <b>404</b> – The route or resource was not found.\n- <b>409</b> – Conflict in resource state (e.g., duplicate product identifier).\n- <b>429</b> - Too many requests. See Rate Limits below.\n- <b>500</b> – An unexpected server error occurred.\n- <b>502 / 503 / 504</b> – Infrastructure issues such as load balancer, service unavailability, or timeouts.\n\n<b>API Rate Limits</b><br />\nRate limits are how many API calls you can make in a given time frame. If your call exceeds the pre-defined rate limit, you will run into a “429” http error-code. After which, you will need to wait until you can make another API call.\n\n<b>PIM API Rate Limit:</b> 5 requests/second\n"
  version: v1.0.1
servers:
- url: https://{tenantSubdomain}.{region}/api/v1/pim/
  variables:
    tenantSubdomain:
      default: demo
    region:
      enum:
      - canto.com
      - canto.global
      - canto.de
      - au.canto.com
      - ca.canto.com
      default: canto.com
security:
- bearerAuth: []
tags:
- name: options
paths:
  /dimensions/{dimension_id}/options/{id}:
    put:
      tags:
      - options
      summary: Update Dimension Option
      description: '    Update the value of an option within a dimension

        '
      operationId: put_api_v1_dimensions_dimension_id_options_id
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: number
      - name: id
        in: path
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Dimension Option Name
                position:
                  type: string
                  description: Dimension Option Position
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Dimension Option Name
                position:
                  type: string
                  description: Dimension Option Position
      responses:
        '200':
          description: Successfully updated Dimension Option
          content:
            '*/*':
              schema:
                required:
                - id
                type: object
                properties:
                  id:
                    type: number
                    description: Dimension Option ID
                  name:
                    type: string
                    description: Dimension Option Name
                  position:
                    type: string
                    description: Dimension Option Position
                additionalProperties: false
        '400':
          description: The request was invalid
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Dimension or Option ID not found
          content: {}
        '422':
          description: There was an error updating your Dimension Option
          content: {}
        '500':
          description: Something went wrong
          content: {}
    patch:
      tags:
      - options
      summary: Update Dimension Option
      description: '    Update the value of an option within a dimension

        '
      operationId: patch_api_v1_dimensions_dimension_id_options_id
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: number
      - name: id
        in: path
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Dimension Option Name
                position:
                  type: string
                  description: Dimension Option Position
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Dimension Option Name
                position:
                  type: string
                  description: Dimension Option Position
      responses:
        '200':
          description: Successfully updated Dimension Option
          content:
            '*/*':
              schema:
                required:
                - id
                type: object
                properties:
                  id:
                    type: number
                    description: Dimension Option ID
                  name:
                    type: string
                    description: Dimension Option Name
                  position:
                    type: string
                    description: Dimension Option Position
                additionalProperties: false
        '400':
          description: The request was invalid
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Dimension or Option ID not found
          content: {}
        '422':
          description: There was an error updating your Dimension Option
          content: {}
        '500':
          description: Something went wrong
          content: {}
  /dimensions/{dimension_id}/options:
    post:
      tags:
      - options
      summary: Create Dimension Option
      description: '    Add a new option to a dimension

        '
      operationId: post_api_v1_dimensions_dimension_id_options
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              required:
              - name
              type: object
              properties:
                name:
                  type: string
                  description: Dimension Option Name
                position:
                  type: string
                  description: Dimension Option Position
          multipart/form-data:
            schema:
              required:
              - name
              type: object
              properties:
                name:
                  type: string
                  description: Dimension Option Name
                position:
                  type: string
                  description: Dimension Option Position
        required: true
      responses:
        '200':
          description: Successfully created Dimension Option
          content:
            '*/*':
              schema:
                required:
                - id
                - name
                type: object
                properties:
                  id:
                    type: number
                    description: Dimension Option ID
                  name:
                    type: string
                    description: Dimension Option Name
                  position:
                    type: string
                    description: Dimension Option Position
                additionalProperties: false
        '400':
          description: The request was invalid
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '422':
          description: There was an error creating your Dimension Option
          content: {}
        '500':
          description: Something went wrong
          content: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AccessToken
x-original-swagger-version: '2.0'