BidProwl Flip Score API

openapi: 3.2.0
info:
  title: BidProwl Flip Score 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: Flip Score
paths:
  /api/v1/flip-score/{id}:
    get:
      operationId: getFlipScore
      summary: Flip Score with factor breakdown and resale margin (Pro/Pro+)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Score detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      flip_score:
                        type: integer
                        minimum: 0
                        maximum: 100
                      factors:
                        type: object
                        additionalProperties:
                          type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Flip Score
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'
  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:
    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