openapi: 3.0.1
info:
  title: Canto PIM bulk_products_catalogs product_share_links 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_share_links
  description: 'Product Share Links allow you to create shareable links for products that can be accessed

    outside the PIM system. These links can have custom names and optionally expire.

    '
paths:
  /product_share_links:
    get:
      tags:
      - product_share_links
      summary: Get Product Share Links
      description: '    List all shareable links created for product pages

        '
      operationId: get_api_v1_product_share_links
      responses:
        '200':
          description: List of product Share Links
          content:
            '*/*':
              schema:
                required:
                - product_share_links
                type: object
                properties:
                  product_share_links:
                    type: array
                    description: Array of Product Share Links
                    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_share_links
      summary: Create Product Share Link
      description: '    Generate a new share link for a product.

        '
      operationId: post_api_v1_product_share_links
      requestBody:
        content:
          application/json:
            schema:
              required:
              - product_id
              type: object
              properties:
                product_id:
                  type: number
                  description: ID of the Product to share
                custom_name:
                  type: string
                  description: Optional custom name for the Share Link
                expiration_date:
                  type: string
                  description: Optional expiration date for the Share Link
          multipart/form-data:
            schema:
              required:
              - product_id
              type: object
              properties:
                product_id:
                  type: number
                  description: ID of the Product to share
                custom_name:
                  type: string
                  description: Optional custom name for the Share Link
                expiration_date:
                  type: string
                  description: Optional expiration date for the Share Link
        required: true
      responses:
        '201':
          description: Successfully created Share Link
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/product_share_link_properties'
        '400':
          description: The request parameters were invalid
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '422':
          description: There was an error creating the Share Link
          content: {}
        '500':
          description: Something went wrong
          content: {}
  /product_share_links/{id}:
    get:
      tags:
      - product_share_links
      summary: Get Product Share Link
      description: '    Get details of a specific share link.

        '
      operationId: get_api_v1_product_share_links_id
      parameters:
      - name: id
        in: path
        description: Share Link ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Share Link details
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/product_share_link_properties'
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Share Link ID not found
          content: {}
        '500':
          description: Something went wrong
          content: {}
    delete:
      tags:
      - product_share_links
      summary: Delete Product Share Link
      description: '    Remove a product share link

        '
      operationId: delete_api_v1_product_share_links_id
      parameters:
      - name: id
        in: path
        description: Share Link ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: Share Link successfully deleted
          content: {}
        '401':
          description: User is not permitted to use the API or Authentication is invalid
          content: {}
        '404':
          description: Share Link ID not found
          content: {}
        '422':
          description: There was an error deleting the Share Link
          content: {}
        '500':
          description: Something went wrong
          content: {}
components:
  schemas:
    product_share_link_properties:
      required:
      - custom_name
      - expiration_date
      - id
      - identifier
      - product_id
      - url
      - user_id
      type: object
      properties:
        id:
          type: number
          description: Share Link ID
        product_id:
          type: number
          description: ID of the shared Product
        identifier:
          type: string
          description: Unique identifier for the Share Link
        custom_name:
          type: string
          description: Custom name for the Share Link
        expiration_date:
          type: string
          description: Expiration date for the Share Link
        url:
          type: string
          description: Generated shareable URL
        user_id:
          type: number
          description: ID of the user who created the Share Link
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AccessToken
x-original-swagger-version: '2.0'