Constructor Catalog Batching API
Batched catalog ingestion service for high-volume item and variation update and delete operations.
OpenAPI Specification
openapi: 3.1.0
info:
title: Catalog Batching Service
contact:
email: support@constructor.io
version: 0.1.0
servers:
- url: https://batching.catalog.cnstrc.com
paths:
/v2/items:
patch:
tags:
- Items
summary: Update catalog items
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `catalog(w)`.
Update items in the catalog. If an item does not exist, it will be created.'
operationId: v2-batching-items-update-items
parameters:
- name: key
in: query
required: true
schema:
type: string
description: The key of the index to use.
title: Key
description: The key of the index to use.
- name: section
in: query
required: true
schema:
type: string
description: The section of the index to use. Defaults to `Products`.
title: Section
description: The section of the index to use. Defaults to `Products`.
- name: on_missing
in: query
required: false
schema:
$ref: '#/components/schemas/MissingRecordsStrategy'
description: Strategy for handling items that do not exist. Only CREATE is supported.
default: CREATE
description: Strategy for handling items that do not exist. Only CREATE is supported.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ItemsBatchRequest'
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/BatchAcceptedResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- http_basic_auth: []
- http_bearer_auth:
- catalog(w)
delete:
tags:
- Items
summary: Delete catalog items
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `catalog(w)`.
Delete items from the catalog. Deletions are processed asynchronously.'
operationId: v2-batching-items-delete-items
parameters:
- name: key
in: query
required: true
schema:
type: string
description: The key of the index to use.
title: Key
description: The key of the index to use.
- name: section
in: query
required: true
schema:
type: string
description: The section of the index to use. Defaults to `Products`.
title: Section
description: The section of the index to use. Defaults to `Products`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ItemsDeleteRequest'
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/BatchAcceptedResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- http_basic_auth: []
- http_bearer_auth:
- catalog(w)
/v2/variations:
patch:
tags:
- Variations
summary: Update catalog variations
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `catalog(w)`.
Update variations in the catalog. If a variation does not exist, it will be created.'
operationId: v2-batching-variations-update-variations
parameters:
- name: key
in: query
required: true
schema:
type: string
description: The key of the index to use.
title: Key
description: The key of the index to use.
- name: section
in: query
required: true
schema:
type: string
description: The section of the index to use. Defaults to `Products`.
title: Section
description: The section of the index to use. Defaults to `Products`.
- name: on_missing
in: query
required: false
schema:
$ref: '#/components/schemas/MissingRecordsStrategy'
description: Strategy for handling variations that do not exist. Only CREATE is supported.
default: CREATE
description: Strategy for handling variations that do not exist. Only CREATE is supported.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VariationsBatchRequest'
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/BatchAcceptedResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- http_basic_auth: []
- http_bearer_auth:
- catalog(w)
delete:
tags:
- Variations
summary: Delete catalog variations
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `catalog(w)`.
Delete variations from the catalog. Deletions are processed asynchronously.'
operationId: v2-batching-variations-delete-variations
parameters:
- name: key
in: query
required: true
schema:
type: string
description: The key of the index to use.
title: Key
description: The key of the index to use.
- name: section
in: query
required: true
schema:
type: string
description: The section of the index to use. Defaults to `Products`.
title: Section
description: The section of the index to use. Defaults to `Products`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VariationsDeleteRequest'
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/BatchAcceptedResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- http_basic_auth: []
- http_bearer_auth:
- catalog(w)
components:
schemas:
BatchAcceptedResponse:
properties:
message:
type: string
title: Message
description: Success message
count:
type: integer
title: Count
description: Number of items/variations accepted.
type: object
required:
- message
- count
title: BatchAcceptedResponse
description: Response for accepted batching requests.
ErrorResponse:
properties:
message:
type: string
title: Message
description: Error message
errors:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Errors
description: Detailed validation errors
type: object
required:
- message
title: ErrorResponse
description: Error response model.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Item:
properties:
id:
type: string
maxLength: 250
minLength: 1
title: ID
description: The ID of the item, must be unique.
name:
type: string
maxLength: 250
minLength: 1
title: Name
description: The name of the item, as it will appear in the results. Must contain at least one alphanumeric character.
suggested_score:
anyOf:
- type: integer
maximum: 500000000
minimum: -1
- type: 'null'
title: Suggested Score
description: A number that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear).
data:
anyOf:
- $ref: '#/components/schemas/ItemMetadata'
- type: 'null'
description: Object containing additional data, that should be attached to this item. The maximum size of data object is limited to 30kB.
additionalProperties: false
type: object
required:
- id
- name
title: Item
description: Catalog item model.
ItemDeletePayload:
properties:
id:
type: string
maxLength: 250
minLength: 1
title: ID
description: The ID of the item to delete.
type: object
required:
- id
title: ItemDeletePayload
description: Payload for deleting a single item.
ItemMetadata:
properties:
keywords:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Keywords
description: An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a search term that is not in the product name itself.
url:
anyOf:
- type: string
- type: 'null'
title: URL
description: A URL to directly send the user after selecting the item. Might be required in some cases. Please consult with your integration team for more information.
image_url:
anyOf:
- type: string
- type: 'null'
title: Image URL
description: A URL that points to an image you would like displayed next to some item (only applicable when URL is supplied).
group_ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Group IDs
description: You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please consult with your integration team for more information. `group_ids` can be used as filters in search, autosuggest, and browse requests.
description:
anyOf:
- type: string
maxLength: 4000
- type: 'null'
title: Description
description: A description for this item. The maximum length of this field is 4,000 characters.
active:
anyOf:
- type: boolean
- type: 'null'
title: Active
description: Determines whether the item is active and eligible to be returned in results.
facets:
anyOf:
- additionalProperties:
anyOf:
- type: string
- type: integer
- type: number
- items:
anyOf:
- type: string
- type: integer
- type: number
type: array
type: object
- type: 'null'
title: Facets
description: A mapping of facet names to values. Each value is either a single string, integer, or floating point number, or a list of those. Facet keys are limited to 100 characters; string values are limited to 200 characters.
deprecated: true
additionalProperties: true
type: object
title: ItemMetadata
description: Additional metadata for an item.
ItemsBatchRequest:
properties:
items:
items:
$ref: '#/components/schemas/Item'
type: array
maxItems: 100
minItems: 1
title: Items
description: Array of items to batch (1-100 items).
type: object
required:
- items
title: ItemsBatchRequest
description: Request body for batching items.
ItemsDeleteRequest:
properties:
items:
items:
$ref: '#/components/schemas/ItemDeletePayload'
type: array
maxItems: 100
minItems: 1
title: Items
description: Array of items to delete (1-100 items).
type: object
required:
- items
title: ItemsDeleteRequest
description: Request body for deleting items.
MissingRecordsStrategy:
type: string
enum:
- CREATE
title: MissingRecordsStrategy
description: Strategy for handling records that do not exist in the system.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
Variation:
properties:
id:
type: string
maxLength: 250
minLength: 1
title: ID
description: The ID of the variation, must be unique.
item_id:
type: string
maxLength: 250
minLength: 1
title: Item ID
description: The ID of the item this variation is attached to.
name:
anyOf:
- type: string
maxLength: 250
minLength: 1
- type: 'null'
title: Name
description: The name of the variation, as it will appear in the results. Must contain at least one alphanumeric character.
suggested_score:
anyOf:
- type: integer
maximum: 500000000
minimum: -1
- type: 'null'
title: Suggested Score
description: A number that will influence the variation's initial ranking relative to other variation scores (the higher the score, the higher in the list of suggestions the variation will appear).
data:
anyOf:
- $ref: '#/components/schemas/VariationMetadata'
- type: 'null'
description: Object containing additional data, that should be attached to this variation. The maximum size of data object is limited to 30kB.
additionalProperties: false
type: object
required:
- id
- item_id
title: Variation
description: Catalog variation model.
VariationDeletePayload:
properties:
id:
type: string
maxLength: 250
minLength: 1
title: ID
description: The ID of the variation to delete.
type: object
required:
- id
title: VariationDeletePayload
description: Payload for deleting a single variation.
VariationMetadata:
properties:
keywords:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Keywords
description: An array of keywords for this variation. Keywords are useful if you want a product name to appear when a user enters a search term that is not in the product name itself.
url:
anyOf:
- type: string
- type: 'null'
title: URL
description: A URL to directly send the user after selecting the variation. Might be required in some cases. Please consult with your integration team for more information.
image_url:
anyOf:
- type: string
- type: 'null'
title: Image URL
description: A URL that points to an image you would like displayed next to some variation (only applicable when URL is supplied).
group_ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Group IDs
description: You can associate each variation with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io group_ids can be used as filters in search, autosuggest, and browse requests.
description:
anyOf:
- type: string
maxLength: 4000
- type: 'null'
title: Description
description: A description for this variation. The maximum length of this field is 4000 characters.
active:
anyOf:
- type: boolean
- type: 'null'
title: Active
description: Whether the variation is active and eligible to be returned in results.
facets:
anyOf:
- additionalProperties:
anyOf:
- type: string
- type: integer
- type: number
- items:
anyOf:
- type: string
- type: integer
- type: number
type: array
type: object
- type: 'null'
title: Facets
description: A mapping of facet names to values. Each value is either a single string, integer, or floating point number, or a list of those. Facet keys are limited to 100 characters; string values are limited to 200 characters.
deprecated: true
is_default:
anyOf:
- type: boolean
- type: 'null'
title: Is Default
description: Whether this variation should always be returned as the best matching variation.
additionalProperties: true
type: object
title: VariationMetadata
description: Additional metadata for a variation.
VariationsBatchRequest:
properties:
variations:
items:
$ref: '#/components/schemas/Variation'
type: array
maxItems: 100
minItems: 1
title: Variations
description: Array of variations to batch (1-100 variations).
type: object
required:
- variations
title: VariationsBatchRequest
description: Request body for batching variations.
VariationsDeleteRequest:
properties:
variations:
items:
$ref: '#/components/schemas/VariationDeletePayload'
type: array
maxItems: 100
minItems: 1
title: Variations
description: Array of variations to delete (1-100 variations).
type: object
required:
- variations
title: VariationsDeleteRequest
description: Request body for deleting variations.
securitySchemes:
http_basic_auth:
type: http
scheme: basic
http_bearer_auth:
type: http
scheme: bearer
x-readme:
explorer-enabled: false