openapi: 3.2.0
info:
  contact:
    email: support@constructor.io
  title: Catalog management Item statistics API
  version: '0.1'
servers:
- url: https://ac.cnstrc.com
security: []
tags:
- name: Item statistics
paths:
  /v1/items_fields_stats:
    get:
      tags:
      - Item statistics
      operationId: v1-items-fields-stats-retrieve-items-fields-stats
      summary: Retrieve item field statistics
      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(r)`.


        Retrieve a list of statistics for all fields (such as `brand` or `size`).'
      parameters:
      - name: key
        in: query
        schema:
          title: Key
          description: The key of the index to use.
          maxLength: 100
          minLength: 1
          examples:
          - key_K2pX7vBnU0bgA5xp
          type: string
        required: true
      - name: section
        in: query
        schema:
          title: Section
          description: The section of the index to use. Defaults to `Products`.
          maxLength: 100
          minLength: 1
          examples:
          - Products
          - Search Suggestions
          type: string
        required: false
      - name: filters
        in: query
        schema:
          $ref: '#/components/schemas/ItemFieldFilters'
        required: false
        style: deepObject
        explode: true
      - name: num_results_per_page
        in: query
        schema:
          title: Num Results Per Page
          description: The number of results per page to return.
          default: 20
          minimum: 1
          maximum: 1000
          examples:
          - 20
          - 100
          type: integer
        required: false
      - name: page
        in: query
        schema:
          title: Page
          description: The page of results to return.
          minimum: 1
          examples:
          - 1
          - 2
          type: integer
        required: false
      - name: offset
        in: query
        schema:
          title: Offset
          description: The number of results to skip from the beginning. Cannot be used together with `page`.
          minimum: 0
          examples:
          - 0
          - 100
          type: integer
        required: false
      - name: sort_by
        in: query
        schema:
          title: Sort By
          description: The item field name to sort results by.
          examples:
          - name
          - percentage_presence
          enum:
          - name
          - percentage_presence
          type: string
        required: false
      - name: sort_order
        in: query
        schema:
          description: The order by which results should be sorted. Only valid in conjunction with `sort_by`.
          default: ascending
          examples:
          - ascending
          - descending
          allOf:
          - $ref: '#/components/schemas/SortOrderType'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFieldStatsListGetResponse'
        '400':
          description: Validation Error
        '401':
          description: Credentials are not passed or action is forbidden.
        '403':
          description: The supplied token does not have the required permissions.
        '404':
          description: Not Found
        '429':
          description: Rate limit breached
      security:
      - http_basic_auth: []
      - http_bearer_auth:
        - catalog(r)
  /v1/items_fields_stats/{name}:
    get:
      tags:
      - Item statistics
      operationId: v1-items-fields-stats-retrieve-item-field-stats
      summary: Retrieve item field statistic
      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(r)`.


        Retrieve a list of statistics for a specific field (such as `brand` or `size`).'
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: query
        schema:
          title: Key
          description: The key of the index to use.
          maxLength: 100
          minLength: 1
          examples:
          - key_K2pX7vBnU0bgA5xp
          type: string
        required: true
      - name: section
        in: query
        schema:
          title: Section
          description: The section of the index to use. Defaults to `Products`.
          maxLength: 100
          minLength: 1
          examples:
          - Products
          - Search Suggestions
          type: string
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFieldStatsGetResponse'
        '400':
          description: Validation Error
        '401':
          description: Credentials are not passed or action is forbidden.
        '403':
          description: The supplied token does not have the required permissions.
        '404':
          description: Not Found
        '429':
          description: Rate limit breached
      security:
      - http_basic_auth: []
      - http_bearer_auth:
        - catalog(r)
components:
  schemas:
    ItemFieldStatsListGetResponse:
      title: ItemFieldStatsListGetResponse
      type: object
      properties:
        items_fields_stats:
          title: Items Fields Stats
          type: array
          items:
            $ref: '#/components/schemas/ItemFieldStatsResponse'
        total_count:
          title: Total Count
          description: Number of item field stats
          minimum: 0
          type: integer
      required:
      - items_fields_stats
      - total_count
    MetadataSearchabilityType:
      title: MetadataSearchabilityType
      enum:
      - number
      - string
      - array
      - object
      - boolean
      - mixed
      type: string
    ItemFieldStatsResponse:
      title: ItemFieldStatsResponse
      type: object
      properties:
        name:
          title: Metadata Name
          description: The item field name on which stats are computed
          maxLength: 300
          minLength: 1
          type: string
        percentage_presence:
          title: Percentage Presence
          description: Percentage presence
          minimum: 0
          maximum: 1
          type: number
        type:
          description: The item field type
          allOf:
          - $ref: '#/components/schemas/MetadataSearchabilityType'
        example_items:
          title: Example Items
          type: array
          items:
            type: string
        created_at:
          title: Created At
          description: Item field stats creation date and time
          type: string
          format: date-time
        updated_at:
          title: Updated At
          description: Item field stats last update date and time
          type: string
          format: date-time
      required:
      - name
      - created_at
    ItemFieldFilters:
      title: Filters
      type: object
      properties:
        name:
          title: Name
          description: The item field name on which stats are computed
          maxLength: 300
          minLength: 1
          type: string
      additionalProperties: false
    SortOrderType:
      title: SortOrderType
      enum:
      - ascending
      - descending
      type: string
    ItemFieldStatsGetResponse:
      title: ItemFieldStatsGetResponse
      type: object
      properties:
        name:
          title: Metadata Name
          description: The item field name on which stats are computed
          maxLength: 300
          minLength: 1
          type: string
        percentage_presence:
          title: Percentage Presence
          description: Percentage presence
          minimum: 0
          maximum: 1
          type: number
        type:
          description: The item field type
          allOf:
          - $ref: '#/components/schemas/MetadataSearchabilityType'
        example_items:
          title: Example Items
          type: array
          items:
            type: string
        created_at:
          title: Created At
          description: Item field stats creation date and time
          type: string
          format: date-time
        updated_at:
          title: Updated At
          description: Item field stats last update date and time
          type: string
          format: date-time
      required:
      - name
      - created_at
  securitySchemes:
    http_basic_auth:
      type: http
      scheme: basic
    http_bearer_auth:
      type: http
      scheme: bearer
x-readme:
  explorer-enabled: false