ProspectAPIs Account API

openapi: 3.2.0
info:
  title: ProspectAPIs Account API
  summary: Funding signals and cited prospect research over one REST API.
  description: 'The REST contract for ProspectAPIs: funding rounds you can filter and page, cited prospect research briefs, and funding watchlists that push new matches to a webhook. Built for sales teams and the AI agents that work for them.


    Authentication is a bearer API key (`Authorization: Bearer pa_live_`), created in the dashboard. `GET /pricing`, `GET /health` and `GET /v1/version` need no key.


    Every account starts with a one-time free balance (`signup_credit_usd` in `GET /pricing`), and every paid call draws from it at its own price: `GET /v1/funding` per returned record (a no-match is free), `POST /v1/email/verify` per valid or invalid result, `POST /v1/research` per completed brief. Paid responses carry `X-Credits-Remaining`. The live price list is `GET /pricing`; a key''s balance is `GET /v1/account`. This document describes shapes, not prices.'
  version: 0.1.0
  contact:
    name: ProspectAPIs
    url: https://prospectapis.com
    email: emma@prospectapis.com
  license:
    name: Proprietary
    url: https://prospectapis.com/terms
  termsOfService: https://prospectapis.com/terms
servers:
- url: https://api.prospectapis.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Account
  description: Your balance, feedback and the API version.
paths:
  /v1/account:
    get:
      tags:
      - Account
      summary: Account balance
      description: The calling key's balance and the current prices. Free, so an agent can check before a costed run instead of discovering the balance through a 402.
      operationId: getAccount
      responses:
        '200':
          description: The account's balance and prices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              example:
                credits_remaining: 0.991
                signup_credit_usd: 1
                free_records_remaining: 0
                free_records_per_month: 0
                free_period_start: '2026-11-01'
                price_per_record_usd: 0.009
                price_per_verification_usd: 0.003
                research_price_usd: 0.15
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
  /v1/feedback:
    post:
      tags:
      - Account
      summary: Send feedback
      description: Report a bug, a wrong or empty field, or a missing capability to the team. The report is stored first, then posted to the team; read it back, with its status and the team's response, at GET /v1/feedback/{id}. Free; at most 10 an hour per account.
      operationId: sendFeedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
            example:
              kind: bug
              title: country filter ignores accents
              details: GET /v1/funding?country=Curaçao returned 0 records; expected 2.
      responses:
        '202':
          description: The report was stored. status is sent when the team was alerted, stored when the alert to the team failed and the team sees it in its triage instead (the report is kept either way).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackAccepted'
              example:
                feedback_id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                status: sent
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/FeedbackUnavailable'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      x-agentic-access:
        action-class: acting
        consequence: write
        subject: required
        audience: null
        token:
          max-ttl: 900
        escalation:
          human-in-the-loop: conditional
          triggers:
          - abnormal
          - high-value
        audit: required
        idempotency-key: Idempotency-Key header, replayed for 24 hours
    get:
      tags:
      - Account
      summary: List your feedback
      description: The reports this account sent with POST /v1/feedback (any of its keys), newest first, each with its status and the team's response. Free.
      operationId: listFeedback
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A page of this account's reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackList'
              example:
                data:
                - id: 3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13
                  kind: bug
                  tool: funding_search
                  title: country filter ignores accents
                  details: GET /v1/funding?country=Curaçao returned 0 records; expected 2.
                  status: fixed
                  response: 'Fixed: accents now match.'
                  responded_at: '2026-11-02T09:30:00Z'
                  created_at: '2026-11-01T18:04:11Z'
                  updated_at: '2026-11-02T09:30:00Z'
                  from_this_key: true
                next_cursor: next cursor
                count: 1
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
  /v1/feedback/{id}:
    get:
      tags:
      - Account
      summary: Read one feedback report
      description: One report this account sent, with its status and the team's response. A report another account sent answers 404, the same as an id that does not exist. Free.
      operationId: getFeedback
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feedback'
              example:
                id: 3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13
                kind: bug
                tool: funding_search
                title: country filter ignores accents
                details: GET /v1/funding?country=Curaçao returned 0 records; expected 2.
                status: fixed
                response: 'Fixed: accents now match.'
                responded_at: '2026-11-02T09:30:00Z'
                created_at: '2026-11-01T18:04:11Z'
                updated_at: '2026-11-02T09:30:00Z'
                from_this_key: true
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
  /v1/version:
    get:
      tags:
      - Account
      summary: API version
      description: The API version and the deployed git sha. Free, no key.
      operationId: getVersion
      security: []
      responses:
        '200':
          description: The API version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
              example:
                version: version
                git_sha: git sha
        '500':
          $ref: '#/components/responses/InternalError'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
components:
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid (e.g. a bad filter or input); nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: An unexpected server error; nothing was charged. Retry shortly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error
    FeedbackUnavailable:
      description: Feedback is not being accepted right now, or the report could not be recorded; nothing was stored. Retry shortly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; retry after the window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such record for this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    FeedbackRequest:
      type: object
      example:
        kind: bug
        title: country filter ignores accents
        details: GET /v1/funding?country=Curaçao returned 0 records; expected 2.
      required:
      - title
      - details
      properties:
        kind:
          type: string
          enum:
          - bug
          - feature
          - question
          default: bug
        title:
          type: string
          minLength: 1
          maxLength: 200
        details:
          type: string
          minLength: 1
          maxLength: 8000
        tool:
          type: string
          maxLength: 60
          description: The tool or endpoint the report is about, e.g. research_get.
      additionalProperties: false
    FeedbackList:
      type: object
      required:
      - data
      - next_cursor
      - count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Feedback'
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass back as cursor for the next page; null on the last page.
        count:
          type: integer
    Feedback:
      type: object
      required:
      - id
      - kind
      - tool
      - title
      - details
      - status
      - response
      - responded_at
      - created_at
      - updated_at
      - from_this_key
      properties:
        id:
          type: string
          format: uuid
          description: The feedback_id POST /v1/feedback returned.
        kind:
          type: string
          enum:
          - bug
          - feature
          - question
        tool:
          type:
          - string
          - 'null'
          description: The tool or endpoint the report is about, when one was named.
        title:
          type: string
        details:
          type: string
        status:
          type: string
          enum:
          - received
          - triaged
          - fixed
          - wont_fix
          - needs_info
          description: 'received: not looked at yet. triaged: the team is on it. fixed: shipped. wont_fix: not planned (the response says why). needs_info: the team needs more from you (see response).'
        response:
          type:
          - string
          - 'null'
          description: The team's reply, when there is one.
        responded_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          description: The last change to status or response.
        from_this_key:
          type: boolean
          description: true when the API key making this call sent the report; another key of the same account reads it too.
      example:
        id: 3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13
        kind: bug
        tool: funding_search
        title: country filter ignores accents
        details: GET /v1/funding?country=Curaçao returned 0 records; expected 2.
        status: fixed
        response: 'Fixed: accents now match.'
        responded_at: '2026-11-02T09:30:00Z'
        created_at: '2026-11-01T18:04:11Z'
        updated_at: '2026-11-02T09:30:00Z'
        from_this_key: true
    FeedbackAccepted:
      type: object
      required:
      - feedback_id
      - status
      properties:
        feedback_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - sent
          - stored
          description: 'sent: stored and the team was alerted. stored: stored, the alert failed; the team sees it in its triage.'
    Version:
      type: object
      required:
      - version
      - git_sha
      properties:
        version:
          type: string
          description: The SemVer API version.
        git_sha:
          type:
          - string
          - 'null'
          description: The deployed commit, when set.
    Account:
      type: object
      required:
      - credits_remaining
      - free_records_remaining
      - price_per_record_usd
      - research_price_usd
      properties:
        credits_remaining:
          type: number
          description: USD credits left, including what is left of the signup balance.
        signup_credit_usd:
          type: number
          description: The one-time balance every account starts with.
        free_records_remaining:
          type: integer
          description: Kept for older clients; always 0 since 2026-10-25.
        free_records_per_month:
          type: integer
          description: Kept for older clients; always 0.
        free_period_start:
          type: string
          format: date
          description: Kept for older clients.
        price_per_record_usd:
          type: number
        price_per_verification_usd:
          type: number
          description: The price of one charged email verification result.
        research_price_usd:
          type:
          - number
          - 'null'
          description: The price of one POST /v1/research, or null while research is not priced.
    Error:
      type: object
      required:
      - error
      description: Every error answers with this shape. `error` is a human-readable message; `code` is a stable machine code when present.
      properties:
        error:
          type: string
        code:
          type: string
          description: A stable error code, e.g. INVALID_FILTER, INVALID_INPUT, INVALID_ID, NOT_FOUND, INSUFFICIENT_CREDITS, WATCHLIST_LIMIT, RATE_LIMITED.
        message:
          type: string
          description: Extra guidance on some errors (401, 402).
        field:
          type: string
          description: The offending field, on some 400s.
        top_up_url:
          type: string
          format: uri
          description: Where to add credits, on a 402.
      additionalProperties: true
  parameters:
    cursor:
      name: cursor
      in: query
      description: The previous page's `next_cursor`, passed back unchanged.
      schema:
        type: string
    id:
      name: id
      in: path
      required: true
      description: A UUID.
      schema:
        type: string
        format: uuid
      example: 3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional, 1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours gets the first answer back with Idempotent-Replayed: true and is never charged again. The same key with a different body is 422; a retry while the first call is still running is 409.'
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: order-42
    limit:
      name: limit
      in: query
      description: Page size, 1 to 100 (default 25).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
      example: 10
  headers:
    RateLimit-Limit:
      description: Requests this API key may make per minute.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window resets.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key as a bearer token: `Authorization: Bearer pa_live_<48 hex>`. Create and manage keys in the dashboard at https://prospectapis.com.'
externalDocs:
  description: API reference and quickstart
  url: https://prospectapis.com/docs