compsniper-com PSA API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping PSA 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: PSA
paths:
  /v1/psa/search:
    get:
      tags:
      - PSA
      operationId: searchPsaCards
      summary: Find a PSA graded card and its specId
      description: Search PSA's card catalog (sports and trading cards) by name, set and number. Each match has the specId used by /v1/psa/card. One successful call uses one request.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: keyword
        in: query
        required: true
        schema:
          type: string
          maxLength: 200
          example: charizard base set
          description: Card name, set and number
      - name: count
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 10
          description: Number of matches
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 1
          description: Page
      responses:
        '200':
          description: Matching PSA cards
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyword:
                    type: string
                  marketplace:
                    type: string
                    example: psa
                  totalResults:
                    type: integer
                  totalItems:
                    type: integer
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        specId:
                          type: string
                        description:
                          type: string
                        subject:
                          type: string
                        cardNumber:
                          type:
                          - string
                          - 'null'
                        setName:
                          type:
                          - string
                          - 'null'
                        year:
                          type:
                          - string
                          - 'null'
                        category:
                          type:
                          - string
                          - 'null'
        '400':
          description: 'invalid_params: a parameter is missing or invalid'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '429':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '502':
          description: 'upstream_blocked: PSA did not complete this call; retry after a short pause (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '503':
          description: 'server_busy: retry after retry_after seconds (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
  /v1/psa/card:
    get:
      tags:
      - PSA
      operationId: getPsaCard
      summary: PSA graded card prices by grade, recent sales and population report
      description: 'For one PSA card: sold prices by grade (sales, average, min, max, latest), recent individual sales with grading company, grade and cert number, the population report with gem rate, and a price summary. Send specId from /v1/psa/search, or a keyword and the best match is used (others listed in otherMatches). One successful call uses one request; a card PSA does not have returns 404 not_found and is not charged.'
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: specId
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{1,12}$
          example: '5217539'
          description: PSA spec ID (required unless keyword is sent)
      - name: keyword
        in: query
        required: false
        schema:
          type: string
          maxLength: 200
          example: 1999 pokemon base set charizard 4
          description: Card name, set and number (used when specId is not sent)
      - name: count
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 50
          default: 10
          description: Recent sales to return in items
      - name: timeRange
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 120
          default: 0
          description: Months of sales to include (0 = all available)
      - name: grade
        in: query
        required: false
        schema:
          type: string
          example: '10'
          description: Filter items to one PSA grade from 1 to 10 (half grades allowed) or raw
      responses:
        '200':
          description: Prices by grade, sales and population
          content:
            application/json:
              schema:
                type: object
                properties:
                  card:
                    type: object
                    properties:
                      specId:
                        type: string
                      subject:
                        type: string
                      cardNumber:
                        type:
                        - string
                        - 'null'
                      setName:
                        type:
                        - string
                        - 'null'
                      year:
                        type:
                        - string
                        - 'null'
                  priceByGrade:
                    type: array
                    items:
                      type: object
                      properties:
                        grade:
                          type: string
                        sales:
                          type: integer
                        averagePrice:
                          type:
                          - number
                          - 'null'
                        minPrice:
                          type:
                          - number
                          - 'null'
                        maxPrice:
                          type:
                          - number
                          - 'null'
                        latestPrice:
                          type:
                          - number
                          - 'null'
                  population:
                    type:
                    - object
                    - 'null'
                    properties:
                      total:
                        type: integer
                      gemRate:
                        type:
                        - number
                        - 'null'
                        description: Share graded 10, percent
                      grades:
                        type: array
                        items:
                          type: object
                          properties:
                            grade:
                              type: string
                              example: '10'
                            count:
                              type: integer
                            withQualifier:
                              type: integer
                              description: Copies graded with a qualifier, for example 9 OC
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        saleDate:
                          type: string
                          format: date-time
                        salePrice:
                          type: number
                        saleType:
                          type: string
                          example: Auction
                        gradingCompany:
                          type: string
                          example: PSA
                        grade:
                          type:
                          - string
                          - 'null'
                        certNumber:
                          type:
                          - string
                          - 'null'
                        url:
                          type:
                          - string
                          - 'null'
                  summary:
                    $ref: '#/components/schemas/PriceSummary'
                  otherMatches:
                    type: array
                    items:
                      type: object
        '400':
          description: 'invalid_params: a parameter is missing or invalid'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '429':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '502':
          description: 'upstream_blocked: PSA did not complete this call; retry after a short pause (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '503':
          description: 'server_busy: retry after retry_after seconds (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '404':
          description: 'not_found: PSA has no card for this specId or keyword (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
  /v1/psa/sets:
    get:
      tags:
      - PSA
      operationId: listPsaSets
      summary: Find PSA sets or list every set for a game
      description: Send a game to list every PSA set for that game, newest first and paged; add keyword or year to narrow it. Without game, keyword searches set names across all games. Each set has the headingId used by /v1/psa/set.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: game
        in: query
        required: false
        schema:
          type: string
          enum:
          - pokemon
          - one-piece
          - magic
          - yugioh
          - dragon-ball
          - lorcana
          - digimon
          - weiss-schwarz
          - union-arena
          - flesh-and-blood
          - star-wars-unlimited
          - cardfight-vanguard
          - duel-masters
          - battle-spirits
          - final-fantasy
          - gundam
          - shadowverse
          - riftbound
          - grand-archive
          - wixoss
          description: Game to list every set for
      - name: keyword
        in: query
        required: false
        schema:
          type: string
          minLength: 2
          maxLength: 120
          example: '151'
          description: Words in the set name (required unless game is sent)
      - name: year
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{4}$
          description: 4-digit year
      - name: count
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          description: Sets per page
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1
          description: Page
      responses:
        '200':
          description: PSA sets
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyword:
                    type: string
                  marketplace:
                    type: string
                    example: psa
                  game:
                    type:
                    - string
                    - 'null'
                  page:
                    type: integer
                  hasNextPage:
                    type: boolean
                  totalResults:
                    type: integer
                  totalItems:
                    type: integer
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        headingId:
                          type: string
                        name:
                          type: string
                        year:
                          type:
                          - string
                          - 'null'
                        url:
                          type: string
                        gradedTotal:
                          type:
                          - integer
                          - 'null'
        '400':
          description: 'invalid_params: a parameter is missing or invalid'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '429':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '502':
          description: 'upstream_blocked: PSA did not complete this call; retry after a short pause (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '503':
          description: 'server_busy: retry after retry_after seconds (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
  /v1/psa/set:
    get:
      tags:
      - PSA
      operationId: getPsaSetPopulation
      summary: PSA population of every card in a set, by grade
      description: One call returns every card in a PSA set with its number, name, variety, specId and population for every grade (Authentic, then 1 to 10 including half grades), plus totals for the set. Send headingId from /v1/psa/sets or the set's PSA population page url. Large sets can take 10 to 20 seconds.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: headingId
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{1,12}$
          example: '57801'
          description: PSA set ID (required unless url is sent)
      - name: url
        in: query
        required: false
        schema:
          type: string
          example: https://www.psacard.com/pop/tcg-cards/1999/pokemon-game/57801
          description: The set's PSA population page
      responses:
        '200':
          description: Set population
          content:
            application/json:
              schema:
                type: object
                properties:
                  set:
                    type: object
                    properties:
                      headingId:
                        type: string
                      name:
                        type: string
                      year:
                        type:
                        - string
                        - 'null'
                      gradedTotal:
                        type:
                        - integer
                        - 'null'
                  totalCards:
                    type: integer
                  totals:
                    type: object
                    properties:
                      total:
                        type: integer
                      grades:
                        type: array
                        items:
                          type: object
                          properties:
                            grade:
                              type: string
                              example: '10'
                            count:
                              type: integer
                            withQualifier:
                              type: integer
                              description: Copies graded with a qualifier, for example 9 OC
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        specId:
                          type: string
                        cardNumber:
                          type:
                          - string
                          - 'null'
                        name:
                          type: string
                        variety:
                          type:
                          - string
                          - 'null'
                        population:
                          type: object
                          properties:
                            total:
                              type: integer
                            grades:
                              type: array
                              items:
                                type: object
                                properties:
                                  grade:
                                    type: string
                                    example: '10'
                                  count:
                                    type: integer
                                  withQualifier:
                                    type: integer
                                    description: Copies graded with a qualifier, for example 9 OC
        '400':
          description: 'invalid_params: a parameter is missing or invalid'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '429':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '502':
          description: 'upstream_blocked: PSA did not complete this call; retry after a short pause (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '503':
          description: 'server_busy: retry after retry_after seconds (not charged)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
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:
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'