compsniper-com Cards API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping Cards 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: Cards
paths:
  /v1/cards/batch:
    post:
      summary: Submit a sports or trading-card comps batch
      description: Submit up to 100 cards in one HTTP request. Cards are processed asynchronously and sequentially. Each successfully processed card consumes one normal monthly request.
      operationId: submitCardBatch
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Safely retry a submission without creating a duplicate job.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardBatchRequest'
      responses:
        '202':
          description: Batch accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardBatchAccepted'
        '400':
          description: Invalid card batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Another card batch is already active for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Submission rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Cards
  /v1/cards/batch/{jobId}:
    parameters:
    - name: jobId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      summary: Get card batch progress and results
      operationId: getCardBatch
      responses:
        '200':
          description: Current progress, including completed per-card results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardBatchJob'
        '404':
          description: Batch not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Cards
    delete:
      summary: Cancel a queued or running card batch
      operationId: cancelCardBatch
      responses:
        '200':
          description: Cancellation requested or existing terminal status returned.
        '404':
          description: Batch not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Cards
components:
  schemas:
    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.
    CardBatchRequest:
      type: object
      required:
      - cards
      properties:
        cards:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/CardInput'
        options:
          $ref: '#/components/schemas/CardBatchOptions'
    CardBatchAccepted:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          example: queued
        totalCards:
          type: integer
        billing:
          type: string
        resultsUrl:
          type: string
    CompactSoldItem:
      type: object
      properties:
        itemId:
          type: string
        title:
          type:
          - string
          - 'null'
        soldPrice:
          type:
          - string
          - 'null'
        currency:
          type:
          - string
          - 'null'
        shippingPrice:
          type:
          - string
          - 'null'
        totalPrice:
          type:
          - string
          - 'null'
        condition:
          type:
          - string
          - 'null'
        bestOfferAccepted:
          type:
          - boolean
          - 'null'
          description: true when eBay marked an accepted Best Offer; null otherwise. The accepted amount is not disclosed.
        soldDate:
          type:
          - string
          - 'null'
        sellerUsername:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
    CardInput:
      type: object
      description: Supply an exact keyword, or structured fields. subject is universal; player and character are convenient aliases.
      properties:
        reference:
          type: string
          description: Your inventory or correlation ID, echoed in the result.
        keyword:
          type: string
          maxLength: 300
          description: Exact eBay search keyword. When present it overrides generated structured-field keywords.
        subject:
          type: string
        player:
          type: string
        character:
          type: string
        year:
          oneOf:
          - type: string
          - type: number
        set:
          type: string
        cardNumber:
          oneOf:
          - type: string
          - type: number
        parallel:
          type: string
        grader:
          type: string
          example: PSA
        grade:
          oneOf:
          - type: string
          - type: number
          example: 10
    CardBatchJob:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - queued
          - running
          - done
          - partial
          - cancelled
          - failed
        totalCards:
          type: integer
        processedCards:
          type: integer
        remainingCards:
          type: integer
        succeededCards:
          type: integer
        failedCards:
          type: integer
        error:
          type:
          - string
          - 'null'
        results:
          type: array
          items:
            $ref: '#/components/schemas/CardBatchResult'
        upgradeUrl:
          type: string
          format: uri
          description: Present when processing stopped because the account quota was exhausted.
    CardBatchResult:
      type: object
      required:
      - keyword
      - ok
      properties:
        reference:
          type: string
        card:
          $ref: '#/components/schemas/CardInput'
        keyword:
          type: string
        ok:
          type: boolean
        totalResults:
          type:
          - string
          - 'null'
        totalItems:
          type: integer
        rawMedian:
          type:
          - number
          - 'null'
        rawSampleCount:
          type:
          - integer
          - 'null'
        summary:
          $ref: '#/components/schemas/PriceSummary'
        cached:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/CompactSoldItem'
        error:
          type: string
        code:
          type: string
    CardBatchOptions:
      type: object
      properties:
        ebaySite:
          type: string
          enum:
          - ebay.com
          - ebay.co.uk
          - ebay.de
          - ebay.fr
          - ebay.it
          - ebay.es
          - ebay.ca
          - ebay.com.au
        count:
          type: integer
          minimum: 1
          maximum: 240
          default: 60
          description: Maximum sold comps inspected per card. Compact output is capped at 60.
        itemCondition:
          type: string
          enum:
          - any
          - new
          - used
        soldAfter:
          type: string
          format: date
        soldBefore:
          type: string
          format: date
        exactMatch:
          type: boolean
          default: false
          description: Remove eBay's explicit Results matching fewer words section for each card search.
        relevance:
          type: boolean
          default: true
        outputMode:
          type: string
          enum:
          - summary
          - compact
          default: summary
          description: compact also returns compact sold-listing rows, including bestOfferAccepted, and is limited to 25 cards with count <= 60.
    PriceSummary:
      type:
      - object
      - 'null'
      description: Deterministic price intelligence over the returned sold items.
      properties:
        count:
          type: integer
          description: Items with a usable sold price.
        currency:
          type:
          - string
          - 'null'
        median:
          type: number
        mean:
          type: number
        min:
          type: number
        max:
          type: number
        p25:
          type: number
          description: Lower bound of the realistic range.
        p75:
          type: number
          description: Upper bound of the realistic range.
        avgShipping:
          type:
          - number
          - 'null'
  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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'