openapi: 3.2.0
info:
  contact:
    name: Clay
    url: https://www.clay.com
  description: Programmatic access to Clay.
  title: Clay Public Search API
  version: '0'
servers:
- description: production
  url: https://api.clay.com/public/v0
security:
- ClayApiKey: []
tags:
- description: Search creation and pagination endpoints.
  name: search
paths:
  /search/filters-mode:
    post:
      description: Starts a new Clay search from a source type and structured filter fields.
      operationId: createFilters
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSearchRequest'
        description: Body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSearchResponse'
          description: '200'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '400'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '401'
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '402'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '403'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '404'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '429'
      summary: Create a search from structured filters
      tags:
      - search
  /search/filters-mode/fields:
    get:
      description: Returns every filter field accepted by POST /search/filters-mode for the given source type, including each field's type, description, allowed values, and usage guidance. Call this before creating a search to build valid filters.
      operationId: fields
      parameters:
      - in: query
        name: source_type
        required: true
        schema:
          enum:
          - people
          - companies
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchFieldsResponse'
          description: '200'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '400'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '401'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '403'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '429'
      summary: List the filter fields available for a search source type
      tags:
      - search
  /search/filters-mode/{search_id}/run:
    post:
      description: Returns the next page of records for an existing filter-mode search.
      operationId: run
      parameters:
      - in: path
        name: search_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NextSearchResultsBody'
        description: Body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NextSearchResultsResponse'
          description: '200'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '400'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '401'
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '402'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '403'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '404'
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '413'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '429'
      summary: Run the search iterator and return the next page of results
      tags:
      - search
  /search/query-mode:
    post:
      description: Starts a new Clay search from a Clay advanced search query. The source type is detected from the query and returned in the response. Count-mode and jobs queries are not supported.
      operationId: createQueryMode
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                query:
                  minLength: 1
                  type: string
              required:
              - query
              type: object
        description: Body
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  search_id:
                    type: string
                  source_type:
                    enum:
                    - people
                    - companies
                    type: string
                required:
                - search_id
                - source_type
                type: object
          description: '200'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '400'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '401'
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '402'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '403'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '404'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '429'
      summary: Create a search from a Clay search query (beta)
      tags:
      - search
  /search/query-mode/reference:
    get:
      description: Returns the Clay search query reference document (markdown), covering the queryable fields and the query grammar. Use it to author a Clay advanced search query before creating a query-mode search.
      operationId: queryModeReference
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  reference:
                    type: string
                required:
                - reference
                type: object
          description: '200'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '400'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '401'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '403'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '429'
      summary: Get the Clay search query reference (beta)
      tags:
      - search
  /search/query-mode/{search_id}/run:
    post:
      description: Returns the next page of records for an existing query-mode search.
      operationId: runQueryMode
      parameters:
      - in: path
        name: search_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NextSearchResultsBody'
        description: Body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NextQueryModeResultsResponse'
          description: '200'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '400'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '401'
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '402'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '403'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '404'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '429'
      summary: Run the query-mode iterator and return the next page of results (beta)
      tags:
      - search
components:
  schemas:
    SearchFilterField:
      additionalProperties: false
      properties:
        allowed_values:
          items:
            type: string
          type: array
        description:
          type: string
        name:
          type: string
        type:
          type: string
      required:
      - name
      - type
      type: object
    SearchFieldsResponse:
      additionalProperties: false
      properties:
        fields:
          items:
            $ref: '#/components/schemas/SearchFilterField'
          type: array
        guidance:
          $ref: '#/components/schemas/SearchFieldsGuidance'
        source_type:
          enum:
          - people
          - companies
          type: string
      required:
      - source_type
      - fields
      - guidance
      type: object
    PublicApiMatchedExperience:
      additionalProperties: false
      properties:
        company:
          anyOf:
          - type: string
          - type: 'null'
        end_date:
          anyOf:
          - type: string
          - type: 'null'
        location:
          anyOf:
          - type: string
          - type: 'null'
        start_date:
          anyOf:
          - type: string
          - type: 'null'
        title:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - company
      - title
      - location
      - start_date
      - end_date
      type: object
    NextSearchResultsBody:
      additionalProperties: false
      properties:
        limit:
          default: 20
          maximum: 500
          minimum: 1
          type: integer
      type: object
    SearchFieldsGuidance:
      additionalProperties: false
      properties:
        behavior:
          items:
            type: string
          type: array
        create_examples:
          items:
            $ref: '#/components/schemas/SearchCreateExample'
          type: array
        field_guidance:
          items:
            $ref: '#/components/schemas/SearchGuidanceItem'
          type: array
      required:
      - behavior
      - field_guidance
      type: object
    NextQueryModePeopleResultsResponse:
      additionalProperties: false
      properties:
        data:
          items:
            $ref: '#/components/schemas/PublicApiPersonSearchResult'
          type: array
        exhaustion_reason:
          enum:
          - query_limit
          - no_more_results
          type: string
        has_more:
          type: boolean
        period_quota:
          additionalProperties: false
          properties:
            limit:
              type: number
            remaining:
              type: number
            resets_at:
              type: string
            used:
              type: number
          required:
          - limit
          - used
          - remaining
          - resets_at
          type: object
        source_type:
          const: people
          type: string
      required:
      - data
      - has_more
      - source_type
      type: object
    NextQueryModeResultsResponse:
      oneOf:
      - $ref: '#/components/schemas/NextQueryModePeopleResultsResponse'
      - $ref: '#/components/schemas/NextQueryModeCompanyResultsResponse'
    NextQueryModeCompanyResultsResponse:
      additionalProperties: false
      properties:
        data:
          items:
            $ref: '#/components/schemas/PublicApiCompanySearchResult'
          type: array
        exhaustion_reason:
          enum:
          - query_limit
          - no_more_results
          type: string
        has_more:
          type: boolean
        period_quota:
          additionalProperties: false
          properties:
            limit:
              type: number
            remaining:
              type: number
            resets_at:
              type: string
            used:
              type: number
          required:
          - limit
          - used
          - remaining
          - resets_at
          type: object
        source_type:
          const: companies
          type: string
      required:
      - data
      - has_more
      - source_type
      type: object
    CreateSearchResponse:
      additionalProperties: false
      properties:
        search_id:
          type: string
      required:
      - search_id
      type: object
    ErrorResponse:
      additionalProperties: false
      properties:
        message:
          type: string
      required:
      - message
      type: object
    CreateSearchRequest:
      additionalProperties: false
      properties:
        filters:
          additionalProperties: {}
          type: object
        source_type:
          enum:
          - people
          - companies
          type: string
      required:
      - source_type
      - filters
      type: object
    PublicApiPersonSearchResult:
      additionalProperties: false
      properties:
        clay_profile_id:
          type: number
        first_name:
          anyOf:
          - type: string
          - type: 'null'
        last_name:
          anyOf:
          - type: string
          - type: 'null'
        location:
          additionalProperties: false
          properties:
            city:
              anyOf:
              - type: string
              - type: 'null'
            name:
              anyOf:
              - type: string
              - type: 'null'
            state_or_province:
              anyOf:
              - type: string
              - type: 'null'
          required:
          - name
          - city
          - state_or_province
          type: object
        matched_experiences:
          items:
            $ref: '#/components/schemas/PublicApiMatchedExperience'
          type: array
        name:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - clay_profile_id
      - name
      - first_name
      - last_name
      - location
      - matched_experiences
      type: object
    SearchCreateExample:
      additionalProperties: false
      properties:
        intent:
          type: string
        request:
          additionalProperties: false
          properties:
            filters:
              additionalProperties: {}
              type: object
            source_type:
              enum:
              - people
              - companies
              type: string
          required:
          - source_type
          - filters
          type: object
      required:
      - intent
      - request
      type: object
    SearchGuidanceItem:
      additionalProperties: false
      properties:
        fields:
          items:
            type: string
          type: array
        id:
          type: string
        text:
          type: string
      required:
      - id
      - text
      type: object
    NextSearchResultsResponse:
      additionalProperties: false
      properties:
        data:
          items:
            additionalProperties: {}
            type: object
          type: array
        has_more:
          type: boolean
        period_quota:
          additionalProperties: false
          properties:
            limit:
              type: number
            remaining:
              type: number
            resets_at:
              type: string
            used:
              type: number
          required:
          - limit
          - used
          - remaining
          - resets_at
          type: object
      required:
      - data
      - has_more
      type: object
    PublicApiCompanySearchResult:
      additionalProperties: false
      properties:
        annual_revenue:
          anyOf:
          - type: string
          - type: 'null'
        clay_company_id:
          type: number
        country:
          anyOf:
          - type: string
          - type: 'null'
        description:
          anyOf:
          - type: string
          - type: 'null'
        domain:
          anyOf:
          - type: string
          - type: 'null'
        industry:
          anyOf:
          - type: string
          - type: 'null'
        linkedin_url:
          anyOf:
          - type: string
          - type: 'null'
        location:
          anyOf:
          - type: string
          - type: 'null'
        name:
          anyOf:
          - type: string
          - type: 'null'
        size:
          anyOf:
          - type: string
          - type: 'null'
        total_funding_amount_range_usd:
          anyOf:
          - type: number
          - type: 'null'
        type:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - clay_company_id
      - name
      - size
      - type
      - domain
      - country
      - industry
      - location
      - description
      - linkedin_url
      - annual_revenue
      - total_funding_amount_range_usd
      type: object
  securitySchemes:
    ClayApiKey:
      description: Personal API key tied to your Clay user. Create one under Settings → Account in the Clay app.
      in: header
      name: clay-api-key
      type: apiKey