> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Listings

<Warning>
  This page does not apply to installs made in 2025 or later of the Depict Shopify apps
</Warning>


## OpenAPI

````yaml get /v3/listings
openapi: 3.1.0
info:
  title: Depict API
  version: '1.0'
servers: []
security: []
paths:
  /v3/listings:
    get:
      tags:
        - Listing (v3)
      summary: Get Listings
      description: >-
        Returns the full listing hierarchy. Useful for navigation menus, listing
        selection dialogs, etc.

        Can optionally be filtered to only show listings of certain types.


        Example response:

        <pre>

        [
            {
                "listing_id": "f346c448-4cf1-4373-9156-49e222cd6db0",
                "listing_type": "smart_pick",
                "show_in_breadcrumbs": false,
                "show_in_quicklinks": false,
                "title": "Trending",
                "children": []
            },
            {
                "listing_id": "2efca23d-f077-4477-8830-cc7143c49173",
                "external_id": "1001",
                "listing_type": "category",
                "show_in_breadcrumbs": true,
                "show_in_quicklinks": true,
                "title": "Clothes",
                "slug": "mens-cloths",
                "children": [
                    {
                        "listing_id": "06b234cf-ce21-4252-90e6-db47246b1d98",
                        "external_id": "1011",
                        "listing_type": "category",
                        "show_in_breadcrumbs": true,
                        "show_in_quicklinks": true,
                        "title": "Suits",
                        "slug": "mens-suits",
                        "children": []
                    },
                    {
                        "listing_id": "1e648857-4aad-4606-9e7a-5290cb3576e5",
                        "external_id": "1012",
                        "listing_type": "category",
                        "show_in_breadcrumbs": true,
                        "show_in_quicklinks": true,
                        "title": "Shirts",
                        "slug": "mens-shirts",
                        "children": []
                    }
                ]
            }
        ]

        </pre>
      operationId: Get_Listings_v3_listings_get
      parameters:
        - name: merchant
          in: query
          required: true
          schema:
            type: string
            title: Merchant
        - name: market
          in: query
          required: true
          schema:
            type: string
            title: Market
        - name: locale
          in: query
          required: true
          schema:
            type: string
            title: Locale
        - name: types
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/CollectionType'
            default: []
            title: Types
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ListListingsResponseItem'
                title: Response Get Listings V3 Listings Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
        - APIKeyCookie: []
components:
  schemas:
    CollectionType:
      type: string
      enum:
        - long_tail_collection
        - campaign
        - category
        - smart_pick
        - style
        - brand
      title: CollectionType
    ListListingsResponseItem:
      properties:
        listing_id:
          type: string
          format: uuid
          title: Listing Id
          description: Depict ID of the listing.
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
          description: ID of the listing in the merchant PIM, CMS or similar.
        listing_type:
          $ref: '#/components/schemas/CollectionType'
        show_in_breadcrumbs:
          type: boolean
          title: Show In Breadcrumbs
          description: Show or hide this listing in navigation breadcrumbs.
        show_in_quicklinks:
          type: boolean
          title: Show In Quicklinks
          description: Show or hide this listing in quicklinks.
        image_urls:
          items:
            type: string
          type: array
          title: Image Urls
          description: List of image URLs for the listing.
        title:
          type: string
          title: Title
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
        children:
          items:
            $ref: '#/components/schemas/ListListingsResponseItem'
          type: array
          title: Children
      additionalProperties: false
      type: object
      required:
        - listing_id
        - listing_type
        - show_in_breadcrumbs
        - show_in_quicklinks
        - image_urls
        - title
        - children
      title: ListListingsResponseItem
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - 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:
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
    APIKeyCookie:
      type: apiKey
      in: cookie
      name: X-API-KEY

````