Constructor Product Details API
Retrieval of item and variation product-detail records for a given index.
OpenAPI Specification
openapi: 3.1.0
info:
title: Product details
description: A service for retrieving product details for items and variations.
contact:
email: support@constructor.io
version: 1.0.0
servers:
- url: https://product-details.cnstrc.com
security: []
tags:
- name: Product details
paths:
/v1/items:
get:
tags:
- Product details
summary: Retrieve item product details
description: Retrieve product details for an item.
operationId: v1-product-details-get-items
parameters:
- name: key
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 100
title: Key
description: The key of the index to use.
examples:
- key_K2pX7vBnU0bgA5xp
description: The key of the index to use.
- name: section
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 100
title: Section
description: The section of the index to use (e.g. 'Products').
examples:
- Products
description: The section of the index to use (e.g. 'Products').
- name: item_id
in: query
required: true
schema:
type: string
title: Item ID
description: The unique identifier of an item in the product catalog.
description: The unique identifier of an item in the product catalog.
- name: c
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 100
- type: 'null'
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
examples:
- cio-js-client-2.35.2
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
- name: ui
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Ui
description: A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.
examples:
- customer-user-id-456
description: A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.
- name: fields
in: query
required: true
schema:
type: array
items:
const: enriched_attributes
type: string
title: Fields
description: One or more product detail fields to include in the response. This parameter may be repeated to specify multiple fields.
examples:
- - enriched_attributes
description: One or more product detail fields to include in the response. This parameter may be repeated to specify multiple fields.
- name: s
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: S
description: An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity.
examples:
- 1
description: An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity.
- name: i
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: I
description: A globally unique identifier for the user browser (or mobile application instance) making the request.
examples:
- user-device-id-123
description: A globally unique identifier for the user browser (or mobile application instance) making the request.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SingleItemGetResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithTrace'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security: []
/v1/variations:
get:
tags:
- Product details
summary: Retrieve variation product details
description: Retrieve product details for variations of an item.
operationId: v1-product-details-get-variations
parameters:
- name: key
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 100
title: Key
description: The key of the index to use.
examples:
- key_K2pX7vBnU0bgA5xp
description: The key of the index to use.
- name: section
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 100
title: Section
description: The section of the index to use (e.g. 'Products').
examples:
- Products
description: The section of the index to use (e.g. 'Products').
- name: variation_id
in: query
required: true
schema:
type: array
items:
type: string
maxItems: 100
title: Variation ID
description: One or more variation IDs to retrieve product details for. This parameter may be repeated to specify multiple IDs.
description: One or more variation IDs to retrieve product details for. This parameter may be repeated to specify multiple IDs.
- name: c
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 100
- type: 'null'
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
examples:
- cio-js-client-2.35.2
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
- name: ui
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Ui
description: A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.
examples:
- customer-user-id-456
description: A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.
- name: fields
in: query
required: true
schema:
type: array
items:
const: enriched_attributes
type: string
title: Fields
description: One or more product detail fields to include in the response. This parameter may be repeated to specify multiple fields.
examples:
- - enriched_attributes
description: One or more product detail fields to include in the response. This parameter may be repeated to specify multiple fields.
- name: s
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: S
description: An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity.
examples:
- 1
description: An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity.
- name: i
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: I
description: A globally unique identifier for the user browser (or mobile application instance) making the request.
examples:
- user-device-id-123
description: A globally unique identifier for the user browser (or mobile application instance) making the request.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VariationsGetResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithTrace'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security: []
components:
schemas:
AttributeType:
type: string
enum:
- standard
- extended
title: AttributeType
description: The type of an enriched attribute value.
AttributeValue:
properties:
value:
type: string
title: Value
type:
$ref: '#/components/schemas/AttributeType'
type: object
required:
- value
- type
title: AttributeValue
description: A single enriched attribute value.
Badge:
properties:
type:
type: string
title: Type
display_name:
type: string
title: Display Name
metadata:
additionalProperties:
type: string
type: object
title: Metadata
examples:
- times_was_seen_last_week: '123'
type: object
required:
- type
- display_name
title: Badge
description: Fully resolved badge (API type, all {placeholder} replaced).
EnrichedAttributes:
properties:
badges:
items:
$ref: '#/components/schemas/Badge'
type: array
title: Badges
attributes:
additionalProperties:
items:
$ref: '#/components/schemas/AttributeValue'
type: array
type: object
title: Attributes
examples:
- color:
- type: standard
value: red
- type: standard
value: green
- type: standard
value: blue
neckline:
- type: standard
value: round
type: object
required:
- badges
- attributes
title: EnrichedAttributes
description: 'Enriched attributes: resolved badges and attributes keyed by name.'
ErrorDetail:
properties:
code:
type: string
title: Code
message:
type: string
title: Message
type: object
required:
- code
- message
title: ErrorDetail
description: Single error entry in an error response.
ErrorResponse:
properties:
message:
type: string
title: Message
errors:
items:
$ref: '#/components/schemas/ErrorDetail'
type: array
title: Errors
type: object
required:
- message
- errors
title: ErrorResponse
description: Standard error response body.
ErrorResponseWithTrace:
properties:
message:
type: string
title: Message
errors:
items:
$ref: '#/components/schemas/ErrorDetail'
type: array
title: Errors
trace_id:
type: string
title: Trace Id
type: object
required:
- message
- errors
- trace_id
title: ErrorResponseWithTrace
description: Error response body with trace ID.
ItemWithEnrichedAttributes:
properties:
id:
type: string
title: ID
enriched_attributes:
$ref: '#/components/schemas/EnrichedAttributes'
type: object
required:
- id
- enriched_attributes
title: ItemWithEnrichedAttributes
description: Item with nested enriched_attributes (used in GET /v1/items).
Variation:
properties:
variation_id:
type: string
title: Variation ID
enriched_attributes:
$ref: '#/components/schemas/EnrichedAttributes'
type: object
required:
- variation_id
- enriched_attributes
title: Variation
description: Variation with nested enriched_attributes (used in GET /v1/variations).
SingleItemGetResponse:
properties:
trace_id:
type: string
title: Trace Id
response:
title: Response
type: object
properties:
item:
$ref: '#/components/schemas/ItemWithEnrichedAttributes'
required:
- item
type: object
required:
- trace_id
- response
title: SingleItemGetResponse
description: Full response for GET /v1/items.
VariationsGetResponse:
properties:
trace_id:
type: string
title: Trace Id
response:
title: Response
type: object
properties:
variations:
title: Variations
type: array
items:
$ref: '#/components/schemas/Variation'
required:
- variations
type: object
required:
- trace_id
- response
title: VariationsGetResponse
description: Full response for GET /v1/variations.
securitySchemes:
http_basic_auth:
type: http
scheme: basic
http_bearer_auth:
type: http
scheme: bearer
x-readme:
explorer-enabled: false