openapi: 3.2.0
info:
  title: Nexscope Ecommerce Data and Creative eBay 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: eBay Marketplace
  description: eBay marketplace product search APIs.
  x-category-slug: ebay-marketplace
paths:
  /api/skill-api/v1/skills/ebay-search/run:
    post:
      tags:
      - eBay Marketplace
      summary: Ebay Search
      description: Search and browse product listings across multiple eBay international sites.
      operationId: runEbaySearch
      externalDocs:
        description: Ebay Search documentation
        url: https://www.nexscope.ai/api-docs/ebay-search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request parameters documented by ecommerce.ebay-search.
              properties:
                keyword:
                  type: string
                  description: Search keyword, max 1024 characters
                  example: phone case
                ebayDomain:
                  type: string
                  description: 'eBay site domain, default ebay.com. Options: ebay.com (United States), ebay.co.uk (United Kingdom), ebay.de (Germany), ebay.fr (France), ebay.it (Italy), ebay.es (Spain), ebay.ca (Canada), ebay.com.au (Australia), ebay.nl (Netherlands), ebay.at (Austria), ebay.ch (Switzerland), ebay.pl (Poland), ebay.ie (Ireland), ebay.com.hk (Hong Kong, China), ebay.com.my (Malaysia), ebay.com.sg (Singapore)'
                page:
                  type: integer
                  description: Page number for pagination, default 1
                  example: 1
                pageSize:
                  type: integer
                  description: 'Maximum results per page, default 50. Options: 25, 50, 100, 200'
                  example: 10
                orderBy:
                  type: string
                  description: 'Sort order, default 12 (Best Match). Options: 1 (Ending soonest), 2 (Price lowest), 3 (Price highest), 7 (Distance nearest), 10 (Newly listed), 12 (Best Match), 15 (Price + shipping lowest), 16 (Price + shipping highest), 18 (New first), 19 (Used first)'
                priceMin:
                  type: number
                  description: Minimum price filter
                  example: 1
                priceMax:
                  type: number
                  description: Maximum price filter
                  example: 1
                itemCondition:
                  type: string
                  description: Item condition code, multiple separated by \
                buyingFormat:
                  type: string
                  description: 'Buying format. Options: Auction, BIN (Buy It Now), BO (Best Offer)'
                showOnly:
                  type: string
                  description: 'Filter conditions, comma-separated for multiple values. Options: Complete (Ended), Sold (Sold), FR (Free returns), RPA (Returns accepted), AS (Authorized seller), Savings (Discounts), SaleItems (Sale items), Lots (Lots), Charity (Charity), AV, FS (Free shipping), LPickup (Local pickup)'
                location:
                  type: integer
                  description: Country/region code of item location (e.g., 1=United States, 2=Canada, 3=United Kingdom, 45=China, 77=Germany)
                  example: 1
                prefLoc:
                  type: string
                  description: 'Preferred location scope. Options: 1 (Domestic), 2 (Regional), 3 (Worldwide)'
                zipCode:
                  type: string
                  description: ZIP or postal code for filtering shippable items by region
                categoryId:
                  type: integer
                  description: eBay category ID for category-specific search
                  example: 1
                noCache:
                  type: boolean
                  description: Whether to bypass cache, default false
                  example: false
              example:
                page: 1
                keyword: phone case
                pageSize: 10
              additionalProperties: true
            example:
              page: 1
              keyword: phone case
              pageSize: 10
      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: Total matching results
                    example: 1
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        productId:
                          type: string
                          description: eBay product ID
                          example: example-id
                        title:
                          type: string
                          description: Product title
                        subtitle:
                          type: string
                          description: Product subtitle
                        price:
                          type: number
                          description: Current price / transaction price
                          example: 1
                        minPrice:
                          type: number
                          description: Price range start value (for multi-SKU items)
                          example: 1
                        maxPrice:
                          type: number
                          description: Price range end value (for multi-SKU items)
                          example: 1
                        oldPrice:
                          type: number
                          description: Original price before discount
                          example: 1
                        currency:
                          type: string
                          description: Currency unit (e.g., USD, GBP, EUR)
                        condition:
                          type: string
                          description: Item condition description
                        link:
                          type: string
                          description: eBay product detail page link
                        imageUrl:
                          type: string
                          description: Product thumbnail URL
                          example: https://example.com/image.jpg
                        shipping:
                          type: string
                          description: Shipping information
                        location:
                          type: string
                          description: Item location
                        sellerName:
                          type: string
                          description: Seller name
                        sellerReviews:
                          type: integer
                          description: Seller feedback count
                          example: 1
                        positiveFeedbackInPercentage:
                          type: number
                          description: Seller positive feedback percentage
                          example: 1
                        salesQuantity:
                          type: integer
                          description: Quantity sold
                          example: 1
                        bidsCount:
                          type: integer
                          description: Bid count (for auction items)
                          example: 1
                        returns:
                          type: string
                          description: Return information
                        promotion:
                          type: string
                          description: Promotion information
                        sponsored:
                          type: boolean
                          description: Whether sponsored/promoted item
                          example: false
                        sourceType:
                          type: string
                          description: Source platform identifier (ebay)
                        sourceTool:
                          type: string
                          description: Source tool identifier
                      additionalProperties: true
                    description: Product list array (see product fields below)
                    example: []
                  columns:
                    type: array
                    items: {}
                    description: Rendered column definitions
                    example: []
                  type:
                    type: string
                    description: Render style identifier
                  costToken:
                    type: integer
                    description: Token consumption
                    example: 1
                  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.
                  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
                  products:
                  - productId: example-id
                    price: 1
                    minPrice: 1
                    maxPrice: 1
                    oldPrice: 1
                    imageUrl: https://example.com/image.jpg
                    sellerReviews: 1
                    positiveFeedbackInPercentage: 1
                    salesQuantity: 1
                    bidsCount: 1
                    sponsored: false
                  columns: []
                  costToken: 1
                additionalProperties: true
              example:
                total: 1
                products:
                - productId: example-id
                  price: 1
                  minPrice: 1
                  maxPrice: 1
                  oldPrice: 1
                  imageUrl: https://example.com/image.jpg
                  sellerReviews: 1
                  positiveFeedbackInPercentage: 1
                  salesQuantity: 1
                  bidsCount: 1
                  sponsored: false
                columns: []
                costToken: 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: ebay-search
      x-nexscope-mcp-tool-name: nexscope_ebay_search
      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