ProspectAPIs Launches API

openapi: 3.2.0
info:
  title: ProspectAPIs Launches 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: Launches
  description: 'Launch events as prospecting triggers: a company said it launched (stage post) or is about to (stage pre). Not available yet: 503 until GET /pricing reports launches available.'
paths:
  /v1/launches:
    get:
      tags:
      - Launches
      summary: Search launch events
      operationId: searchLaunches
      description: 'Keyset-paginated launch events, newest launch first. Not available yet: answers 503 and charges nothing until GET /pricing reports launches available. Pass `next_cursor` back as `cursor` for the next page.'
      parameters:
      - $ref: '#/components/parameters/since'
      - $ref: '#/components/parameters/until'
      - name: stage
        in: query
        required: false
        schema:
          type: string
        description: post, pre, or both comma-separated.
      - name: launch_type
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated: new_company, new_product, major_version, feature.'
      - $ref: '#/components/parameters/domain'
      - $ref: '#/components/parameters/company'
      - name: category
        in: query
        required: false
        schema:
          type: string
        description: A category such as ai, saas or hardware.
      - $ref: '#/components/parameters/country'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A page of launch events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LaunchList'
              example:
                data:
                - id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                  stage: post
                  company_domain: acme.com
                  source_url: https://acme.com
                  launched_at: '2026-11-01T12:00:00Z'
                  detected_at: '2026-11-01T12:00:00Z'
                  gate_version: gate version
                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'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Launch events are not available yet (GET /pricing launches.available is false). Nothing is charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
  /v1/launches/{id}:
    get:
      tags:
      - Launches
      summary: Get one launch event
      operationId: getLaunch
      description: 'One launch event by id. Not available yet: answers 503 and charges nothing until GET /pricing reports launches available; a missing id is a free 404.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: A launch id from GET /v1/launches.
      responses:
        '200':
          description: The launch event.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Launch'
              example:
                data:
                  id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                  stage: post
                  company_domain: acme.com
                  source_url: https://acme.com
                  launched_at: '2026-11-01T12:00:00Z'
                  detected_at: '2026-11-01T12:00:00Z'
                  gate_version: gate version
          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'
        '404':
          description: No launch event with that id. Free.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Launch events are not available yet (GET /pricing launches.available is false). Nothing is charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      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'
    PaymentRequired:
      description: Out of credits. The body carries `top_up_url`; nothing was charged.
      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'
    BadRequest:
      description: The request was invalid (e.g. a bad filter or input); nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    country:
      name: country
      in: query
      description: Headquarters country. A country name or any two-letter ISO 3166-1 code (United States, US, Germany, DE) matches country_code exactly; any other text, such as a city, matches the stated place (the record's location), case-insensitive.
      schema:
        type: string
        maxLength: 60
    limit:
      name: limit
      in: query
      description: Page size, 1 to 100 (default 25).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
      example: 10
    domain:
      name: domain
      in: query
      description: Exact company domain, a bare domain such as `example.com`.
      schema:
        type: string
      example: example.com
    cursor:
      name: cursor
      in: query
      description: The previous page's `next_cursor`, passed back unchanged.
      schema:
        type: string
    company:
      name: company
      in: query
      description: Case-insensitive substring match on the company name (1 to 100 characters).
      schema:
        type: string
        maxLength: 100
    since:
      name: since
      in: query
      description: Only rounds announced on or after this date (inclusive), YYYY-MM-DD.
      schema:
        type: string
        format: date
      example: '2026-10-01'
    until:
      name: until
      in: query
      description: Only rounds announced on or before this date (inclusive), YYYY-MM-DD.
      schema:
        type: string
        format: date
  schemas:
    Launch:
      type: object
      description: 'One launch event, a prospecting trigger: who launched what, the company domain, the founder or poster to contact, and the company''s funding, HQ, size and category. Carries a link to the company''s own post or page and derived fields only, never the post text or media. A record that fails the relevance gate or resolves no domain is never served; a duplicate is served free.'
      required:
      - id
      - stage
      - company_domain
      - source_url
      - launched_at
      - detected_at
      - gate_version
      properties:
        id:
          type: string
          format: uuid
        stage:
          type: string
          enum:
          - post
          - pre
          description: 'post: launched and usable now. pre: the company itself says it is about to launch; never a prediction.'
        launch_type:
          type:
          - string
          - 'null'
          enum:
          - new_company
          - new_product
          - major_version
          - feature
          - null
        company_name:
          type:
          - string
          - 'null'
        company_domain:
          type: string
          example: acme.com
        product_name:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
        country_code:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2, when known.
        source_url:
          type: string
          format: uri
          description: The company's own post or page.
        launched_at:
          type: string
          format: date-time
        detected_at:
          type: string
          format: date-time
        person_ref:
          type:
          - string
          - 'null'
          description: An opaque reference to the founder or poster (per_ plus 24 hex). With `person_name` and `company_domain` it is the input to POST /v1/email/find and the people reads.
        person_name:
          type:
          - string
          - 'null'
          description: The founder's or poster's public name.
        poster_role:
          type:
          - string
          - 'null'
          enum:
          - company
          - founder
          - employee
          - null
        gate_version:
          type: string
          description: The relevance gate version that passed this record.
        updated_at:
          type: string
          format: date-time
        company:
          type:
          - object
          - 'null'
          description: The launching company's context from its company profile, or null when no profile is built yet.
          properties:
            hq:
              description: Headquarters as the company states it.
            size:
              type:
              - string
              - 'null'
              description: Employee band, such as 11-50.
            industry:
              type:
              - string
              - 'null'
            founded_year:
              type:
              - integer
              - 'null'
        funding:
          type:
          - object
          - 'null'
          description: The newest funding round we hold for the company domain, with the count and known total, or null when we hold none.
          properties:
            last_funding_id:
              type:
              - string
              - 'null'
              description: Pass to GET /v1/funding/{id}.
            last_round:
              type:
              - string
              - 'null'
            last_round_stage:
              type:
              - string
              - 'null'
            last_amount_usd:
              type:
              - number
              - 'null'
            last_announced_at:
              type:
              - string
              - 'null'
              format: date
            last_source_url:
              type:
              - string
              - 'null'
              format: uri
            rounds_known:
              type: integer
            total_known_usd:
              type:
              - number
              - 'null'
        duplicate_of:
          type:
          - string
          - 'null'
          format: uuid
          description: The id of an earlier record of the same launch (same company, same stage, within 7 days). A duplicate is served but never charged.
    LaunchList:
      type: object
      required:
      - data
      - next_cursor
      - count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Launch'
        next_cursor:
          type:
          - string
          - 'null'
        count:
          type: integer
    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
  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