Blueshift Catalog API

openapi: 3.2.0
info:
  description: These APIs will help you manage different workflows in Blueshift. Our powerful REST APIs provide an easy way to integrate your data and third party applications with Blueshift.
  version: 1.0.0
  title: Blueshift Catalog API
  contact:
    email: support@getblueshift.com
servers:
- url: https://api.getblueshift.com
- url: https://api.eu.getblueshift.com
tags:
- name: Catalog
  description: A catalog is a list of items which may include content or products.
paths:
  /api/v1/catalogs:
    get:
      summary: Get list of catalogs
      description: Use this endpoint to get a list of all catalogs.
      tags:
      - Catalog
      security:
      - user_api_auth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  catalogs:
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                          description: The catalog's UUID.
                          example: dd0d2987-9e57-47d4-9380-8a3e959cbe8e
                        name:
                          type: string
                          description: The name of the catalog.
                          example: Books
                        catalog_type:
                          type: string
                          description: The type of the catalog.
                          example: ecommerce
                        upload_method:
                          type: string
                          description: The method that you use to upload the catalog to our platform.
                          example: file
                        url:
                          type: string
                          description: The URL of the catalog on your site.
                          example: https://www.example.com/catalog/books
                        update_frequency:
                          type: string
                          description: The frequency at which our platform receives data from your service to update the catalog.
                          example: daily
                        product_price_column_name:
                          type: string
                          description: The name of the column in the database that lists the products' prices.
                          example: price
                        product_name_column_name:
                          type: string
                          description: The name of the column in the database that lists the products' names.
                          example: title
                        product_id_column_name:
                          type: string
                          description: The name of the column in the database that lists the products' IDs.
                          example: sku
                        product_image_column_name:
                          type: string
                          description: The name of the column in the database that lists the URLs of the products' images.
                          example: image_url
                        product_msrp_column_name:
                          type: string
                          description: The name of the column in the database that lists the products' maximum selling price.
                          example: msrp
                        product_url_column_name:
                          type: string
                          description: The name of the column in the database that lists the products' URLs.
                          example: product_url
                        last_processed:
                          type: string
                          format: date-time
                          description: The timestamp when the catalog was last updated in ISO 8601 format.
                          example: '2024-10-03T04:58:34.000Z'
                        catalog_headers:
                          type: array
                          example: '"title", "price", "image_url", "author", "isbn", "on_sale_date", "url", "sku", "itemformat", "language", "saleStatus", "consumerImprint", "formatFamily", "pages", "subject"'
                          items:
                            type: string
                        status:
                          type: string
                          example: success
                        product_count:
                          type: integer
                          description: The number of items in the catalog.
                          example: 9882
                        product_category_column_name:
                          type: array
                          example: '"subject"'
                          items:
                            type: string
                        file_settings:
                          type: array
                          items:
                            type: string
                          example: ''
                        category_options:
                          type: array
                          items:
                            type: string
                          example: ''
                        product_tag_column_name:
                          type: array
                          items:
                            type: string
                            example: tags
                        tag_options:
                          type: string
                          example: ''
                        product_brand_column_name:
                          type: string
                          description: The name of the column in the database that lists the product brand.
                          example: author
                        is_passive:
                          type: boolean
                          description: Indicates the availability of the product.
                          example: true
                        is_active:
                          type: boolean
                          description: Indicates the availability of the product.
                          example: true
                        product_start_date_column_name:
                          type: string
                          description: The name of the column in the database that indicates the start date on which a product will be available.
                          example: on_sale_date
                        product_end_date_column_name:
                          type: string
                          description: The name of the column in the database that indicates the last date on which a product will be available.
                          example: on_sale_end_date
                        parent_sku_column_name:
                          type: string
                          description: The name of the column in the database that lists the parent sku that ties all variants or child products together.
                          example: parent_sku
                        product_inventory_column_name:
                          type: string
                          description: The name of the column in the database that lists the product inventory.
                        default_root_category:
                          type: string
                          description: The default root category for the catalog.
                        start_at:
                          type: string
                          format: date-time
                          description: The date and time at which the catalog becomes available.
                        end_at:
                          type: string
                          format: date-time
                          description: The date and time at which the catalog in no longer available.
                        archived:
                          type: boolean
                          description: Indicates if the catalog is archived.
                          example: false
                        author:
                          type: string
                          description: The user who created the catalog.
                          example: John Doe
                        access_key:
                          type: string
                          description: The access key used to create the catalog.
                          example: your_secure_access_key_here
                        file_options:
                          type: object
                          properties:
                            format:
                              type: string
                              description: The format of the catalog file.
                              example: csv
                            col_sep:
                              type: string
                              description: The separator used in the csv file.
                              example: '|'
                            encoding:
                              type: string
                              description: The encoding for the csv file.
                              example: utf-8
                        error_access_key:
                          type: string
                          description: The access key for errors.
                        catalog_file_name:
                          type: string
                          description: The filename of the uploaded catalog file.
                          example: products.csv
                        login:
                          type: string
                          description: The user login for the catalog.
                        password:
                          type: string
                          description: The password for the catalog.
                        host:
                          type: string
                        path:
                          type: string
                        port:
                          type: string
                        s3_access_key:
                          type: string
                          description: The access key for the S3 bucket from which the catalog is uploaded.
                          example: ABCDEFPLOI7NY4NP5KON
                        secret_access_key:
                          type: string
                          description: The secret access key for the S3 bucket from which the catalog is uploaded.
                        bucket:
                          type: string
                          description: The name of the S3 bucket from which the catalog is uploaded.
                        s3_path:
                          type: string
                          description: The path for the S3 bucket from which the catalog is uploaded.
                        s3_aws_region:
                          type: string
                          description: The region for the S3 bucket from which the catalog is uploaded.
                          example: us-west-2
                        sftp_login:
                          type: string
                          description: The region for the S3 bucket from which the catalog is uploaded.
                        sftp_password:
                          type: string
                          description: The sftp password for the location from which the catalog is uploaded.
                        sftp_port:
                          type: string
                          description: The sftp port for the location from which the catalog is uploaded.
                        sftp_path:
                          type: string
                          description: The sftp folder path for the location from which the catalog is uploaded.
                        sftp_host:
                          type: string
                          description: The sftp host for the location from which the catalog is uploaded.
                        last_catalog_file:
                          type: object
                          description: Last catalog upload details for recurring catalog uploads.
                          properties:
                            id:
                              type: string
                              description: The ID for the file last uploaded for the catalog.
                              example: '332983'
                            uuid:
                              type: string
                              description: The catalog's UUID.
                              example: 7fbea614-c257-4745-a1cb-22f6d7b87f74
                            catalog_id:
                              type: string
                              description: The catalog ID.
                              example: '2151'
                            file_name:
                              type: string
                              description: The file name of the file last uploaded for the catalog.
                              example: products.csv
                            total_records:
                              type: string
                              description: Total number of records in uploaded file.
                              example: '9882'
                            processed_records:
                              type: string
                              description: Total number of records processed.
                              example: '9882'
                            errored_records:
                              type: string
                              description: Number of records that resulted in an error.
                              example: '0'
                            status:
                              type: string
                              description: The status of the file upload.
                              example: success
                            created_at:
                              type: string
                              format: date-time
                              description: The date and time for the upload.
                              example: '2018-10-03T04:57:24.000Z'
                            updated_at:
                              type: string
                              format: date-time
                              description: The date and time for the upload.
                              example: '2018-10-03T04:58:34.000Z'
                            s3_key:
                              type: string
                              description: The access key ID to access your S3 folder.
                              example: your_secure_access_key_here
                            error_file_s3_key:
                              type: string
        '400':
          description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
        '401':
          description: Unauthorized - API authentication failed due to an invalid or missing API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '403':
          description: Forbidden - The API key does not have sufficient permissions to perform this action.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Forbidden
        '404':
          description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists.
        '409':
          description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff.
        '413':
          description: "You can upload maximum 50 users in one api call\t- The server is refusing to process a request because the request payload is larger than the server is willing or able to process."
        '422':
          description: Unprocessable Entity - The request was well-formed but contains semantic errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Validation failed
        '429':
          description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com for recommended throughput."
        '500':
          description: "Internal Server Error\t- Please contact blueshift for more information."
        '502':
          description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff.
        '503':
          description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff.
        '504':
          description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff.
    post:
      summary: Create a catalog
      description: Create a catalog in Blueshift.
      tags:
      - Catalog
      security:
      - user_api_auth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                catalog:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Specify a name for the catalog that you want to create. Ensure that the value that provide in this field is unique.
                      example: Winter Collection
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  catalog_uuid:
                    type: string
                    description: The UUID of the catalog that got created.
                    example: 0215377e-71c2-4a4f-8ec2-3a7d04ad0461
        '400':
          description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized - API authentication failed due to an invalid or missing API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '403':
          description: Forbidden - The API key does not have sufficient permissions to perform this action.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Forbidden
        '404':
          description: Not Found - The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
        '422':
          description: Unprocessable Entity - The request was well-formed but contains semantic errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Validation failed
        '429':
          description: Too Many Requests - The request limit has been exceeded. Reduce request frequency.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too Many Requests
        '500':
          description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
        '502':
          description: Bad Gateway - The server received an invalid response. Retry the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bad Gateway
        '503':
          description: Service Unavailable - The service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Service Unavailable
        '504':
          description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Gateway Timeout
  /api/v1/catalogs/{catalog_uuid}.json:
    get:
      summary: Get catalog details
      description: Use this endpoint to get the details of one catalog at a time.
      tags:
      - Catalog
      security:
      - user_api_auth: []
      parameters:
      - in: path
        required: true
        name: catalog_uuid
        description: Specify the UUID of the catalog. You can get the catalog's UUID from its URL. For example, if you open a catalog on the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/catalogs/<CATALOG_UUID>/details`.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    description: The catalog's UUID.
                    example: 1234asdfjh-asdfjh123425-asdjk1234
                  name:
                    type: string
                    description: The name of the catalog.
                  catalog_type:
                    type: string
                    description: The type of the catalog for example, `e-commerce`.
                  url:
                    type: string
                    description: The URL of the catalog on your site.
                  upload_method:
                    type: string
                    description: The method that you use to upload the catalog to our platform. For example, `api`, `file`.
                    example: api
                  update_frequency:
                    type: integer
                    description: The frequency at which our platform receives data from your service to update the catalog.
                  product_price_column_name:
                    type: string
                    description: The name of the column in the database that lists the products' prices.
                  product_name_column_name:
                    type: string
                    description: The name of the column in the database that lists the products' names.
                  product_id_column_name:
                    type: string
                    description: The name of the column in the database that lists the products' IDs.
                  product_image_column_name:
                    type: string
                    description: The name of the column in the database that lists the URLs of the products' images.
                  product_msrp_column_name:
                    type: string
                    description: The name of the column in the database that lists the products' maximum selling price.
                  product_url_column_name:
                    type: string
                    description: The name of the column in the database that lists the products' URLs.
                  last_processed:
                    type: string
                    format: date-time
                    description: The timestamp when the catalog was last updated in ISO 8601 format.
        '400':
          description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        product_id:
                          type: string
                          description: can't be blank
        '401':
          description: Unauthorized - API authentication failed due to an invalid or missing API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not authorized
        '403':
          description: Forbidden - The API key does not have sufficient permissions to perform this action.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Forbidden
        '404':
          description: Not Found - The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
        '413':
          description: "You can upload maximum 100 products in one api call\t- The server is refusing to process a request because the request payload is larger than the server is willing or able to process."
        '422':
          description: Unprocessable Entity - Some/all of the products have invalid data, please check the response for more information on.
        '429':
          description: "Rate limit exceeded\t- Too many requests"
        '500':
          description: "Internal Server Error\t- Please contact blueshift for more information"
        '502':
          description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff
        '503':
          description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff
        '504':
          description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff
    put:
      summary: Add items to a catalog
      description: Use this endpoint to add items to a catalog.
      tags:
      - Catalog
      security:
      - user_api_auth: []
      parameters:
      - in: path
        required: true
        name: catalog_uuid
        description: Specify the UUID of the catalog to which you want to add the items. You can get the catalog's UUID from its URL. For example, if you open a catalog on the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/catalogs/<CATALOG_UUID>/details`.
        schema:
          type: string
        example: 89ee8378-a887-474b-8afe-e2369cc9297c
      - name: syncUpdateWithProductData
        description: Optional query parameter. When set to `true`, the API returns the product_id and UUID for products that are added successfully. When set to `false` or not provided, returns a simple status response.
        in: query
        schema:
          type: boolean
        example: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                catalog:
                  type: object
                  properties:
                    products:
                      type: array
                      description: Specify the items that you want to add to the catalog.
                      items:
                        type: object
                        required:
                        - image
                        - product_id
                        - title
                        - web_link
                        - availability
                        - category
                        additionalProperties: true
                        properties:
                          brand:
                            type: string
                            description: Specify the brand name of the item.
                            example: TechBrand
                          category:
                            type: array
                            items:
                              type: string
                            description: Specify the category identifiers starting from the root of the taxonomy.
                            example:
                            - Electronics
                            - Electronics > Laptops
                          image:
                            type: string
                            description: Specify the link to the image of the item. Ensure that the URL that you provide in this field does not contain more than 500 characters.
                            example: https://example.com/images/product.jpg
                          msrp:
                            type: string
                            description: Specify the maximum suggested retail price of the item (numeric value without currency symbol).
                            example: '999.99'
                          price:
                            type: string
                            description: Specify the selling price of an item (numeric value without currency symbol).
                            example: '899.99'
                          product_id:
                            type: string
                            description: Specify the unique identifier of the item. This is what you pass in the product_ids in your events, and the values specified here must be the same. Ensure that the value that you provide in this field does not contain more than 64 characters.
                            example: PROD123456
                          availability:
                            type: string
                            description: Specify the availability of the item.
                            example: in_stock
                          tags:
                            type: array
                            description: Specify an array of strings denoting grouping of similar products into collections or groups.
                            items:
                              type: string
                            example:
                            - bestseller
                            - premium
                          parent_sku:
                            type: string
                            description: Provide the SKU to tie all variants or child products together.
                            example: SKU-PARENT-001
                          title:
                            type: string
                            description: Specify the title of the item. Ensure that the title that you provide in this field does not contain more than 255 characters.
                            example: Premium Laptop 15-inch
                          web_link:
                            type: string
                            description: Specify the URL of the item on your website. Ensure that the URL that you provide in this field does not contain more than 500 characters.
          

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/blueshift/refs/heads/main/openapi/blueshift-catalog-api-openapi.yml