openapi: 3.0.1
info:
  title: Canto PIM bulk_products_catalogs product_catalogs 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: product_catalogs
paths:
  /product_catalogs:
    get:
      tags:
      - product_catalogs
      summary: Get Product Catalogs
      description: '    Retrieve a list of all product catalogs

        '
      operationId: get_api_v1_product_catalogs
      responses:
        '200':
          description: Successfully fetched Product Catalogs
          headers:
            page-items:
              description: Number of items per page
              schema:
                type: integer
            link:
              description: Standard link header defined in RFC 8228. Contains links for first, last, next, and prev pages with respective `rel` attributes
              schema:
                type: string
            current-page:
              description: Current page number
              schema:
                type: integer
            total-count:
              description: Total number of items
              schema:
                type: integer
            total-pages:
              description: Total number of pages
              schema:
                type: integer
          content:
            '*/*':
              schema:
                required:
                - product_catalogs
                type: object
                properties:
                  product_catalogs:
                    type: array
                    description: Array of Product Catalogs
                    items:
                      type: string
                additionalProperties: false
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '500':
          description: Something went wrong
          content: {}
    post:
      tags:
      - product_catalogs
      summary: Create Product Catalog
      description: '    Create a new product catalog

        '
      operationId: post_api_v1_product_catalogs
      requestBody:
        content:
          application/json:
            schema:
              required:
              - name
              type: object
              properties:
                name:
                  type: string
                  description: Product Catalog Name
                summary:
                  type: string
                  description: Product Catalog Summary
          multipart/form-data:
            schema:
              required:
              - name
              type: object
              properties:
                name:
                  type: string
                  description: Product Catalog Name
                summary:
                  type: string
                  description: Product Catalog Summary
        required: true
      responses:
        '200':
          description: Successfully created Product Catalog
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/catalog'
        '400':
          description: The request parameters were invalid. References to `nil` means empty string or `null` value
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '422':
          description: There was an error creating your Product Catalog
          content: {}
        '500':
          description: Something went wrong
          content: {}
  /product_catalogs/{id}:
    get:
      tags:
      - product_catalogs
      summary: Get Product Catalog
      description: '    Fetch a specific product catalog by ID

        '
      operationId: get_api_v1_product_catalogs_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Successfully fetched Product Catalog
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/catalog'
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Product Catalog ID not found
          content: {}
        '500':
          description: Something went wrong
          content: {}
    put:
      tags:
      - product_catalogs
      summary: Update Product Catalog
      description: '    Completely update an existing product catalog

        '
      operationId: put_api_v1_product_catalogs_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Product Catalog Name
                summary:
                  type: string
                  description: Product Catalog Summary
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Product Catalog Name
                summary:
                  type: string
                  description: Product Catalog Summary
      responses:
        '200':
          description: Successfully updated Product Catalog
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/catalog'
        '400':
          description: The request parameters were invalid. References to `nil` means empty string or `null` value
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Product Catalog ID not found
          content: {}
        '422':
          description: There was an error updating your Product Catalog
          content: {}
        '500':
          description: Something went wrong
          content: {}
    delete:
      tags:
      - product_catalogs
      summary: Delete Product Catalog
      description: '    Delete a specific product catalog

        '
      operationId: delete_api_v1_product_catalogs_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: number
      responses:
        '204':
          description: Successfully Deleted Product Catalog
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Product Catalog ID not found
          content: {}
        '422':
          description: There was an error throwing your Product Catalog in the trash
          content: {}
        '500':
          description: Something went wrong
          content: {}
    patch:
      tags:
      - product_catalogs
      summary: Update Product Catalog
      description: '    Update specifics of a product catalog

        '
      operationId: patch_api_v1_product_catalogs_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Product Catalog Name
                summary:
                  type: string
                  description: Product Catalog Summary
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Product Catalog Name
                summary:
                  type: string
                  description: Product Catalog Summary
      responses:
        '200':
          description: Successfully updated Product Catalog
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/catalog'
        '400':
          description: The request parameters were invalid. References to `nil` means empty string or `null` value
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Product Catalog ID not found
          content: {}
        '422':
          description: There was an error updating your Product Catalog
          content: {}
        '500':
          description: Something went wrong
          content: {}
components:
  schemas:
    catalog:
      required:
      - banner_asset_id
      - created_at
      - id
      - product_attribute_view_id
      - product_channel_id
      - updated_at
      - user_id
      type: object
      properties:
        id:
          type: number
          description: Product Catalog ID
        name:
          type: string
          description: Product Catalog Name
        summary:
          type: string
          description: Product Catalog Summary
        product_attribute_view_id:
          type: number
          description: ID Of Product Attribute View associated with this Catalog
        created_at:
          type: string
          description: Product Catalog Created At
        updated_at:
          type: string
          description: Product Catalog Updated At
        banner_asset_id:
          type: string
          description: ID of Banner Asset of this Catalog Banner
        user_id:
          type: string
          description: ID of User who created this Catalog
        product_channel_id:
          type: number
          description: ID of Product Channel associated with this Catalog for exports
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AccessToken
x-original-swagger-version: '2.0'