hyreflow-ai Onboarding API

openapi: 3.2.0
info:
  title: hyreflow engine (local) Onboarding API
  version: 0.1.0
tags:
- name: Onboarding
paths:
  /api/v2/onboarding:
    post:
      summary: Onboarding Set
      description: 'Record an answer from the first-run setup page (web console).

        Every body field is optional but at least one is required: `first_name`, `last_name` (the person''s

        name, captured as two parts), `job_role` (their current role, from a fixed dropdown),

        `referral_source` (where they heard about us, from a fixed dropdown), `crm` / `sequencer` (the tool

        they use: a catalog provider id, "other", or "none", "" clears it), `crm_other` / `sequencer_other`

        (free text typed under "Other", only meaningful alongside `crm`/`sequencer` == "other", "" clears it),

        `website` (the account''s site, owner only), `locale` (a short language code), `team_size` (how many recruiters

        the account has, a range code, "" clears it, owner only), `workspace_name` (renames the

        caller''s active workspace, same rules as `PATCH /api/v2/workspaces/{id}`), `llm` (which client they

        use), `outcome` (how the flow ended). Passing only some fields leaves the others untouched -- e.g. an

        `outcome`-only call never clobbers a previously recorded `first_name`/`last_name`/`job_role`/`llm`/

        `website`/`locale`. `outcome` stamps `onboarding_completed_at` the first time only (first completion

        wins, never moved by a later call). `first_name`/`last_name`/`job_role`/`referral_source`/`crm`/

        `sequencer`/`crm_other`/`sequencer_other`/`llm`/`outcome` belong to the PERSON (`users`);

        `website`/`locale`/`team_size`/`workspace_name` are a property of the ACCOUNT (the caller''s active `workspace`) -- see 0056''s

        migration comment for why. `prompt_copied: true` records the first Copy click on the first prompt

        (`onboarding_prompt_copied_at`, first wins, ENG-744). `start_brain: true` is the setup page reaching step 2

        (its Continue): it starts the owner''s second brain build (ENG-789), after storing a `website` sent in the

        same request, when the workspace has it on and the caller''s onboarding is unfinished, a no-op otherwise.

        Saving a `website` without it starts nothing. Returns the resulting state, the same shape surfaced at

        `/api/v2/me`''s `onboarding` block.'
      operationId: onboarding_set_api_v2_onboarding_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:
      - Onboarding
  /api/v2/onboarding/status:
    get:
      summary: Onboarding Status
      description: 'What the setup page polls (ENG-748, ENG-744): whether the person''s agent has connected over MCP,

        then whether it has started and completed onboarding (reported by the hyreflow_onboarding tool, with

        its latest progress note), plus `brain` {status, host, notes} once a second brain build has started.

        Someone already using Hyreflow without the setup prompt is finished here.'
      operationId: onboarding_status_api_v2_onboarding_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Onboarding
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