BidProwl Usage API

openapi: 3.2.0
info:
  title: BidProwl Usage 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: Usage
paths:
  /api/v1/usage:
    get:
      operationId: getUsage
      summary: This key's plan, monthly quota, calls used and reset date
      description: Does not count against the quota. The same numbers ride on every response as RateLimit-* headers.
      responses:
        '200':
          description: Usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Usage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Usage
components:
  schemas:
    Usage:
      type: object
      properties:
        key_id:
          type: string
        plan:
          type: string
          enum:
          - free
          - pro
          - pro_plus
        period:
          type: string
          description: Quota month, YYYY-MM (UTC)
        limit:
          type: integer
        used:
          type: integer
        remaining:
          type: integer
        resets_at:
          type: string
          format: date-time
          description: First of next month, 00:00 UTC
        resets_at_epoch:
          type: integer
        batch_comps_max:
          type: integer
          description: Max queries per POST /api/v1/comps/batch
        features:
          type: object
          properties:
            item_comps:
              type: boolean
            sold_history_item_level:
              type: boolean
            csv_export:
              type: boolean
            webhooks:
              type: boolean
    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.
  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
  responses:
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key (bp_live_...) from bidprowl.com/account/api-keys