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

# Upload a product catalog

> Uploads a JSON file containing a product catalog.

To update the product catalog, upload a file with the updated product data.

Required scopes: accounts--my:ro


## OpenAPI

````yaml /text.json post /v1/catalogs/imports
openapi: 3.0.0
info:
  title: Product Directory API
  description: >-
    A service for uploading and managing a product catalog for use by an AI
    agent.
  version: 1.0.0
servers:
  - url: https://api.text.com/product-directory
    description: Main production server URL
security:
  - PersonalAccessToken: []
paths:
  /v1/catalogs/imports:
    post:
      tags:
        - Catalog
      summary: Upload a product catalog
      description: >-
        Uploads a JSON file containing a product catalog.


        To update the product catalog, upload a file with the updated product
        data.
      operationId: upload-a-product-catalog
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadCatalogRequest'
      responses:
        '202':
          description: >-
            The catalog import job was queued. A `202` response doesn't mean the
            products passed validation — invalid products are skipped and
            counted in `failed_count` on the job status; they aren't rejected at
            upload time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadCatalogResponse'
              example:
                job_id: 550e8400-e29b-41d4-a716-446655440000
        '401':
          description: Missing or invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: authentication
                  message: No Authorization header.
        '413':
          description: The file exceeds the 50MB request size limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: entity_too_large
                  message: max_file_size_exceeded
        '422':
          description: The file isn't valid, or its filename doesn't end in `.json`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_file:
                  summary: File isn't valid JSON, or isn't a non-empty JSON array
                  value:
                    error:
                      type: validation
                      message: invalid_file
                unsupported_format:
                  summary: Filename doesn't end in .json
                  value:
                    error:
                      type: validation
                      message: unsupported_format
components:
  schemas:
    UploadCatalogRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: >-
            A JSON file containing an array of product objects. The filename
            must end in `.json`. Maximum size: 50MB. The file is processed
            asynchronously — the response includes a `job_id` for tracking
            progress with [Check import
            status](/api/product-directory/catalog/check-import-status).
    UploadCatalogResponse:
      type: object
      required:
        - job_id
      properties:
        job_id:
          type: string
          format: uuid
          description: Unique import job identifier. Use it to poll `Check import status`.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              description: The error category.
            message:
              type: string
              description: A message describing the error.
  securitySchemes:
    PersonalAccessToken:
      description: >-
        Use your `account ID` as the username and your personal access token
        (PAT) as the password, or pass a Base64-encoded value directly in the
        Authorization header. For more information, see the <a
        href="/authentication/personal-access-tokens">personal access tokens
        guide</a>.
      type: http
      scheme: basic

````

## Related topics

- [Check import status](/api-reference/catalog/check-import-status.md)
- [Get catalog details](/api-reference/catalog/get-catalog-details.md)
- [Delete a product](/api-reference/products/delete-a-product.md)
- [List catalogs](/api-reference/catalog/list-catalogs.md)