BidProwl Comps API

openapi: 3.2.0
info:
  title: BidProwl Comps API
  version: 1.0.0
  description: 'US government surplus auctions: live listings from 27 official sources with ZIP-radius search, sold-price comparables from 200,000+ closed auctions, nearly all from the last 12 months, and Flip Scores. Free tier: 1,000 calls/month. Get a key at https://bidprowl.com/account/api-keys.'
  contact:
    email: hello@bidprowl.com
    url: https://bidprowl.com/developers
  x-versioning:
    scheme: URL path (/api/v1). A breaking change ships as /api/v2; /api/v1 is never broken in place.
    deprecationPolicy: A deprecated endpoint returns the RFC 8594 `Deprecation` header with the date it was deprecated, and `Sunset` with the date it stops responding. Sunset is never less than 180 days after Deprecation, and both are announced at https://bidprowl.com/developers before they are sent.
    contact: hello@bidprowl.com
servers:
- url: https://bidprowl.com
security:
- bearerAuth: []
tags:
- name: Comps
paths:
  /api/v1/comps:
    get:
      operationId: getSoldComps
      summary: Sold-price comparables
      description: Category+state aggregates for every key. Item-level percentiles (item=) and per-listing comps with resale margin (listing_id=) require Pro or Pro+.
      parameters:
      - name: listing_id
        in: query
        schema:
          type: string
          format: uuid
      - name: item
        in: query
        schema:
          type: string
        description: Tracked item slug, e.g. forklift
      - name: category
        in: query
        schema:
          type: string
      - name: state
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Comparables
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SoldStats'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Comps
  /api/v1/comps/batch:
    post:
      operationId: getSoldCompsBatch
      summary: Many comps lookups in one request (one call per query)
      description: 'Each query is answered exactly as GET /api/v1/comps would answer it. A string query resolves as a listing id, a tracked item slug, a category slug, or free text naming a tracked item ("2015 Ford F150" resolves to ford-f-150); an object takes GET''s own params. Max 25 queries (100 on Pro+). Each query costs one call, charged all or nothing up front: a batch that would cross the monthly quota is refused with 429 and charges nothing. Per-item failures (unknown item, item-level comps on a free key) come back inside `data` with their own status and code.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - queries
              properties:
                queries:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    oneOf:
                    - type: string
                    - type: object
                      properties:
                        listing_id:
                          type: string
                          format: uuid
                        item:
                          type: string
                        category:
                          type: string
                        state:
                          type: string
                state:
                  type: string
                  description: Default state for item and category queries
            example:
              queries:
              - forklift
              - vehicles
              - item: rolex
                state: FL
              state: TX
      responses:
        '200':
          description: One result per query, in order
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        query: {}
                        resolved:
                          type: object
                        status:
                          type: integer
                        data:
                          type: object
                          description: As GET /api/v1/comps returns it
                        code:
                          type: string
                        error:
                          type: string
                        upgrade:
                          type: string
                  count:
                    type: integer
                  calls_charged:
                    type: integer
        '400':
          description: Malformed body or too many queries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceBusy'
      tags:
      - Comps
components:
  responses:
    NotFound:
      description: No such listing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key is valid but the plan does not include this data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-minute burst limit or monthly quota exhausted. Read Retry-After, and RateLimit-* to self-throttle before you get here.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceBusy:
      description: The endpoint is at its concurrency cap. Nothing was charged; retry after Retry-After seconds.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    Retry-After:
      description: Seconds to wait before retrying. Sent on every 429.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the monthly window resets (delta-seconds, per the RFC draft).
      schema:
        type: integer
    RateLimit-Remaining:
      description: Calls left in the current monthly window.
      schema:
        type: integer
    RateLimit-Limit:
      description: Calls allowed in the current monthly window.
      schema:
        type: integer
  schemas:
    SoldStats:
      type: object
      properties:
        median_cents:
          type: integer
        average_cents:
          type: integer
        min_cents:
          type: integer
        max_cents:
          type: integer
        sold_count:
          type: integer
        avg_bids:
          type: number
    Error:
      type: object
      required:
      - error
      - code
      - docs
      properties:
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          description: Machine-readable code. Branch on this, never on `error`.
          enum:
          - missing_api_key
          - invalid_api_key
          - forbidden
          - not_found
          - invalid_request
          - burst_rate_exceeded
          - monthly_quota_exceeded
          - service_busy
          - internal_error
        docs:
          type: string
          format: uri
        upgrade:
          type: string
          format: uri
          description: Present only when upgrading actually resolves the failure.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key (bp_live_...) from bidprowl.com/account/api-keys