openapi: 3.2.0
info:
  contact:
    email: support@aiapplyd.com
    name: AI Applyd
    url: https://aiapplyd.com
  description: 'The AI Applyd API runs the whole job hunt for you: it matches you to roles that fit your profile, rewrites your resume for each posting, writes the cover letter the form asks for, and auto-applies across the major applicant tracking systems.'
  license:
    name: Proprietary
    url: https://aiapplyd.com/legal/terms
  title: AI Applyd Onboarding API
  version: 115c47ce
servers:
- description: Current environment
  url: https://api.aiapplyd.com/api/v1
security:
- BearerAuth: []
tags:
- name: Onboarding
paths:
  /onboarding/parse-resume:
    post:
      tags:
      - Onboarding
      summary: Parse Resume for Onboarding
      description: Upload a resume file (PDF, DOCX, or TXT), save it as a user document, and use AI to extract structured data for profile creation.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                documentId:
                  type: string
                temporary:
                  type: string
                  enum:
                  - 'true'
                  - 'false'
      responses:
        '200':
          description: Parsed resume data for frontend review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseResumeResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postOnboardingParseResume
  /onboarding/auto-setup:
    post:
      tags:
      - Onboarding
      summary: Auto-Setup from Parsed Resume
      description: Update user account, create job match preferences, and trigger initial job scrape using parsed resume data.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoSetupRequest'
      responses:
        '200':
          description: Auto-setup completed with preferences and scrape status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoSetupResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postOnboardingAutoSetup
  /onboarding/discover-status:
    get:
      tags:
      - Onboarding
      summary: Poll Background Match Discovery Status
      description: Returns the current status of the background match-discovery job triggered by /onboarding/auto-setup. Frontend polls this after auto-setup to show retry affordance when discovery fails.
      responses:
        '200':
          description: Current discovery status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverStatusResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: getOnboardingDiscoverStatus
  /onboarding/profile:
    post:
      tags:
      - Onboarding
      summary: Upsert Onboarding Profile
      description: Soft-patch the user's onboarding wizard answers. Every field is optional; only the fields posted are written. Idempotent per screen.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingProfileUpsert'
      responses:
        '200':
          description: Persisted onboarding profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingProfileResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postOnboardingProfile
    get:
      tags:
      - Onboarding
      summary: Get Onboarding Profile
      description: Read the user's onboarding wizard answers (or an empty profile when the wizard has not been started).
      responses:
        '200':
          description: Onboarding profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingProfileResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: getOnboardingProfile
  /onboarding/resume-prefill:
    get:
      tags:
      - Onboarding
      summary: Get Resume Prefill
      description: Report which application-profile and job-preference fields still hold the value verified from the user's base resume, plus the canonical resume cities to offer as location chips. Returns field keys and city names only, never contact values.
      responses:
        '200':
          description: Resume prefill status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumePrefillResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: getOnboardingResumePrefill
  /onboarding/complete:
    post:
      tags:
      - Onboarding
      summary: Complete Onboarding
      description: 'Finalize the onboarding wizard: stamp the completion milestone and soft-fill the user''s job-match preferences + AI persona from the wizard answers (only filling targets that are still empty). Idempotent - re-calling is a no-op for the soft-fill. An optional `autoApplyMode` arms the persona''s auto-apply status when the user opted into autopilot (only when still at the seeded default).'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteOnboardingRequest'
      responses:
        '200':
          description: Onboarding finalized with soft-fill summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingCompleteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postOnboardingComplete
  /onboarding/escrow:
    post:
      tags:
      - Onboarding
      summary: Mint Onboarding Escrow
      description: 'Store anonymous /start answers server-side at the account gate and return an opaque reference. The reference is threaded into the auth callback URL so a magic link opened in a DIFFERENT browser can still recover the answers. Anonymous by necessity: the account does not exist yet.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MintOnboardingEscrowBody'
      responses:
        '200':
          description: The escrow reference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MintOnboardingEscrowResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postOnboardingEscrow
  /onboarding/escrow/redeem:
    post:
      tags:
      - Onboarding
      summary: Redeem Onboarding Escrow
      description: Exchange an escrow reference for the answers it holds, then drop the blob. Requires a session. Returns answers:null for an absent, expired or already-redeemed reference - which is NOT the same as "the user answered nothing".
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemOnboardingEscrowBody'
      responses:
        '200':
          description: The escrowed answers, or nulls when the reference resolves to nothing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemOnboardingEscrowResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postOnboardingEscrowRedeem
components:
  schemas:
    ResumePrefillResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ResumePrefillData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    RedeemOnboardingEscrowBody:
      type: object
      properties:
        ref:
          type: string
          minLength: 8
          maxLength: 120
          description: The reference handed back by the mint and carried in the auth callback URL.
          example: 9f1c8b3e-4d2a-4c77-9a5e-0b2f6d1e8a44
      required:
      - ref
      additionalProperties: false
    RedeemOnboardingEscrowPayload:
      type: object
      properties:
        answers:
          allOf:
          - $ref: '#/components/schemas/OnboardingProfileUpsert'
          - description: The escrowed answers, or null when this reference resolves to nothing.
        screen:
          type:
          - integer
          - 'null'
          description: Furthest pre-auth screen reached, or null alongside a null answers.
          example: 18
      required:
      - answers
      - screen
    WorkExperienceItem:
      type: object
      properties:
        company:
          type: string
          description: Company name
          example: Acme Corp
        current:
          type: boolean
          description: Whether this is the current position
          example: false
        description:
          type:
          - string
          - 'null'
          description: Role description or achievements
          example: Led a team of 5 engineers building microservices
        endDate:
          type:
          - string
          - 'null'
          description: End date (free-form from resume)
          example: Dec 2023
        location:
          type:
          - string
          - 'null'
          description: City of this role exactly as printed on the resume
          example: Berlin
        startDate:
          type:
          - string
          - 'null'
          description: Start date (free-form from resume)
          example: Jan 2020
        title:
          type: string
          description: Job title
          example: Senior Software Engineer
      required:
      - company
      - current
      - description
      - endDate
      - startDate
      - title
      additionalProperties: false
    OnboardingSoftFilled:
      type: object
      properties:
        targetRoles:
          type: boolean
        locations:
          type: boolean
        salaryMin:
          type: boolean
        salaryMax:
          type: boolean
        experienceLevels:
          type: boolean
        remoteGlobal:
          type: boolean
        personaCreated:
          type: boolean
        minMatchScore:
          type: boolean
        dailyLimit:
          type: boolean
        scoringWeights:
          type: boolean
      required:
      - targetRoles
      - locations
      - salaryMin
      - salaryMax
      - experienceLevels
      - remoteGlobal
      - personaCreated
      - minMatchScore
      - dailyLimit
      - scoringWeights
    EducationItem:
      type: object
      properties:
        degree:
          type: string
          description: Degree or certification name
          example: B.S. Computer Science
        institution:
          type: string
          description: School or institution name
          example: MIT
        year:
          type:
          - string
          - 'null'
          description: Graduation year or date range
          example: '2018'
      required:
      - degree
      - institution
      - year
      additionalProperties: false
    RedeemOnboardingEscrowResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RedeemOnboardingEscrowPayload'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    OnboardingProfileData:
      type: object
      properties:
        activelyLooking:
          type:
          - boolean
          - 'null'
        triedOtherApps:
          type:
          - boolean
          - 'null'
        importance:
          type: array
          items:
            type: string
            enum:
            - meaningful_work
            - experienced_leaders
            - top_investors
            - wear_many_hats
            - smart_people
            - challenging_work
            - growing_fast
            - cool_startup
            - stable_company
            - innovative_tech
            - flexible_hours
            - great_benefits
            description: A factor the user cares about most in their next role
            example: meaningful_work
        categories:
          type: array
          items:
            type: string
            enum:
            - software_engineering
            - healthcare
            - consulting
            - data
            - design
            - finance
            - legal
            - hr
            - marketing
            - operations_strategy
            - product
            - sales
            - customer_success
            - security
            - misc_engineering
            description: Coarse career-field category for onboarding role discovery
            example: software_engineering
        roles:
          type: array
          items:
            type: string
        customRoles:
          type: array
          items:
            type: string
        experienceBand:
          type:
          - string
          - 'null'
          enum:
          - internship
          - entry
          - junior
          - mid
          - senior
          - expert
          - null
          description: Onboarding-facing experience band picked by the user
          example: mid
        experienceBands:
          type: array
          items:
            type: string
            enum:
            - internship
            - entry
            - junior
            - mid
            - senior
            - expert
            description: Onboarding-facing experience band picked by the user
            example: mid
        locations:
          type: array
          items:
            type: string
        remoteGlobal:
          type: boolean
        country:
          type:
          - string
          - 'null'
        salaryMin:
          type:
          - number
          - 'null'
        salaryMax:
          type:
          - number
          - 'null'
        salaryCurrency:
          type:
          - string
          - 'null'
        goal:
          type:
          - string
          - 'null'
          enum:
          - land_asap
          - make_more_money
          - land_dream_job
          - null
          description: The user's primary job-search goal
          example: land_asap
        interviewsPerWeekTarget:
          type:
          - integer
          - 'null'
        jobTimeline:
          type:
          - string
          - 'null'
          enum:
          - one_month
          - three_months
          - six_months
          - twelve_months_plus
          - null
          description: How soon the user wants to land a new role
          example: three_months
        blockers:
          type: array
          items:
            type: string
            enum:
            - not_applying_enough
            - cant_land_interviews
            - not_ready_yet
            - lack_great_offers
            description: A blocker the user feels is hindering their job search
            example: not_applying_enough
        motivations:
          type: array
          items:
            type: string
            enum:
            - more_money
            - support_family
            - exciting_job
            - get_time_back
            description: A motivation driving the user's job search
            example: more_money
        attributionSource:
          type:
          - string
          - 'null'
          enum:
          - social
          - influencer
          - friend
          - search
          - ad
          - other
          - null
          description: How the user discovered AI Applyd
          example: search
        referralCodeUsed:
          type:
          - string
          - 'null'
        resumeDeferred:
          type: boolean
        fullLegalName:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        completedSteps:
          type: array
          items:
            type: string
            enum:
            - upload-resume
            - set-preferences
            - connect-platform
            - discover-jobs
            description: Step identifier in the dashboard onboarding / readiness checklist
            example: upload-resume
        finalizedAt:
          type:
          - string
          - 'null'
      required:
      - activelyLooking
      - triedOtherApps
      - importance
      - categories
      - roles
      - customRoles
      - experienceBand
      - experienceBands
      - locations
      - remoteGlobal
      - country
      - salaryMin
      - salaryMax
      - salaryCurrency
      - goal
      - interviewsPerWeekTarget
      - jobTimeline
      - blockers
      - motivations
      - attributionSource
      - referralCodeUsed
      - resumeDeferred
      - fullLegalName
      - phone
      - completedSteps
      - finalizedAt
    MintOnboardingEscrowPayload:
      type: object
      properties:
        ref:
          type: string
          description: Opaque SERVER-minted escrow reference. Thread this into the auth callback URL. A client-supplied reference is never honoured.
          example: 9f1c8b3e-4d2a-4c77-9a5e-0b2f6d1e8a44
      required:
      - ref
    OnboardingCompleteResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/OnboardingCompleteData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    AutoSetupPreferencesData:
      type: object
      properties:
        createdAt:
          type:
          - string
          - 'null'
        excludeCompanies:
          type:
          - array
          - 'null'
          items:
            type: string
        experienceLevel:
          type:
          - string
          - 'null'
        id:
          type: integer
        industries:
          type:
          - array
          - 'null'
          items:
            type: string
        isActive:
          type: boolean
        locations:
          type:
          - array
          - 'null'
          items:
            type: string
        salaryMin:
          type:
          - number
          - 'null'
        targetRoles:
          type:
          - array
          - 'null'
          items:
            type: string
        updatedAt:
          type:
          - string
          - 'null'
      required:
      - createdAt
      - excludeCompanies
      - experienceLevel
      - id
      - industries
      - isActive
      - locations
      - salaryMin
      - targetRoles
      - updatedAt
      additionalProperties: false
    OnboardingProfileUpsert:
      type: object
      properties:
        activelyLooking:
          type: boolean
        triedOtherApps:
          type: boolean
        importance:
          type: array
          items:
            type: string
            enum:
            - meaningful_work
            - experienced_leaders
            - top_investors
            - wear_many_hats
            - smart_people
            - challenging_work
            - growing_fast
            - cool_startup
            - stable_company
            - innovative_tech
            - flexible_hours
            - great_benefits
            description: A factor the user cares about most in their next role
            example: meaningful_work
          maxItems: 3
        categories:
          type: array
          items:
            type: string
            enum:
            - software_engineering
            - healthcare
            - consulting
            - data
            - design
            - finance
            - legal
            - hr
            - marketing
            - operations_strategy
            - product
            - sales
            - customer_success
            - security
            - misc_engineering
            description: Coarse career-field category for onboarding role discovery
            example: software_engineering
          maxItems: 3
        roles:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 120
          maxItems: 5
        customRoles:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 120
          maxItems: 5
        experienceBand:
          type: string
          enum:
          - internship
          - entry
          - junior
          - mid
          - senior
          - expert
          description: Onboarding-facing experience band picked by the user
          example: mid
        experienceBands:
          type: array
          items:
            type: string
            enum:
            - internship
            - entry
            - junior
            - mid
            - senior
            - expert
            description: Onboarding-facing experience band picked by the user
            example: mid
          maxItems: 6
        locations:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 160
          maxItems: 5
        remoteGlobal:
          type: boolean
        country:
          type: string
          minLength: 1
          maxLength: 80
        salaryMin:
          type: number
          minimum: 0
        salaryMax:
          type: number
          minimum: 0
        salaryCurrency:
          type: string
          enum:
          - usd
          - eur
          - gbp
          - cad
          - aud
          - inr
          description: Currency for salary values
          example: usd
        goal:
          type: string
          enum:
          - land_asap
          - make_more_money
          - land_dream_job
          description: The user's primary job-search goal
          example: land_asap
        interviewsPerWeekTarget:
          type: integer
          minimum: 0
          maximum: 50
        jobTimeline:
          type: string
          enum:
          - one_month
          - three_months
          - six_months
          - twelve_months_plus
          description: How soon the user wants to land a new role
          example: three_months
        blockers:
          type: array
          items:
            type: string
            enum:
            - not_applying_enough
            - cant_land_interviews
            - not_ready_yet
            - lack_great_offers
            description: A blocker the user feels is hindering their job search
            example: not_applying_enough
          maxItems: 3
        motivations:
          type: array
          items:
            type: string
            enum:
            - more_money
            - support_family
            - exciting_job
            - get_time_back
            description: A motivation driving the user's job search
            example: more_money
          maxItems: 3
        attributionSource:
          type: string
          enum:
          - social
          - influencer
          - friend
          - search
          - ad
          - other
          description: How the user discovered AI Applyd
          example: search
        referralCodeUsed:
          type: string
          minLength: 1
          maxLength: 64
        resumeDeferred:
          type: boolean
        fullLegalName:
          type: string
          minLength: 1
          maxLength: 120
        phone:
          type: string
          minLength: 1
          maxLength: 40
        completedSteps:
          type: array
          items:
            type: string
            enum:
            - upload-resume
            - set-preferences
            - connect-platform
            - discover-jobs
            description: Step identifier in the dashboard onboarding / readiness checklist
            example: upload-resume
      additionalProperties: false
    AutoSetupData:
      type: object
      properties:
        discoverStatusKey:
          type:
          - string
          - 'null'
          description: KV key the frontend can poll via GET /onboarding/discover-status to track background match discovery. Null when no discovery was triggered.
          example: onboarding:discover:user_abc123
        preferences:
          $ref: '#/components/schemas/AutoSetupPreferencesData'
        scrapeStatus:
          type: string
          enum:
          - triggered
          - skipped
          - failed
          description: Whether initial job scrape was triggered
          example: triggered
        userUpdated:
          type: boolean
          description: Whether the user account was updated
          example: true
      required:
      - discoverStatusKey
      - preferences
      - scrapeStatus
      - userUpdated
      additionalProperties: false
    AutoSetupResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AutoSetupData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ResumePrefill:
      type: object
      properties:
        addressLine1:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        currentEmployer:
          type:
          - string
          - 'null'
        githubUrl:
          type:
          - string
          - 'null'
        highestEducation:
          type:
          - string
          - 'null'
          enum:
          - high_school
          - associate
          - bachelor
          - master
          - doctorate
          - any
          - null
          description: Education level requirement
          example: any
        homeLocation:
          type:
          - string
          - 'null'
        linkedinUrl:
          type:
          - string
          - 'null'
        ownTitles:
          type: array
          items:
            type: string
        phone:
          type:
          - string
          - 'null'
        portfolioUrl:
          type:
          - string
          - 'null'
        seeded:
          type: object
          properties:
            jobPreferences:
              type: object
              properties:
                locations:
                  type: boolean
                  enum:
                  - true
                experienceLevels:
                  type: boolean
                  enum:
                  - true
                skills:
                  type: boolean
                  enum:
                  - true
                targetRoles:
                  type: boolean
                  enum:
                  - true
            profile:
              type: object
              properties:
                addressLine1:
                  type: boolean
                  enum:
                  - true
                city:
                  type: boolean
                  enum:
                  - true
                state:
                  type: boolean
                  enum:
                  - true
                country:
                  type: boolean
                  enum:
                  - true
                zipCode:
                  type: boolean
                  enum:
                  - true
                phone:
                  type: boolean
                  enum:
                  - true
                linkedinUrl:
                  type: boolean
                  enum:
                  - true
                githubUrl:
                  type: boolean
                  enum:
                  - true
                portfolioUrl:
                  type: boolean
                  enum:
                  - true
                currentEmployer:
                  type: boolean
                  enum:
                  - true
                highestEducation:
                  type: boolean
                  enum:
                  - true
                yearsOfExperience:
                  type: boolean
                  enum:
                  - true
          additionalProperties: false
        state:
          type:
          - string
          - 'null'
        workHistoryLocations:
          type: array
          items:
            type: string
        yearsOfExperience:
          type:
          - integer
          - 'null'
        zipCode:
          type:
          - string
          - 'null'
      required:
      - addressLine1
      - city
      - country
      - currentEmployer
      - githubUrl
      - highestEducation
      - homeLocation
      - linkedinUrl
      - ownTitles
      - phone
      - portfolioUrl
      - state
      - workHistoryLocations
      - yearsOfExperience
      - zipCode
      additionalProperties: false
    AutoSetupRequest:
      type: object
      properties:
        city:
          type:
          - string
          - 'null'
          description: City from parsed resume
          example: San Francisco
        country:
          type:
          - string
          - 'null'
          description: Country from parsed resume
          example: United States
        documentId:
          type: integer
          description: ID of the parsed resume document (optional for manual entry)
          example: 42
          exclusiveMinimum: 0
        email:
          type:
          - string
          - 'null'
          description: Email from parsed resume
          example: john.doe@example.com
        experienceLevel:
          type: string
          enum:
          - entry
          - mid
          - senior
          - lead
          - executive
          description: Inferred experience level (DEPRECATED scalar  -  prefer `experienceLevels`). When `experienceLevels` is present it wins; the scalar is mirrored from its first element.
          example: senior
        experienceLevels:
          type: array
          items:
            type: string
            enum:
            - entry
            - mid
            - senior
            - lead
            - executive
            description: Professional experience level
            example: mid
          description: Inferred experience levels (multi-select). The résumé parser pre-selects ONE as primary; the user can add more. Empty/omitted = no seniority constraint.
          example:
          - mid
          - senior
        remoteGlobal:
          type: boolean
          description: Accept worldwide "Remote  -  Anywhere (Global)" jobs from any region. Set via the location picker's Remote-Anywhere option. Independent of workStyles "remote" (region-restricted).
          example: false
        fullName:
          type:
          - string
          - 'null'
          description: Full name from parsed resume
          example: John Doe
        phone:
          type:
          - string
          - 'null'
          description: Phone number from parsed resume
          example: +1-555-123-4567
        benefits:
          type: array
          items:
            type: string
          description: Must-have job benefits
          example:
          - health_insurance
          - remote_work
        companySize:
          type: array
          items:
            type: string
          description: Preferred company sizes
          example:
          - startup
          - medium
        educationLevel:
          type: string
          description: Minimum education level filter
          example: bachelor
        industries:
          type: array
          items:
            type: string
          description: Industries inferred from work experience
          example:
          - Technology
          - Finance
          - Healthcare
        jobTypes:
          type: array
          items:
            type: string
          description: Preferred job types
          example:
          - full_time
          - contract
        salaryCurrency:
          type: string
          enum:
          - usd
          - eur
          - gbp
          - cad
          - aud
          - inr
          description: Currency for the salary band (converted to USD for matching). Defaults to usd.
          example: eur
        salaryMax:
          type: integer
          description: Maximum desired salary (in salaryCurrency)
          example: 200000
          exclusiveMinimum: 0
        salaryMin:
          type: integer
          description: Minimum desired salary (in salaryCurrency)
          example: 80000
          exclusiveMinimum: 0
        visaSponsorship:
          type: string
          description: Visa sponsorship preference
          example: any
        skills:
          type: array
          items:
            type: string
          description: Skills extracted from resume
          example:
          - TypeScript
          - React
          - Node.js
        state:
          type:
          - string
          - 'null'
          description: State/province from resume
          example: California
        suggestedJobTitles:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
          description: 'Suggested job titles based on resume (max 5). Empty arrays and placeholder values ("anywhere", "any", ...) are rejected: a specific title is required to scope the job search.'
          example:
          - Senior Software Engineer
          - Full Stack Developer
        suggestedLocations:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
          description: 'Suggested job search locations as "City, Country" or "Country" (max 5). Middle admin segments (state/province) are stripped on ingest. Empty arrays and placeholder values ("anywhere", "any", ...) are rejected: a specific location is required to scope the job search.'
          example:
          - San Francisco, United States
          - Berlin, Germany
        workStyles:
          type: array
          items:
            type: string
            enum:
            - onsite
            - hybrid
            - remote
            description: User's preferred work style, physical mode only, no geo scoping
            example: remote
          minItems: 1
          description: Preferred work styles (onsite/hybrid/remote), multi-select, at least 1 required
          example:
          - remote
          - hybrid
      required:
      - city
      - country
      - email
      - fullName
      - phone
      - skills
      - state
      - suggestedJobTitles
      - suggestedLocations
      - workStyles
      additionalProperties: false
    ResumeFieldEvidence:
      type: object
      properties:
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
          description: 'How the value was read: high/medium when printed in the resume, low when inferred'
          example: high
        field:
          type: string
          enum:
          - addressLine1
          - city
          - state
          - country
          - zipCode
          - phone
          - email
          - linkedinUrl
          - githubUrl
          - portfolioUrl
          - currentEmployer
          - educationLevel
          description: A parsed resume fact the model must back with a verbatim quote from the resume
          example: city
        quote:
          type:
          - string
          - 'null'
          description: The exact contiguous resume text that contains the value (<=160 chars), or null
          example: Berlin, Germany | +49 176 1234 5678
      required:
      - confidence
      - field
      - quote
      additionalProperties: false
    OnboardingCompleteData:
      type: object
      properties:
        onboardingCompleted:
          type: boolean
          enum:
          - true
        softFilled:
          $ref: '#/components/schemas/OnboardingSoftFilled'
        initialMatchCount:
          type: integer
          minimum: 0
      required:
      - onboardingCompleted
      - softFilled
      - initialMatchCount
    MintOnboardingEscrowResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MintOnboardingEscrowPayload'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    DiscoverStatusResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DiscoverStatusData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ParsedResumeData:
      type: object
      properties:
        addressLine1:
          type:
          - string
          - 'null'
          description: Street + number exactly as printed, or null
          example: Hauptstrasse 12
        city:
          type:
          - string
          - 'null'
          description: City from resume
          example: San Francisco
        companySize:
          type: array
          items:
            type: string
          description: 'AI-inferred company size preferences: startup, small, medium, large, enterprise'
          example:
          - startup
          - medium
        country:
          type:
          - string
          - 'null'
          description: Country from resume
          example: United States
        currentJobTitle:
          type:
          - string
          - 'null'
          description: Current or most recent job title
          example: Senior Software Engineer
        documentId:
          type: integer
          description: ID of the saved user document
          example: 42
        education:
          type: array
          items:
            $ref: '#/components/schemas/EducationItem'
          description: Education history extracted from resume
        educationLevel:
          type:
          - string
          - 'null'
          description: 'AI-inferred education level: high_school, associate, bachelor, master, doctorate'
          example: bachelor
        email:
          type:
          - string
          - 'null'
          description: Email address from resume
          example: john.doe@example.com
        experienceLevel:
          type:
          - string
          - 'null'
          description: 'AI-inferred experience level: entry, mid, senior, lead, executive'
          example: senior
        fieldEvidence:
          type: array
          items:
            $ref: '#/components/schemas/ResumeFieldEvidence'
          description: Verbatim quotes the model offers for contact and level facts
        firstName:
          type:
          - string
          - 'null'
          description: First name parsed from full name
          example: John
        fullName:
          type:
          - string
          - 'null'
          description: Full name from resume
          example: John Doe
        githubUrl:
          type:
          - string
          - 'null'
          description: GitHub profile URL exactly as printed, or null
          example: https://github.com/johndoe
        industries:
          type: array
          items:
            type: string
          description: AI-inferred industries from work history
          example:
          - Software & SaaS
          - AI & Machine Learning
        jobTypes:
          type: array
          items:
            type: string
          description: 'AI-inferred job types: full_time, part_time, contract, freelance, internship, temporary'
          example:
          - full_time
        lastName:
          type:
          - string
          - 'null'
          description: Last name parsed from full name
          example: Doe
        linkedinUrl:
          type:
          - string
          - 'null'
          description: LinkedIn profile URL exactly as printed, or null
          example: https://www.linkedin.com/in/johndoe
        phone:
          type:
          - string
          - 'null'
          description: Phone number from resume
          example: +1-555-123-4567
        portfolioUrl:
          type:
          - string
          - 'null'
          description: Personal website / portfolio URL exactly as printed, or null
          example: https://johndoe.dev
        prefill:
          $ref: '#/components/schemas/ResumePrefill'
        professionalSummary:
          type:
          - string
          - 'null'
          description: Professional summary or objective
          example: Experienced full-stack engineer with 8 years building scalable web applications.
        skills:
          type: array
          items:
            type: string
          description: Skills extracted from resume
          example:
          - TypeScript
          - React
          - Node.js
          - PostgreSQL
        state:
          type:
          - string
          - 'null'
          description: State/province from resume
          example: California
        suggestedJobTitles:
          type: array
          items:
            type: string
          description: Suggested job titles based on experience
          example:
          - Senior Software Engineer
          - Full Stack Developer
          - Tech Lead
        suggestedLocations:
          type: array
          items:
            type: string
          description: Suggested job search locations based on resume
          example:
          - San Francisco, CA
          - Remote
        workExperience:
          type: array
          items:
            $ref: '#/components/schemas/WorkExperienceItem'
          description: Work experience history extracted from resume
        yearsOfExperience:
          type:
          - integer
          - 'null'
          description: Estimated total years of experience (whole number)
          example: 8
        zipCode:
          type:
          - string
          - 'null'
          description: ZIP/postal code from resume
          example: '94105'
      required:
      - city
      - companySize
      - country
      - currentJobTitle
      - documentId
      - education
      - educationLevel
      - email
      - experienceLevel
      - firstName
      - fullName
      - industries
      - jobTypes
      - lastName
      - phone
      - professionalSummary
      - skills
      - state
      - suggestedJobTitles
      - suggestedLocations
      - workExperience
      - yearsOfExperience
      - zipCode
      additionalProperties: false
    OnboardingProfileResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/OnboardingProfileData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ResumePrefillData:
      type: object
      properties:
        documentId:
          type:
          - integer
          - 'null'
          description: The base resume the prefill came from, or null when there is none
          example: 42
        jobPreferenceFields:
          type: array
          items:
            type: string
            enum:
            - locations
            - experienceLevels
            - skills
            - targetRoles
            description: A job-preference field a verified resume prefill may fill when the user left it blank
            example: locations
          description: Job-preference fields whose saved value is still the one seeded from the resume
          example:
          - locations
          - skills
        profileFields:
          type: array
          items:
            type: string
            enum:
            - addressLine1
            - city
            - state
            - country
            - zipCode
            - phone
            - linkedinUrl
            - githubUrl
            - portfolioUrl
            - currentEmployer
            - highestEducation
            - yearsOfExperience
            description: An application-profile field a verified resume prefill may fill
            example: city
          description: Application-profile fields whose saved value still equals the verified resume value
          example:
          - city
          - country
          - linkedinUrl
        resumeLocations:
          type: array
          items:
            type: string
          description: Canonical cities from the resume (home first, then past roles), max 5, offered as opt-in location chips
          example:
          - Berlin, Germany
          - Munich, Germany
        seedableSkillsCount:
          type: integer
          minimum: 0
          description: How many resume skills the seed would write (deduped, spoken languages removed, capped)
          example: 12
        status:
          type: string
          enum:
          - none
          - pending
          - ready
          - failed
          description: 'Lifecycle of the base resume prefill: none (no resume), pending (parsing), ready, failed'
          example: ready
      required:
      - documentId
      - jobPreferenceFields
      - profileFields
      - resumeLocations
      - seedableSkillsCount
      - status
      additionalProperties: false
    ResponseMetadata:
      type: object
      properties:
        duration:
          type: number
          description: Request duration in milliseconds
          example: 150
          exclusiveMinimum: 0
        performance:
          type: object
          properties:
            dbQueries:
              type: integer
              minimum: 0
            totalDbTime:
              type: number
              minimum: 0
          description: Performance metrics (preview/local only)
        requestId:
          type: string
          description: Unique request identifier
          example: req_abc123
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
          example: '2026-09-25T17:29:47.224Z'
        version:
          type: string
          description: API version
          example: v1
    DiscoverStatusData:
      type: object
      properties:
        completedAt:
          type: integer
          description: Epoch ms when the job completed (success only)
          example: 1729500000000
        error:
          type: string
          description: Error message if the discovery failed
          example: OpenRouter timeout
        failedAt:
          type: integer
          description: Epoch ms when the job failed
          example: 1729500000000
        startedAt:
          type: integer
          description: Epoch ms when the job was kicked off
          example: 1729500000000
        status:
          type: string
          enum:
          - processing
          - completed
          - failed
          - unknown
          description: Status of the background match-discovery job kicked off by auto-setup
          example: processing
      required:
      - status
      additionalProperties: false
    CompleteOnboardingRequest:
      type: object
      properties:
        autoApplyMode:
          type: string
          enum:
          - copilot
          - autopilot
      additionalProperties: false
    MintOnboardingEscrowBody:
      type: object
      properties:
        answers:
          type: object
          properties:
            activelyLooking:
              type: boolean
            attributionSource:
              type: string
              enum:
              - social
              - influencer
              - friend
              - search
              - ad
              - other
              description: How the user discovered AI Applyd
              example: search
            blockers:
              type: array
              items:
                type: string
                enum:
                - not_applying_enough
                - cant_land_interviews
                - not_ready_yet
                - lack_great_offers
                description: A blocker the user feels is hindering their job search
                example: not_applying_enough
              maxItems: 3
            categories:
              type: array
              items:
                type: string
                enum:
                - software_engineering
                - healthcare
                - consulting
                - data
                - design
                - finance
                - legal
                - hr
                - marketing
                - operations_strategy
                - product
                - sales
                - customer_success
                - security
                - misc_engineering
                description: Coarse career-field category for onboarding role discovery
                example: software_engineering
              maxItems: 3
            customRoles:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 120
              maxItems: 5
            experienceBand:
              type: string
              enum:
              - internship
              - entry
              - junior
              - mid
              - senior
              - expert
              description: Onboarding-facing experience band picked by the user
              example: mid
            experienceBands:
              type: array
              items:
                type: string
                enum:
                - internship
                - entry
                - junior
                - mid
                - senior
                - expert
                description: Onboarding-facing experience band picked by the user
                example: mid
              maxItems: 6
            goal:
              type: string
              enum:
              - land_asap
              - make_more_money
              - land_dream_job
              description: The user's primary job-search goal
              example: land_asap
            importance:
              type: array
              items:
                type: string
                enum:
                - meaningful_work
                - experienced_leaders
                - top_investors
                - wear_many_hats
                - smart_people
                - challenging_work
                - growing_fast
                - cool_startup
                - stable_company
                - innovative_tech
                - flexible_hours
                - great_benefits
                description: A factor the user cares about most in their next role
                example: meaningful_work
              maxItems: 3
            interviewsPerWeekTarget:
              type: integer
              minimum: 0
              maximum: 50
            jobTimeline:
              type: string
              enum:
              - one_month
              - three_months
              - six_months
              - twelve_months_plus
              description: How soon the user wants to land a new role
              example: three_months
            locations:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 160
              maxItems: 5
            motivations:
              type: array
              items:
                type: string
                enum:
                - more_money
                - support_family
                - exciting_job
                - get_time_back
                description: A motivation driving the user's job search
                example: more_money
              maxItems: 3
            referralCodeUsed:
              type: string
              minLength: 1
              maxLength: 64
            remoteGlobal:
              type: boolean
            roles:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 120
              maxItems: 5
            salaryCurrency:
              type: string
              enum:
              - usd
              - eur
              - gbp
              - cad
              - aud
              - inr
              description: Currency for salary values
              example: usd
            salaryMax:
              type: number
              minimum: 0
            salaryMin:
              type: number
              minimum: 0
            triedOtherApps:
              type: boolean
          additionalProperties: false
        screen:
          type: integer
          minimum: 1
          maximum: 64
          description: Furthest pre-auth screen reached, so the return leg resumes in place.
          example: 18
      required:
      - answers
      - screen
      additionalProperties: false
    ParseResumeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ParsedResumeData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ApiErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            context:
              oneOf:
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - validation
                  field:
                    type: string
                  fieldErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                        received:
                          type: string
                      required:
                      - field
                      - message
                  schemaName:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  attemptedEmail:
                    type: string
                    format: email
                  errorType:
                    type: string
                    enum:
                    - authentication
                  failureReason:
                    type: string
                    enum:
                    - invalid_credentials
                    - account_locked
                    - expired_token
                    - token_expired
                    - missing_token
                    - invalid_token
                    - session_expired
                    description: Reason for authentication failure
                    example: token_expired
                  ipAddress:
                    type: string
                  operation:
                    type: string
                  service:
                    type: string
                  userAgent:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  actualPermission:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - authorization
                  requiredPermission:
                    type: string
                  resource:
                    type: string
                  resourceId:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  constraint:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - database
                  operation:
                    type: string
                    enum:
                    - insert
                    - update
                    - delete
                    - select
                    - batch
                    - transaction
                    - migration
                    description: Type of database operation
                    example: select
                  resourceId:
                    type: string
                  sqlState:
                    type: string
                  table:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  endpoint:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - external_service
                  httpStatus:
                    type: number
                  operation:
                    type: string
                  resourceId:
                    type: string
                  responseTime:
                    type: number
                  retryAttempt:
                    type: integer
                  service:
                    type: string
                  serviceName:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - resource
                  resource:
                    type: string
                  resourceId:
                    type: string
                  service:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - rate_limit
                  limit:
                    type: number
                  resetTime:
                    type: string
                  windowMs:
                    type: number
                required:
                - errorType
              - type: object
                properties:
                  configKey:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - configuration
                  operation:
                    type: string
                  service:
                    type: string
                required:
                - errorType
              description: Type-safe error context information
              example:
                errorType: validation
                fieldErrors:
                - field: email
                  message: Invalid email format
            details:
              oneOf:
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - validation
                  validationErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                      required:
                      - field
                      - message
                required:
                - detailType
                - validationErrors
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - service_error
                  originalError:
                    type: string
                  serviceName:
                    type: string
                required:
                - detailType
                - serviceName
                additionalProperties: false
              - type: object
                properties:
                  currentSize:
                    type: number
                  detailType:
                    type: string
                    enum:
                    - batch
                  originalError:
                    type: string
                  statementCount:
                    type: number
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - rate_limit
                  limit:
                    type: number
                  resetTime:
                    type: string
                  windowMs:
                    type: number
                required:
                - detailType
                - limit
                - resetTime
                - windowMs
                additionalProperties: false
              - type: object
                properties:
                  conflictingField:
                    type: string
                  detailType:
                    type: string
                    enum:
                    - resource
                  resourceId:
                    anyOf:
                    - type: string
                    - type: number
                  resourceType:
                    type: string
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - generic
                  info:
                    type: string
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  currentTokens:
                    type: integer
                    minimum: 0
                  detailType:
                    type: string
                    enum:
                    - insufficient_tokens
                  requiredTokens:
                    type: integer
                    minimum: 0
                required:
                - currentTokens
                - detailType
                - requiredTokens
                additionalProperties: false
            message:
              type: string
            validation:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                - field
                - message
                additionalProperties: false
          required:
          - code
          - message
          additionalProperties: false
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - false
      required:
      - error
      - success
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      description: 'Session token from signing in to AI Applyd, sent as `Authorization: Bearer <token>`.'
      scheme: bearer
      type: http