openapi: 3.1.0
info:
  title: Prospect Search API — Headless AI SDR (Reply.io)
  version: "3.0"
  description: >
    Search Reply Data (1B+ contacts, 60M+ companies) by ICP filters and turn the
    matches into a prospect list. Summary specification for AI agents covering the
    Live Data and AI SDR intent-signals endpoint groups. STATUS: coming soon — every
    endpoint in these groups is still marked Coming soon in Reply's API reference
    as of 2026-07-05 (targeted early July 2026); paths and schemas below are
    provisional until then. The authoritative,
    complete reference is
    https://docs.reply.io/api-reference/live-data/start-a-live-data-search and the
    full platform OpenAPI at https://docs.reply.io/api-reference/bundled.yaml.
  contact:
    name: Reply.io
    url: https://reply.io
servers:
  - url: https://api.reply.io/v3
security:
  - bearerAuth: []
tags:
  - name: Live Data
  - name: Intent Signals
paths:
  /live-data/searches:
    get:
      tags: [Live Data]
      operationId: listLiveDataSearches
      summary: List Live Data searches
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Required scope not yet published; the
        adjacent contacts endpoints use `contacts:read`.
      responses:
        "200":
          description: Paginated list of Live Data searches.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/LiveDataSearch"
        "429":
          $ref: "#/components/responses/RateLimited"
    post:
      tags: [Live Data]
      operationId: startLiveDataSearch
      summary: Start a Live Data search
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Starts a search over Reply Data from an ICP
        filter set. Required scope not yet published.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [filters]
              properties:
                name:
                  type: string
                filters:
                  $ref: "#/components/schemas/LiveDataFilters"
      responses:
        "201":
          description: Search created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveDataSearch"
        "403":
          $ref: "#/components/responses/Forbidden"
  /live-data/searches/preview:
    post:
      tags: [Live Data]
      operationId: previewLiveDataSearch
      summary: Preview a Live Data search
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Returns match counts for a filter set
        without starting a full search.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [filters]
              properties:
                filters:
                  $ref: "#/components/schemas/LiveDataFilters"
      responses:
        "200":
          description: Estimated match counts for the filter set.
  /live-data/searches/{searchId}:
    get:
      tags: [Live Data]
      operationId: getLiveDataSearch
      summary: Get a Live Data search
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Poll a search by id for its status and
        result counts.
      parameters:
        - $ref: "#/components/parameters/searchId"
      responses:
        "200":
          description: The Live Data search.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveDataSearch"
  /live-data/typeahead/job-titles:
    get:
      tags: [Live Data]
      operationId: jobTitlesTypeahead
      summary: Job titles typeahead
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Resolves free text into canonical job-title
        filter values.
      parameters:
        - $ref: "#/components/parameters/query"
      responses:
        "200":
          description: Matching canonical job-title values.
  /live-data/typeahead/seniorities:
    get:
      tags: [Live Data]
      operationId: senioritiesTypeahead
      summary: Seniorities typeahead
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Resolves free text into canonical seniority
        filter values. Sibling typeaheads exist for departments, industries, and
        locations in the same group.
      parameters:
        - $ref: "#/components/parameters/query"
      responses:
        "200":
          description: Matching canonical seniority values.
  /live-data/typeahead/locations:
    get:
      tags: [Live Data]
      operationId: locationsTypeahead
      summary: Locations typeahead
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Resolves free text into canonical location
        filter values.
      parameters:
        - $ref: "#/components/parameters/query"
      responses:
        "200":
          description: Matching canonical location values.
  /ai-sdr/intent-signals/typeahead/industries:
    get:
      tags: [Intent Signals]
      operationId: intentSignalsIndustriesTypeahead
      summary: Industries typeahead (intent signals)
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Resolves free text into canonical industry
        values for AI SDR intent-signal targeting. Part of the ai-sdr-intent-signals
        group; other endpoints in the ai-sdr family use the `ai-sdr:read` scope.
      parameters:
        - $ref: "#/components/parameters/query"
      responses:
        "200":
          description: Matching canonical industry values.
  /ai-sdr/intent-signals/typeahead/technologies:
    get:
      tags: [Intent Signals]
      operationId: intentSignalsTechnologiesTypeahead
      summary: Technologies typeahead (intent signals)
      description: >
        Coming soon (targeted early July 2026; not yet live as of 2026-07-05). Resolves free text into canonical technology
        values for AI SDR intent-signal targeting.
      parameters:
        - $ref: "#/components/parameters/query"
      responses:
        "200":
          description: Matching canonical technology values.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Reply.io API key sent as a Bearer token. Create one in the Reply.io app under
        Settings → API Key. See https://docs.reply.io/api-reference/authentication.
  parameters:
    searchId:
      name: searchId
      in: path
      required: true
      schema:
        type: string
    query:
      name: query
      in: query
      required: true
      description: Free-text prefix to resolve into canonical filter values.
      schema:
        type: string
  schemas:
    LiveDataSearch:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          description: Search lifecycle state (e.g. pending, running, completed).
        counts:
          type: object
          description: >
            Match counts (contacts, companies). Exact shape unpublished until the
            endpoints ship.
        createdAt:
          type: string
          format: date-time
    LiveDataFilters:
      type: object
      description: >
        ICP filter set. Values should be resolved via the typeahead endpoints.
        Exact shape unpublished until the endpoints ship.
      properties:
        jobTitles:
          type: array
          items: { type: string }
        seniorities:
          type: array
          items: { type: string }
        departments:
          type: array
          items: { type: string }
        industries:
          type: array
          items: { type: string }
        locations:
          type: array
          items: { type: string }
    Problem:
      type: object
      description: RFC 7807 problem document (application/problem+json).
      properties:
        type: { type: string }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
  responses:
    Forbidden:
      description: The API key is missing a required scope.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    RateLimited:
      description: >
        Rate limit exceeded (100 requests/minute, 3,000/hour per user). Honor the
        Retry-After header.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
