> ## Documentation Index
> Fetch the complete documentation index at: https://jobo.world/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search jobs via structured request body



## OpenAPI

````yaml /openapi.yaml post /api/jobs/search
openapi: 3.1.0
info:
  title: Jobo Enterprise API
  description: >
    The Jobo Enterprise API provides programmatic access to job listings,
    intelligent search,

    real-time feeds, automated job applications, and geocoding services.
  version: 1.0.0
  contact:
    name: Jobo Support
    url: https://jobo.world
    email: support@jobo.world
servers:
  - url: https://connect.jobo.world
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Jobs Search
    description: Search and retrieve job listings
  - name: Jobs Feed
    description: Bulk job feeds and expiration tracking
  - name: Career Sites Feed
    description: Bulk feed of newly discovered career sites with enriched company profiles
  - name: Companies
    description: Company profiles and company-scoped job listings
  - name: Auto Apply
    description: Automated job application sessions
  - name: Auto Apply Profiles
    description: Manage applicant profiles for auto-apply
  - name: Locations
    description: Geocoding and location services
paths:
  /api/jobs/search:
    post:
      tags:
        - Jobs Search
      summary: Search jobs via structured request body
      operationId: searchJobsPost
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobSearchBodyRequest'
      responses:
        '200':
          description: Paginated list of matching jobs with optional facets
          headers:
            X-Total-Count:
              schema:
                type: integer
                format: int64
            X-Total-Pages:
              schema:
                type: integer
            X-Page:
              schema:
                type: integer
            X-Page-Size:
              schema:
                type: integer
            X-Credits-Deducted:
              schema:
                type: integer
            X-Credits-Balance:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSearchResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    JobSearchBodyRequest:
      type: object
      properties:
        queries:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Free-text search queries; multiple entries are OR'd. Each entry
            matches broadly by default (title, company name, popular skills,
            summary) with typo tolerance. Wrap an entry in double quotes (e.g.
            "\"Quantitative Developer\"") to make it an exact, contiguous phrase
            match restricted to the job title only — use this when a query is a
            job-title filter and broad matches are noise. Prefix an entry with
            `-` to exclude it. Maximum 10 positive terms per request; more
            returns a 400 (negative `-` exclusions don't count toward the
            limit).
        search_description:
          type: boolean
          default: true
          description: >-
            Controls which fields the `queries` match against. When `true`
            (default), queries match the job title, company, skills, AND the job
            description/summary — broad recall, best for keyword discovery (e.g.
            "python" finds a "Software Engineer" that lists Python as a skill).
            When `false`, queries match against job titles only — the job's own
            title plus a curated set of same-role alternative titles, so
            "Android Developer" also finds roles titled "Android Engineer"
            without pulling in jobs that merely mention the terms in their
            description or skills (e.g. an "IT Support Engineer" that lists
            Android as a skill no longer matches). Use `false` when you pass
            exact job titles and want relevance over keyword recall.
            Double-quoted entries are stricter still: an exact, contiguous
            phrase match against the literal job title only (alternative titles
            excluded) — the escape hatch when even title synonyms are unwanted.
        locations:
          type: array
          items:
            type: string
          nullable: true
          description: Location strings to filter by (geocoded automatically)
        sources:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Restrict to specific ATS provider IDs (e.g. greenhouse, lever,
            workday).
        skills:
          $ref: '#/components/schemas/InclusionExclusionFilter'
          nullable: true
          description: Include/exclude skills filter
        companies:
          $ref: '#/components/schemas/InclusionExclusionFilter'
          nullable: true
          description: Include/exclude companies filter
        industries:
          $ref: '#/components/schemas/InclusionExclusionFilter'
          nullable: true
          description: >-
            Include/exclude company-industry filter (matched
            case-insensitively).
        work_models:
          type: array
          items:
            type: string
            enum:
              - remote
              - hybrid
              - onsite
          nullable: true
          description: 'Filter by work model: remote, hybrid, onsite'
        employment_types:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Filter by employment type: full-time, part-time, contract,
            internship, freelance, temporary
        experience_levels:
          type: array
          items:
            type: string
          nullable: true
          description: >
            Filter by experience level. Canonical values: `intern`, `entry`,
            `mid`, `senior`, `lead`, `executive`. Values are normalized through
            a synonym dictionary (junior → entry, sr/staff/principal → senior,
            manager → lead, director/vp/c-level → executive, etc.).
        salary_usd:
          $ref: '#/components/schemas/RangeFilterInt'
          nullable: true
          description: Salary range filter in USD (annual)
        posted_after:
          type: string
          format: date-time
          nullable: true
          description: >-
            Only return jobs whose employer posting date is on or after this
            date
        posted_before:
          type: string
          format: date-time
          nullable: true
          description: >-
            Only return jobs whose employer posting date is on or before this
            date
        page:
          type: integer
          default: 1
        page_size:
          type: integer
          default: 25
        include_facets:
          type: array
          items:
            type: string
            enum:
              - work_model
              - experience_level
              - employment_type
              - sources
              - industries
              - skills
          nullable: true
          description: >
            Facets to compute and return. Omit (or `null`) for the default
            subset (`work_model`, `experience_level`, `employment_type`,
            `sources`). Pass an empty array to skip facets entirely.
            `industries` and `skills` are high-cardinality and only computed
            when explicitly requested. Unknown names are ignored.
        include_fields:
          type: array
          items:
            type: string
            enum:
              - description
              - summary
              - qualifications
              - responsibilities
              - benefits
          nullable: true
          description: >
            Heavy, non-core fields to include. Omit (or `null`) for the full job
            — every field, the default. Pass a subset to keep only those
            non-core fields alongside the always-present core fields. Pass an
            empty array for core fields only. Unknown names are ignored;
            excluded non-core fields come back empty.
    JobSearchResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobDto'
        total:
          type: integer
          format: int64
        page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        facets:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/JobFacetDto'
    ProblemDetails:
      type: object
      description: RFC 7807 problem details object returned for error responses.
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
    InclusionExclusionFilter:
      type: object
      properties:
        include:
          type: array
          items:
            type: string
          nullable: true
          description: Values to include (matched case-insensitively)
        exclude:
          type: array
          items:
            type: string
          nullable: true
          description: Values to exclude (matched case-insensitively)
    RangeFilterInt:
      type: object
      properties:
        min:
          type: integer
          nullable: true
        max:
          type: integer
          nullable: true
    JobDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        normalized_title:
          type: string
          nullable: true
        company:
          $ref: '#/components/schemas/JobCompanyDto'
        description:
          type: string
        summary:
          type: string
          nullable: true
        listing_url:
          type: string
        apply_url:
          type: string
        locations:
          type: array
          items:
            $ref: '#/components/schemas/JobLocationDto'
        compensation:
          oneOf:
            - $ref: '#/components/schemas/JobCompensationDto'
          nullable: true
        employment_type:
          type: string
          nullable: true
          enum:
            - Full-time
            - Part-time
            - Contract
            - Internship
            - Freelance
            - Temporary
            - null
        workplace_type:
          type: string
          nullable: true
          enum:
            - Remote
            - Hybrid
            - On-site
            - null
        experience_level:
          type: string
          nullable: true
          enum:
            - Intern
            - Entry Level
            - Mid Level
            - Senior
            - Lead
            - Executive
            - null
        source:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        date_posted:
          type: string
          format: date-time
          nullable: true
        valid_through:
          type: string
          format: date-time
          nullable: true
        qualifications:
          $ref: '#/components/schemas/JobQualificationsDto'
        responsibilities:
          type: array
          items:
            type: string
        benefits:
          type: array
          items:
            type: string
        is_work_auth_required:
          type: boolean
          nullable: true
        is_h1b_sponsor:
          type: boolean
          nullable: true
        is_clearance_required:
          type: boolean
          nullable: true
    JobFacetDto:
      type: object
      properties:
        key:
          type: string
        count:
          type: integer
          format: int64
    JobCompanyDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        website:
          type: string
          nullable: true
        logo_url:
          type: string
          nullable: true
        summary:
          type: string
          nullable: true
        industries:
          type: array
          items:
            type: string
          description: Industry tags (typically 1-3) describing what the company does.
        categories:
          type: array
          items:
            type: string
          description: Business-model bucket tags (b2b / b2c / saas / service-provider).
        linkedin_url:
          type: string
          nullable: true
        crunchbase_url:
          type: string
          nullable: true
        details_url:
          type: string
          nullable: true
          description: |
            Public URL to the full company profile endpoint
            (`GET https://connect.jobo.world/api/companies/{id}`).
            Null when `id` is empty.
    JobLocationDto:
      type: object
      properties:
        location:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        latitude:
          type: number
          format: double
          nullable: true
        longitude:
          type: number
          format: double
          nullable: true
    JobCompensationDto:
      type: object
      properties:
        min:
          type: number
          format: decimal
          nullable: true
        max:
          type: number
          format: decimal
          nullable: true
        currency:
          type: string
          nullable: true
        period:
          type: string
          nullable: true
          enum:
            - hourly
            - daily
            - weekly
            - monthly
            - yearly
            - per-diem
            - null
    JobQualificationsDto:
      type: object
      properties:
        must_have:
          $ref: '#/components/schemas/QualificationBucketDto'
        preferred:
          $ref: '#/components/schemas/QualificationBucketDto'
    QualificationBucketDto:
      type: object
      properties:
        education:
          type: array
          items:
            type: string
        certifications:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            $ref: '#/components/schemas/QualificationSkillDto'
    QualificationSkillDto:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          default: hard
  responses:
    Unauthorized:
      description: Missing or invalid API key
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key provided by Jobo

````