hyreflow-ai Enrich API

openapi: 3.2.0
info:
  title: hyreflow engine (local) Enrich API
  version: 0.1.0
tags:
- name: Enrich
paths:
  /enrich/runs/{run_id}:
    get:
      summary: Enrich Run Status
      description: 'An enrich run''s state — free; see `_enrich_run_state`. Decision batches (/shortlist) have their

        own route.'
      operationId: enrich_run_status_enrich_runs__run_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Enrich
  /enrich/run:
    post:
      summary: Enrich Run
      description: 'Run a dataset enrichment. Body: {input: ds_id (or input_rows: [...]), steps|specs|waterfalls,

        range: "START:END", in_place: bool, output_name, dry_run, preview, estimate, session_id}.


        Loads rows from the input dataset, runs the steps over the `range` slice (rest passed through),

        writes a NEW dataset (or in place), and returns a SUMMARY ONLY — never the rows.


        Cost transparency: every run returns a `cost_estimate` in `_meta`. A run is blocked with 402 and a

        `checkout_url` (when payments are configured) only when the balance can''t cover a single row — the

        floor below which it can make no progress; a balance that covers a row but not the whole batch at the

        worst-case rate runs, and carries a `partial_budget` warning. Use `dry_run`/`preview` to inspect

        payloads without charging; use `estimate: true` for an estimate-only call.'
      operationId: enrich_run_enrich_run_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Enrich
  /enrich/{capability}:
    post:
      summary: Enrich
      description: 'Per-row email waterfall (Phase-3 core). For each input row, walk the capability''s provider

        chain (reference/waterfalls.json) in order, stop at the first real hit.


        Body: {"rows": [ {}, ... ]}

        Each row is passed as the flat `payload` to every step (the engine maps it per signature).

        Missing-key / erroring providers are SKIPPED (chain continues). Only the hitting step is billed

        (soft misses charge 0). Sync providers (prospeo, lusha) run inline; async ones (bettercontact/

        fullenrich/wiza) run via the async poll path (`_run_async`, per `enrich_specs.SPECS[*].async`),

        honoring the per-row waterfall deadline.


        A multi-row call is walked STAGE-MAJOR (`HYREFLOW_BULK_ENRICH`, default on): every pending row through

        provider 1, the survivors through provider 2, … — and a provider whose spec declares `bulk` (FullEnrich)

        gets the whole pending set as ONE vendor job per <=100 rows, so the batch pays its ~45-60s job latency

        once, not per row. Each row still keeps its own reservation, settlement and outcome. Sync/unbatched

        stages fan the pending rows out `HYREFLOW_WATERFALL_CONCURRENCY` wide. The whole batch is bounded by

        BULK_BATCH_DEADLINE. With the flag off (or a single row) the row-major walk runs: each row its own

        chain and WATERFALL_DEADLINE, rows concurrent.'
      operationId: enrich_enrich__capability__post
      security:
      - HTTPBearer: []
      parameters:
      - name: capability
        in: path
        required: true
        schema:
          type: string
          title: Capability
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              default: {}
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Enrich
  /enrich/jobs/{provider}/{job_id}:
    get:
      summary: Enrich Job Status
      description: 'Free resume poll for a job the enrich waterfall started and handed off to the background sweeper

        (ENG-523) — no vendor call, no charge, just this workspace''s own `provider_jobs` row.'
      operationId: enrich_job_status_enrich_jobs__provider___job_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Enrich
  /enrich/jobs/{job_id}:
    get:
      summary: Enrich Job Status By Id
      description: 'The same free resume poll, by the job id alone: the job is looked up within this workspace.'
      operationId: enrich_job_status_by_id_enrich_jobs__job_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Enrich
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer