Constructor Catalog Batching API
Batched catalog ingestion service for high-volume item and variation update and delete operations.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/constructor-catalog-batching-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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