openapi: 3.2.0
info:
  title: Nexscope Ecommerce Data and Creative Etsy Marketplace API
  version: 2026-08-28-public-catalog-v1
  description: Nexscope APIs provide ecommerce marketplace intelligence and creative generation capabilities through REST and MCP. Authentication uses a Nexscope API key. Pricing is credit-based and actual usage varies by endpoint and workload; current estimates are shown in the Nexscope account.
  termsOfService: https://www.nexscope.ai/terms
  contact:
    name: Nexscope Support
    email: service@nexscope.ai
    url: https://www.nexscope.ai/api-docs
  license:
    name: Proprietary API; use subject to Nexscope Terms
    url: https://www.nexscope.ai/terms
servers:
- url: https://api.nexscope.ai
  description: Production
security:
- bearerAuth: []
tags:
- name: Etsy Marketplace
  description: Etsy product and category discovery APIs.
  x-category-slug: etsy-marketplace
paths:
  /api/skill-api/v1/skills/etsy-category-search/run:
    post:
      tags:
      - Etsy Marketplace
      summary: Etsy Category Search
      description: Search Etsy category data by name, ID, or parent IDs to find category identifiers for product/store filtering.
      operationId: runEtsyCategorySearch
      externalDocs:
        description: Etsy Category Search documentation
        url: https://www.nexscope.ai/api-docs/etsy-category-search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request parameters documented by ecommerce.etsy-category-search.
              properties:
                keyword:
                  type: string
                  description: 'Keyword: matches category name, category id, or parentIds fields (substring)'
                  example: phone case
                page:
                  type: integer
                  description: Page number (starting from 1)
                  example: 1
                pageSize:
                  type: integer
                  description: Items per page, max 200
                  example: 1
              required:
              - keyword
              example:
                page: 1
                keyword: phone case
                pageSize: 1
              additionalProperties: true
            example:
              page: 1
              keyword: phone case
              pageSize: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                description: Returns the documented upstream API response directly without an additional wrapper.
                properties:
                  total:
                    type: integer
                    description: Number of records returned on this page
                    example: 1
                  costToken:
                    type: integer
                    description: Token consumption (local retrieval is free)
                    example: 1
                  categories:
                    type: array
                    items:
                      type: object
                      properties:
                        categoryLevel:
                          type: integer
                          description: Category level
                          example: 1
                        id:
                          type: string
                          description: Category ID
                          example: example-id
                        name:
                          type: string
                          description: Category name
                        parentId:
                          type: string
                          description: Canonical primary parent category ID
                          example: example-id
                        parentIds:
                          type: string
                          description: All non-empty parent category IDs (comma-separated)
                      additionalProperties: true
                    description: List of matching categories
                    example: []
                  title:
                    type: string
                    description: Title
                  errcode:
                    type: integer
                    description: Upstream status code returned by the provider.
                  errmsg:
                    type: string
                    description: Upstream status message returned by the provider.
                  code:
                    type: string
                    description: Provider-specific status code.
                  msg:
                    type: string
                    description: Provider-specific status message.
                  message:
                    type: string
                    description: Provider-specific message.
                  type:
                    type: string
                    description: Provider-specific render or payload type.
                  sourceType:
                    type: string
                    description: Provider-specific source platform type.
                  sourceTool:
                    type: string
                    description: Provider-specific source tool name.
                  costTime:
                    type: integer
                    description: Execution time reported by the upstream provider.
                  page:
                    type: integer
                    description: Current page returned by the upstream provider.
                  pageSize:
                    type: integer
                    description: Page size returned by the upstream provider.
                  pageItemCount:
                    type: integer
                    description: Item count on the current page returned by the upstream provider.
                  totalPage:
                    type: integer
                    description: Total page count returned by the upstream provider.
                  dataSnapshotMonth:
                    type: string
                    description: Data snapshot month returned by the upstream provider.
                example:
                  total: 1
                  costToken: 1
                  categories:
                  - categoryLevel: 1
                    id: example-id
                    parentId: example-id
                additionalProperties: true
              example:
                total: 1
                costToken: 1
                categories:
                - categoryLevel: 1
                  id: example-id
                  parentId: example-id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      x-nexscope-slug: etsy-category-search
      x-nexscope-mcp-tool-name: nexscope_etsy_category_search
      x-nexscope-pricing-mode: dynamic-credits
      x-nexscope-catalog-derived: true
  /api/skill-api/v1/skills/etsy-product-query/run:
    post:
      tags:
      - Etsy Marketplace
      summary: Etsy Product Query
      description: Query Etsy products with multi-dimensional filters (keyword/URL, price, sales, favorites, reviews, listing date, category, handmade/vintage types, Pick/Bestseller/Raving tags).
      operationId: runEtsyProductQuery
      externalDocs:
        description: Etsy Product Query documentation
        url: https://www.nexscope.ai/api-docs/etsy-product-query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request parameters documented by ecommerce.etsy-product-query.
              properties:
                beginFavorites:
                  type: integer
                  description: Favorite count (start), combined with end value to form the upstream favorites range
                  example: 1
                beginFavoritesWeekly:
                  type: integer
                  description: Weekly new favorites (start), combined with end value to form the upstream favorites_weekly range
                  example: 1
                beginPrice:
                  type: number
                  description: Price (start), combined with end price to form the upstream price range (e.g., 20~100). When only one side is provided, the upstream returns start~ or ~end
                  example: 1
                beginReviews:
                  type: integer
                  description: Review count (start), combined with end value to form the upstream reviews range
                  example: 1
                beginReviewsWeekly:
                  type: integer
                  description: Weekly new reviews (start), combined with end value to form the upstream reviews_weekly range
                  example: 1
                beginSales:
                  type: integer
                  description: Total sales (start), combined with end value to form the upstream sales range
                  example: 1
                beginSalesWeekly:
                  type: integer
                  description: Weekly sales (start), combined with end value to form the upstream sales_weekly range (e.g., 1~100)
                  example: 1
                category:
                  type: string
                  description: Product category ID (single category), see the Category Query API
                country:
                  type: string
                  description: Shipping country
                currencyCode:
                  type: string
                  description: Currency code
                endFavorites:
                  type: integer
                  description: Favorite count (end)
                  example: 1
                endFavoritesWeekly:
                  type: integer
                  description: Weekly new favorites (end)
                  example: 1
                endPrice:
                  type: number
                  description: Price (end), combined with start price to form the upstream price range
                  example: 1
                endReviews:
                  type: integer
                  description: Review count (end)
                  example: 1
                endReviewsWeekly:
                  type: integer
                  description: Weekly new reviews (end)
                  example: 1
                endSales:
                  type: integer
                  description: Total sales (end)
                  example: 1
                endSalesWeekly:
                  type: integer
                  description: Weekly sales (end)
                  example: 1
                isBestsell:
                  type: integer
                  description: Whether the product is a bestseller
                  example: 1
                isPick:
                  type: integer
                  description: Whether the product is a Pick item
                  example: 1
                isRaving:
                  type: integer
                  description: Whether the product is a Raving item
                  example: 1
                listedTime:
                  type: string
                  description: Listing time no earlier than this date (YYYY-MM-DD)
                page:
                  type: integer
                  description: Page number (starting from 1)
                  example: 1
                pageSize:
                  type: integer
                  description: Items per page, max 100, recommended not to exceed 50
                  example: 10
                productType:
                  type: string
                  description: 'Product type, comma-separated for multiple: 1=Handmade 2=Vintage 3=Digital 4=Custom 9=Other'
                searchKey:
                  type: string
                  description: Search keyword or Etsy product URL
                sortBy:
                  type: integer
                  description: Sort field (corresponds to upstream sort_by, values 1~6)
                  example: 1
                sortDesc:
                  type: integer
                  description: 'Sort direction (corresponds to upstream desc). Schema example: descending 1, ascending 2 (encoding differs from store query''s sortDesc)'
                  example: 1
                status:
                  type: integer
                  description: 'Product status (example: 1=active, 0=inactive)'
                  example: 1
              example:
                page: 1
                pageSize: 10
                searchKey: phone case
              additionalProperties: true
            example:
              page: 1
              pageSize: 10
              searchKey: phone case
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                description: Returns the documented upstream API response directly without an additional wrapper.
                properties:
                  total:
                    type: integer
                    description: Record count (number of records returned on this page, for alignment with list length)
                    example: 1
                  sourceTool:
                    type: string
                    description: 'Tool type: ehunt'
                  sourceType:
                    type: string
                    description: 'Source type: etsy'
                  columns:
                    type: array
                    items: {}
                    description: Rendered columns
                    example: []
                  costToken:
                    type: integer
                    description: Token consumption (estimated based on records returned on this page)
                    example: 1
                  productNum:
                    type: integer
                    description: Total number of matching products (upstream product_num)
                    example: 1
                  title:
                    type: string
                    description: Title
                  type:
                    type: string
                    description: Render style
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        category:
                          type: string
                          description: Category name
                        favorites:
                          type: integer
                          description: Favorite count
                          example: 1
                        favoritesWeekly:
                          type: integer
                          description: Weekly new favorites
                          example: 1
                        imageUrl:
                          type: string
                          description: Main image URL
                          example: https://example.com/image.jpg
                        isBestsell:
                          type: integer
                          description: 'Whether bestseller: 1=Yes'
                          example: 1
                        isPick:
                          type: integer
                          description: 'Whether Pick: 1=Yes'
                          example: 1
                        isRaving:
                          type: integer
                          description: 'Whether Raving: 1=Yes'
                          example: 1
                        price:
                          type: number
                          description: Price
                          example: 1
                        productUrl:
                          type: string
                          description: Product link
                          example: https://example.com/image.jpg
                        releaseTime:
                          type: string
                          description: Listing/release time
                        reviews:
                          type: integer
                          description: Review count
                          example: 1
                        reviewsWeekly:
                          type: integer
                          description: Weekly new reviews
                          example: 1
                        salesTotal:
                          type: integer
                          description: Total sales
                          example: 1
                        salesWeekly:
                          type: integer
                          description: Weekly sales
                          example: 1
                        shipsFrom:
                          type: string
                          description: Shipping country
                        status:
                          type: integer
                          description: 'Product status: 1=active, 0=inactive'
                          example: 1
                        storeName:
                          type: string
                          description: Store name
                        tags:
                          type: string
                          description: Tags
                        title:
                          type: string
                          description: Product title
                      additionalProperties: true
                    description: Etsy product list
                    example: []
                  errcode:
                    type: integer
                    description: Upstream status code returned by the provider.
                  errmsg:
                    type: string
                    description: Upstream status message returned by the provider.
                  code:
                    type: string
                    description: Provider-specific status code.
                  msg:
                    type: string
                    description: Provider-specific status message.
                  message:
                    type: string
                    description: Provider-specific message.
                  costTime:
                    type: integer
                    description: Execution time reported by the upstream provider.
                  page:
                    type: integer
                    description: Current page returned by the upstream provider.
                  pageSize:
                    type: integer
                    description: Page size returned by the upstream provider.
                  pageItemCount:
                    type: integer
                    description: Item count on the current page returned by the upstream provider.
                  totalPage:
                    type: integer
                    description: Total page count returned by the upstream provider.
                  dataSnapshotMonth:
                    type: string
                    description: Data snapshot month returned by the upstream provider.
                example:
                  total: 1
                  columns: []
                  costToken: 1
                  productNum: 1
                  products:
                  - favorites: 1
                    favoritesWeekly: 1
                    imageUrl: https://example.com/image.jpg
                    isBestsell: 1
                    isPick: 1
                    isRaving: 1
                    price: 1
                    productUrl: https://example.com/image.jpg
                    reviews: 1
                    reviewsWeekly: 1
                    salesTotal: 1
                    salesWeekly: 1
                    status: 1
                additionalProperties: true
              example:
                total: 1
                columns: []
                costToken: 1
                productNum: 1
                products:
                - favorites: 1
                  favoritesWeekly: 1
                  imageUrl: https://example.com/image.jpg
                  isBestsell: 1
                  isPick: 1
                  isRaving: 1
                  price: 1
                  productUrl: https://example.com/image.jpg
                  reviews: 1
                  reviewsWeekly: 1
                  salesTotal: 1
                  salesWeekly: 1
                  status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      x-nexscope-slug: etsy-product-query
      x-nexscope-mcp-tool-name: nexscope_etsy_product_query
      x-nexscope-pricing-mode: dynamic-credits
      x-nexscope-catalog-derived: true
  /api/skill-api/v1/skills/etsy-store-query/run:
    post:
      tags:
      - Etsy Marketplace
      summary: Etsy Store Query
      description: Returns Etsy store profiles and marketplace performance metrics.
      operationId: runEtsyStoreQuery
      externalDocs:
        description: Etsy Store Query documentation
        url: https://www.nexscope.ai/api-docs/etsy-store-query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: All filters are optional. Use searchKey to query a specific store name or URL.
              properties:
                searchKey:
                  type: string
                  description: Store name, keyword, or Etsy store URL.
                  example: Lewshop1
                category:
                  type: string
                  description: Primary store category.
                  example: Jewelry
                country:
                  type: string
                  description: Store country or region.
                  example: US
                status:
                  type: integer
                  description: 'Store status: 1 active, 0 inactive.'
                  example: 1
                isRaving:
                  type: integer
                  description: 'Raving store flag: 1 yes.'
                  example: 1
                isStar:
                  type: integer
                  description: 'Star store flag: 1 yes.'
                  example: 1
                beginFavorites:
                  type: integer
                  description: Minimum total favorites.
                  example: 0
                endFavorites:
                  type: integer
                  description: Maximum total favorites.
                  example: 10000
                beginFavoritesWeekly:
                  type: integer
                  description: Minimum weekly favorites.
                  example: 0
                endFavoritesWeekly:
                  type: integer
                  description: Maximum weekly favorites.
                  example: 1000
                beginReviews:
                  type: integer
                  description: Minimum total reviews.
                  example: 0
                endReviews:
                  type: integer
                  description: Maximum total reviews.
                  example: 10000
                beginReviewsWeekly:
                  type: integer
                  description: Minimum weekly reviews.
                  example: 0
                endReviewsWeekly:
                  type: integer
                  description: Maximum weekly reviews.
                  example: 1000
                beginSales:
                  type: integer
                  description: Minimum total sales.
                  example: 0
                endSales:
                  type: integer
                  description: Maximum total sales.
                  example: 100000
                beginSalesWeekly:
                  type: integer
                  description: Minimum weekly sales.
                  example: 0
                endSalesWeekly:
                  type: integer
                  description: Maximum weekly sales.
                  example: 1000
                beginStoreOpenedAt:
                  type: string
                  description: Opening date range start in YYYY-MM-DD format.
                  example: '2020-01-01'
                endStoreOpenedAt:
                  type: string
                  description: Opening date range end in YYYY-MM-DD format.
                  example: '2026-01-01'
                sortBy:
                  type: integer
                  description: 'Sort field: 8 total sales, 9 weekly sales, 10 reviews, 11 favorites.'
                  example: 8
                sortDesc:
                  type: integer
                  description: 'Sort direction: 1 descending, 0 ascending.'
                  example: 1
                page:
                  type: integer
                  description: Page number starting from 1.
                  example: 1
                pageSize:
                  type: integer
                  description: Items per page from 1 to 100.
                  example: 20
              example:
                page: 1
                searchKey: Lewshop1
                pageSize: 20
              additionalProperties: true
            example:
              page: 1
              searchKey: Lewshop1
              pageSize: 20
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                description: Returns the Etsy store gateway payload directly.
                properties:
                  total:
                    type: integer
                    description: Records returned on the current page.
                    example: 1
                  storeNum:
                    type: integer
                    description: Total matching stores.
                    example: 1
                  stores:
                    type: array
                    items:
                      type: object
                      properties:
                        storeId:
                          type: string
                          description: Store identifier.
                          example: '123456'
                        storeName:
                          type: string
                          description: Store name.
                          example: Lewshop1
                        storeUrl:
                          type: string
                          description: Etsy store URL.
                          example: https://www.etsy.com/shop/Lewshop1
                        country:
                          type: array
                          items: {}
                          description: Store countries or regions.
                          example: []
                        category:
                          type: array
                          items: {}
                          description: Primary categories.
                          example: []
                        salesTotal:
                          type: integer
                          description: Total sales.
                          example: 1
                        salesWeekly:
                          type: integer
                          description: Weekly sales.
                          example: 1
                        reviews:
                          type: integer
                          description: Review count.
                          example: 1
                        favorites:
                          type: integer
                          description: Favorite count.
                          example: 1
                        rating:
                          type: number
                          description: Store rating.
                          example: 4.8
                        status:
                          type: integer
                          description: Store status.
                          example: 1
                      additionalProperties: true
                    description: Etsy stores.
                    example: []
                  columns:
                    type: array
                    items: {}
                    description: Provider rendering columns.
                    example: []
                  costToken:
                    type: integer
                    description: Provider-reported token cost.
                    example: 3600
                  errcode:
                    type: integer
                    description: Upstream status code returned by the provider.
                  errmsg:
                    type: string
                    description: Upstream status message returned by the provider.
                  code:
                    type: string
                    description: Provider-specific status code.
                  msg:
                    type: string
                    description: Provider-specific status message.
                  message:
                    type: string
                    description: Provider-specific message.
                  type:
                    type: string
                    description: Provider-specific render or payload type.
                  title:
                    type: string
                    description: Provider-specific response title.
                  sourceType:
                    type: string
                    description: Provider-specific source platform type.
                  sourceTool:
                    type: string
                    description: Provider-specific source tool name.
                  costTime:
                    type: integer
                    description: Execution time reported by the upstream provider.
                  page:
                    type: integer
                    description: Current page returned by the upstream provider.
                  pageSize:
                    type: integer
                    description: Page size returned by the upstream provider.
                  pageItemCount:
                    type: integer
                    description: Item count on the current page returned by the upstream provider.
                  totalPage:
                    type: integer
                    description: Total page count returned by the upstream provider.
                  dataSnapshotMonth:
                    type: string
                    description: Data snapshot month returned by the upstream provider.
                example:
                  total: 1
                  storeNum: 1
                  stores:
                  - storeId: '123456'
                    storeName: Lewshop1
                    storeUrl: https://www.etsy.com/shop/Lewshop1
                    country: []
                    category: []
                    salesTotal: 1
                    salesWeekly: 1
                    reviews: 1
                    favorites: 1
                    rating: 4.8
                    status: 1
                  columns: []
                  costToken: 3600
                additionalProperties: true
              example:
                total: 1
                storeNum: 1
                stores:
                - storeId: '123456'
                  storeName: Lewshop1
                  storeUrl: https://www.etsy.com/shop/Lewshop1
                  country: []
                  category: []
                  salesTotal: 1
                  salesWeekly: 1
                  reviews: 1
                  favorites: 1
                  rating: 4.8
                  status: 1
                columns: []
                costToken: 3600
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      x-nexscope-slug: etsy-store-query
      x-nexscope-mcp-tool-name: nexscope_etsy_store_query
      x-nexscope-pricing-mode: dynamic-credits
      x-nexscope-catalog-derived: true
  /api/skill-api/v1/skills/etsy-product-detail/run:
    post:
      tags:
      - Etsy Marketplace
      summary: Etsy Product Detail
      description: Returns normalized public ecommerce research data with a fixed read-only provider path.
      operationId: runEtsyProductDetail
      externalDocs:
        description: Etsy Product Detail documentation
        url: https://www.nexscope.ai/api-docs/etsy-product-detail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - productUrl
              properties:
                productUrl:
                  type: string
                  format: uri
                  pattern: ^https://(?:[A-Za-z0-9-]+\.)*etsy\.com(?::443)?/listing/\d+(?:/[^/?#]+)?/?(?:[?#].*)?$
              description: Request parameters documented by ecommerce.etsy-product-detail.
              example:
                productUrl: https://www.etsy.com/listing/1710567856/its-okay-to-make-some-mistakes-shirt
            example:
              productUrl: https://www.etsy.com/listing/1710567856/its-okay-to-make-some-mistakes-shirt
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - product
                properties:
                  product:
                    type: object
                    additionalProperties: true
                    required:
                    - productId
                    properties:
                      productId:
                        type: string
                      productUrl:
                        type: string
                      title:
                        type: string
                      description:
                        type: string
                      images:
                        type: array
                      price:
                        type:
                        - number
                        - string
                      currency:
                        type: string
                      shopId:
                        type: string
                description: Returns the documented upstream API response directly without an additional wrapper.
              example:
                product:
                  productId: '1710567856'
                  title: Example Etsy product
                  images: []
                  price: 1
                  currency: EUR
        '400':
          ? ''
          : '#/components/responses/BadRequest'
        '401':
          ? ''
          : '#/components/responses/Unauthorized'
        '403':
          ? ''
          : '#/components/responses/Forbidden'
        '429':
          ? ''
          : '#/components/responses/TooManyRequests'
        '500':
          ? ''
          : '#/components/responses/ServerError'
      x-nexscope-slug: etsy-product-detail
      x-nexscope-mcp-tool-name: nexscope_etsy_product_detail
      x-nexscope-pricing-mode: dynamic-credits
      x-nexscope-catalog-derived: true
components:
  responses:
    ServerError:
      description: Server or upstream provider error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
    Forbidden:
      description: The account or API key is not allowed to use this capability.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
    TooManyRequests:
      description: Rate limit or account usage limit reached.
      headers:
        Retry-After:
          description: Retry delay when returned by the service.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
  schemas:
    CommonError:
      type: object
      description: Common API error envelope. Exact fields may vary by endpoint and upstream provider.
      properties:
        code:
          oneOf:
          - type: integer
          - type: string
          description: Application or provider error code.
        msg:
          type: string
          description: Error message.
        message:
          type: string
          description: Alternative error message field.
        traceId:
          type: string
          description: Support trace identifier when available.
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Nexscope API Key
externalDocs:
  description: Nexscope API Documentation
  url: https://www.nexscope.ai/api-docs
x-nexscope-source: https://api.nexscope.ai/api/skill-api/v1/api-docs
x-nexscope-pricing-mode: dynamic-credits
x-nexscope-mcp-endpoint: https://api.nexscope.ai/api/skill-api/v1/mcp