> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert Categories > Create or replace one or more categories in the catalog. ## OpenAPI ````yaml /openapi.json put /public/v1/catalog-search-service/catalogs/categories openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. paths: /public/v1/catalog-search-service/catalogs/categories: put: tags: - Catalog API summary: Upsert Categories description: Create or replace one or more categories in the catalog. operationId: upsert_categories requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_CategoriesRequest' responses: '204': description: Successful Response '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_HTTPValidationError' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_CategoriesRequest: properties: categories: items: $ref: '#/components/schemas/Advanced_APIs_Category' type: array maxItems: 500 minItems: 1 title: Categories description: >- Categories to upsert. New categories will be created, and existing ones will be fully replaced with the provided data. type: object required: - categories title: CategoriesRequest Advanced_APIs_HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/Advanced_APIs_ValidationError' type: array title: Detail type: object title: HTTPValidationError Advanced_APIs_Category: properties: id: type: string maxLength: 255 minLength: 1 title: Id description: >- Unique ID of the category. Topsort treats IDs as strings, choose any format as long as it is unique within the catalog. examples: - ahEDqV5uhjj8 - CAT-343 - 52c8c83c-2f4f-4873-87a0-1ccd88273b27 name: type: string minLength: 1 title: Name description: Category name. Shown in Topsort UI. Truncated to 150 characters. examples: - Beers/Belgian - Sneakers - SALE parentId: title: Parentid description: >- Deprecated. Use `path` instead. ID of the parent category. Each category can have at most one parent category, allowing categories to be organized into hierarchies. deprecated: true examples: - CAT-434 - e5fde3c3-7562-43aa-9388-8376a55f9578 oneOf: - type: string maxLength: 255 minLength: 1 - type: 'null' path: title: Path description: >- A dot-separated string representing this category's location in the hierarchy. A child category's path is formed by appending its own identifier to its parent's path. For example, if 'clothing' has path 'apparel.clothing', its child 'dresses' would have path 'apparel.clothing.dresses'. Each segment may only contain A-Za-z0-9_. examples: - apparel_and_accessories.clothing.dresses oneOf: - type: string minLength: 1 pattern: ^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$ - type: 'null' globalId: title: Globalid description: >- Global ID of the category. This is an optional field that can be used to link the category to other marketplaces. examples: - CAT-12345 - CAT-67890 oneOf: - type: string maxLength: 255 minLength: 1 - type: 'null' metadata: title: Metadata description: Additional metadata for the category. examples: - description: All drinks available in the marketplace. globalName: Beers path: Driks/Alcoholic/Beers showInStore: true oneOf: - additionalProperties: oneOf: - type: integer - type: number - type: string - type: boolean - type: 'null' type: object maxProperties: 20 - type: 'null' type: object required: - id - name title: Category description: >- Categories provide a way to organize your catalog. Products always belong to at least one category, but can belong to more. Categories can be organized into hierarchies. Advanced_APIs_ValidationError: properties: loc: items: oneOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: Advanced_APIs_HTTPBearer: type: http description: >- A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key. scheme: bearer ````