ProspectAPIs Watchlists API

openapi: 3.2.0
info:
  title: Prospectapis Watchlists API
  x-refined-note:
  - x-authored-by differs across the merged source definitions and was not carried
  - x-engine differs across the merged source definitions and was not carried
  - x-evidence-tiers differs across the merged source definitions and was not carried
  - x-generated differs across the merged source definitions and was not carried
  - x-generated-from differs across the merged source definitions and was not carried
  - x-generator differs across the merged source definitions and was not carried
  - x-provenance differs across the merged source definitions and was not carried
  - x-sources differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Watchlists across 2 of this provider''s published API definitions: prospectapis-openapi-generated.yml, prospectapis-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.prospectapis.com
tags:
- name: Watchlists
paths:
  /v1/watchlists/{id}:
    delete:
      operationId: delete_v1_watchlists_id
      tags:
      - Watchlists
      summary: Delete a watchlist
      x-source: https://prospectapis.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
      security:
      - bearer: []
    get:
      tags:
      - Watchlists
      summary: Read a watchlist
      description: One watchlist, without its signing secret. Free.
      operationId: getWatchlist
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The watchlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
              example:
                id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                name: Jane Doe
                kind: funding
                filters:
                  round: series_a,series_b
                  min_amount_usd: 1000000
                  max_amount_usd: 50000000
                  company: Acme
                  domain: acme.com
                  investor: investor
                  country: US
                  stage: stage
                  launch_type: launch type
                  category: category
                  platform: platform
                  level: company
                webhook_url: https://acme.com
                active: true
                paused_reason: paused reason
                created_at: '2026-11-01T12:00:00Z'
          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
      security:
      - bearer: []
    servers:
    - url: https://api.prospectapis.com
  /v1/watchlists/{id}/deliveries:
    get:
      operationId: get_v1_watchlists_id_deliveries
      tags:
      - Watchlists
      summary: Get watchlist deliveries
      x-source: https://prospectapis.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
      security:
      - bearer: []
    servers:
    - url: https://api.prospectapis.com
  /v1/watchlists/{id}/test:
    post:
      operationId: post_v1_watchlists_id_test
      tags:
      - Watchlists
      summary: Test a watchlist webhook
      x-source: https://prospectapis.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
      security:
      - bearer: []
    servers:
    - url: https://api.prospectapis.com
  /v1/watchlists:
    post:
      tags:
      - Watchlists
      summary: Create a watchlist
      description: Save a set of funding filters plus an https webhook. New matches are pushed as signed `funding_event.matched` events. Free to create; each delivered record costs one record, charged only when your webhook answers 2xx. The signing `secret` is in this response and nowhere else. At most 20 active watchlists per account.
      operationId: createWatchlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistRequest'
            example:
              name: Seed rounds in Germany
              filters:
                round: seed
                country: Germany
              webhook_url: https://hooks.example.com/funding
      responses:
        '201':
          description: The watchlist, including its signing secret (shown only here).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistWithSecret'
              example:
                id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                name: Jane Doe
                kind: funding
                filters:
                  round: series_a,series_b
                  min_amount_usd: 1000000
                  max_amount_usd: 50000000
                  company: Acme
                  domain: acme.com
                  investor: investor
                  country: US
                  stage: stage
                  launch_type: launch type
                  category: category
                  platform: platform
                  level: company
                webhook_url: https://acme.com
                active: true
                paused_reason: paused reason
                created_at: '2026-11-01T12:00:00Z'
                secret: <signing secret, shown once>
          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'
        '409':
          $ref: '#/components/responses/WatchlistLimit'
        '429':
          $ref: '#/components/responses/RateLimited'
      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
      security:
      - bearerAuth: []
    get:
      tags:
      - Watchlists
      summary: List watchlists
      description: This account's watchlists, newest first, without their signing secrets. Free.
      operationId: listWatchlists
      responses:
        '200':
          description: The account's watchlists.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Watchlist'
              example:
                data:
                - id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                  name: Jane Doe
                  kind: funding
                  filters:
                    round: series_a,series_b
                    min_amount_usd: 1000000
                    max_amount_usd: 50000000
                    company: Acme
                    domain: acme.com
                    investor: investor
                    country: US
                    stage: stage
                    launch_type: launch type
                    category: category
                    platform: platform
                    level: company
                  webhook_url: https://acme.com
                  active: true
                  paused_reason: paused reason
                  created_at: '2026-11-01T12:00:00Z'
          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'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
      security:
      - bearerAuth: []
    servers:
    - url: https://api.prospectapis.com
      description: Production
components:
  parameters:
    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
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      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'
    NotFound:
      description: No such record for this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    WatchlistLimit:
      description: The account already has the maximum number of active watchlists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Delivery:
      type: object
      required:
      - id
      - event_id
      - status
      - attempts
      - created_at
      properties:
        id:
          type: string
          format: uuid
        event_id:
          type: string
          format: uuid
          description: The funding round that matched.
        status:
          type: string
          description: pending, sending, delivered, retry, no_credit or failed.
        attempts:
          type: integer
        http_status:
          type:
          - integer
          - 'null'
        error:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        delivered_at:
          type:
          - string
          - 'null'
          format: date-time
    Watchlist:
      type: object
      required:
      - id
      - name
      - filters
      - webhook_url
      - active
      - created_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        kind:
          type: string
          enum:
          - funding
          - ads
        filters:
          $ref: '#/components/schemas/WatchlistFilters'
        webhook_url:
          type: string
          format: uri
        active:
          type: boolean
        paused_reason:
          type:
          - string
          - 'null'
          description: Why it was paused, if it was (revoked key, repeated webhook failures, filters no longer valid).
        created_at:
          type: string
          format: date-time
    WatchlistFilters:
      type: object
      description: The GET /v1/funding filters a watchlist may hold (date windows and paging belong to the API call, not to an alert). At least one is required. Values may be strings or numbers. An ads watchlist (kind ads) takes domain (required) and platform. An events watchlist (kind events) takes city (required) and optionally platform, category, min_guests, max_guests, host, speaker, q and free.
      properties:
        round:
          type: string
          example: series_a,series_b
        min_amount_usd:
          type:
          - number
          - string
        max_amount_usd:
          type:
          - number
          - string
        company:
          type: string
        domain:
          type: string
        investor:
          type: string
        country:
          type: string
          description: 'As the country filter of GET /v1/funding: a country name or ISO code matches country_code.'
        stage:
          type: string
          description: 'Launch watchlists: post, pre or both.'
        launch_type:
          type: string
          description: 'Launch watchlists: comma-separated launch types.'
        category:
          type: string
          description: 'Launch watchlists: a category.'
        platform:
          type: string
          description: 'Ads watchlists: one or more of meta, google, linkedin, tiktok. Events watchlists: luma, partiful or both. Comma separated; omit for all.'
        level:
          type: string
          enum:
          - company
          - ad
          description: 'Ads watchlists only: company (default) delivers advertiser_started, advertiser_stopped and new_creatives; ad delivers every ad''s ad_started, ad_stopped and new_creative.'
        city:
          type: string
          description: 'Events watchlists: a city slug or name (required).'
        min_guests:
          type:
          - string
          - number
          - boolean
          description: 'Events watchlists: at least this many guests.'
        max_guests:
          type:
          - string
          - number
          - boolean
          description: 'Events watchlists: at most this many guests.'
        host:
          type: string
          description: 'Events watchlists: a host name or handle.'
        speaker:
          type: string
          description: 'Events watchlists: a speaker, host or name in the title.'
        q:
          type: string
          description: 'Events watchlists: the title contains this text.'
        free:
          type:
          - string
          - number
          - boolean
          description: 'Events watchlists: true or false.'
      additionalProperties: false
    WatchlistTestResult:
      type: object
      required:
      - delivered
      properties:
        delivered:
          type: boolean
        http_status:
          type:
          - integer
          - 'null'
          description: The status your webhook answered, if it responded.
        error:
          type:
          - string
          - 'null'
    WatchlistWithSecret:
      allOf:
      - $ref: '#/components/schemas/Watchlist'
      - type: object
        required:
        - secret
        properties:
          secret:
            type: string
            description: The webhook signing secret (whsec_...). Shown only in this create response.
    WatchlistRequest:
      type: object
      example:
        name: Seed rounds in Germany
        filters:
          round: seed
          country: Germany
        webhook_url: https://hooks.example.com/funding
      required:
      - name
      - filters
      - webhook_url
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        filters:
          $ref: '#/components/schemas/WatchlistFilters'
        webhook_url:
          type: string
          format: uri
          description: An https URL on a public host that receives signed match events.
        kind:
          type: string
          enum:
          - funding
          - launches
          - ads
          - events
          default: funding
          description: 'What to watch. funding (default): GET /v1/funding filters, $0.009 per delivered record. launches: launch events (filters stage, launch_type, domain, company, category, country), refused with 503 while launches are not available. ads: filters {domain, platform, level}, $0.006 per delivered event, refused with 503 while the ads family is off. events: new public events in a city (filters city plus optionally platform, category, min_guests, max_guests, host, speaker, q, free), one delivery per event at GET /pricing events.price_per_delivered_event_usd, refused with 503 while events are not available.'
      additionalProperties: false
    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-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
    RateLimit-Limit:
      description: Requests this API key may make per minute.
      schema:
        type: integer
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
    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
x-refined-from:
- prospectapis-openapi-generated.yml
- prospectapis-openapi.yml