compsniper-com Bulk Search API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping Bulk Search API
  version: 2.3.0
  description: Public eBay (including up to 3 years of sold history), Poshmark, Mercari, TCGplayer, Grailed, Depop and PSA graded card (prices by grade, population) data plus a separate quote-only US shipping-rates product. Shipping quotes separate applicable services from carrier-packaging and content-restricted options, use an independent subscription and quota, and do not consume sold-comps requests or purchased credits.
  contact:
    name: CompSniper
    url: https://compsniper.com
servers:
- url: https://api.compsniper.com
security:
- bearerAuth: []
tags:
- name: Bulk Search
paths:
  /v1/bulk-search:
    post:
      summary: Stream multiple keyword searches
      description: Search up to 20 unique keywords with at most three concurrent workers. If only part of the input fits the selected billing balance, the first keywords run and the remainder receive per-keyword quota_exceeded result events. Each successful keyword consumes one request; failures do not. Results stream as Server-Sent Events and may complete out of order.
      operationId: bulkSearch
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Replay a completed run with the identical request body without repeating searches or consuming quota.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkSearchRequest'
      responses:
        '200':
          description: SSE stream containing start, result, and complete events.
          content:
            text/event-stream:
              schema:
                type: string
                description: Each data field contains one JSON event payload.
        '400':
          description: Invalid keywords or shared options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Credential lacks comps:read scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: The idempotency key has another body, or a bulk run is already active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: No keyword can be allocated because the selected monthly and credit balance is empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Bulk Search
  /v1/bulk-search/{runId}/download.csv:
    get:
      summary: Download bulk-search CSV
      description: Download every successful keyword in one CSV, or pass index for one submitted keyword. Requires the same account's bearer credential.
      operationId: downloadBulkSearchCsv
      parameters:
      - name: runId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: index
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: Original zero-based keyword index. Omit for a combined CSV.
      responses:
        '200':
          description: CSV export.
          content:
            text/csv:
              schema:
                type: string
        '400':
          description: Invalid runId or index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Run or requested successful keyword not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: The run is still active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Bulk Search
components:
  parameters:
    CreditSource:
      name: X-Credit-Source
      in: header
      required: false
      schema:
        type: string
        enum:
        - credits
      description: Omit to use temporary carryover first, then monthly quota, then purchased credits. Set to credits to spend a purchased credit directly. Failed searches are not charged.
  schemas:
    BulkSearchRequest:
      type: object
      required:
      - keywords
      properties:
        keywords:
          type: array
          minItems: 1
          maxItems: 20
          description: Case-insensitively deduplicated product keywords. Each keyword may contain at most 300 characters.
          items:
            type: string
            maxLength: 300
        options:
          $ref: '#/components/schemas/BulkSearchOptions'
    BulkSearchOptions:
      type: object
      description: Shared page-one options applied independently to every keyword.
      properties:
        count:
          type: integer
          minimum: 1
          maximum: 240
          default: 240
        ebaySite:
          type: string
          enum:
          - ebay.com
          - ebay.co.uk
          - ebay.de
          - ebay.fr
          - ebay.it
          - ebay.es
          - ebay.ca
          - ebay.com.au
        categoryId:
          type: string
        sortOrder:
          type: string
          enum:
          - endedRecently
          - timeNewlyListed
          - pricePlusPostageLowest
          - pricePlusPostageHighest
          - distanceNearest
        minPrice:
          type: number
        maxPrice:
          type: number
        itemLocation:
          type: string
          enum:
          - default
          - domestic
          - worldwide
        itemCondition:
          type: string
          enum:
          - any
          - new
          - used
        conditionId:
          type: integer
          minimum: 0
        buyingFormat:
          type: string
          enum:
          - all
          - auction
          - buyItNow
          - acceptsOffers
        sellerType:
          type: string
          enum:
          - private
          - business
        includeCompleteListing:
          type: boolean
        sold:
          type: boolean
          default: true
        soldAfter:
          type: string
          format: date
        soldBefore:
          type: string
          format: date
        exactMatch:
          type: boolean
          default: false
        aspectFilter:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: array
              items:
                type: string
        relevance:
          type: boolean
          default: true
      additionalProperties: false
    ApiError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        retry_after:
          type: integer
          description: Seconds before a temporary rate_limited request may be retried.
        reset_at:
          type: string
          format: date-time
          description: Billing-cycle reset for quota_exceeded.
        plan:
          type: string
        quota:
          type: integer
        used:
          type: integer
        remaining:
          type: integer
        rollover_balance:
          type: integer
          description: Temporary carried-over requests remaining.
        upgrade_url:
          type: string
          format: uri
          description: Plan-management URL for quota_exceeded.
        credit_balance:
          type: integer
          description: Non-expiring purchased credits remaining.
        purchase_credits_url:
          type: string
          format: uri
          description: Credit purchase URL for quota_exceeded.
        subscription_url:
          type: string
          format: uri
          description: Shipping Rates plan URL for shipping_subscription_required or shipping_quota_exceeded.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'