> ## 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

> Structured search for multiple OR'd queries and locations, explicit
include/exclude filters, date and salary ranges, field selection, and
facets. The body is optional; an omitted body performs an unfiltered
first-page search.




## OpenAPI

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

    real-time feeds, geocoding services, and a contract preview for
    callback-driven

    job applications. Auto Apply is coming soon and is not available in beta or
    production.
  version: '2026-07-21'
  contact:
    name: Jobo Support
    url: https://jobo.world
    email: support@jobo.world
  license:
    name: Proprietary — see terms of service
    url: https://jobo.world/terms
  termsOfService: https://jobo.world/terms
servers:
  - url: https://connect.jobo.world
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Jobs
    description: Search and retrieve job listings
  - name: Feed
    description: Bulk job feeds and expiration tracking
  - name: Companies
    description: Company profiles and company-scoped job listings
  - name: Auto Apply
    description: >-
      Coming soon: profileless applications answered through signed, typed HTTPS
      callbacks
  - name: Locations
    description: Geocoding and location services
paths:
  /api/jobs/search:
    post:
      tags:
        - Jobs
      summary: Search jobs
      description: |
        Structured search for multiple OR'd queries and locations, explicit
        include/exclude filters, date and salary ranges, field selection, and
        facets. The body is optional; an omitted body performs an unfiltered
        first-page search.
      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/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X POST "https://connect.jobo.world/api/jobs/search" \
              -H "X-Api-Key: $JOBO_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "queries": ["backend engineer"],
                "locations": ["London"],
                "work_models": ["remote", "hybrid"],
                "experience_levels": ["senior"],
                "salary_usd": { "min": 150000 },
                "page_size": 50
              }'
        - lang: Python
          source: |
            from jobo_enterprise import JoboClient, RangeFilter

            with JoboClient(api_key="YOUR_API_KEY") as client:
                results = client.search.search_advanced(
                    queries=["backend engineer"],
                    locations=["London"],
                    work_models=["remote", "hybrid"],
                    experience_levels=["senior"],
                    salary_usd=RangeFilter(min=150_000),
                    page_size=50,
                )
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 title, curated alternative titles, company,
            popular skills, and 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 summary 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.
            In both modes results are relevance-ordered — jobs matching every
            word of a query always rank above partial matches, and partial
            matches only appear at the tail when a query has no full match
            inside the filtered window (e.g. a short `posted_after` range). Take
            results from the top; the tail of a large page is best-effort
            filler.
        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:
          type: object
          allOf:
            - $ref: '#/components/schemas/InclusionExclusionFilter'
          nullable: true
          description: Include/exclude skills filter
        companies:
          type: object
          allOf:
            - $ref: '#/components/schemas/InclusionExclusionFilter'
          nullable: true
          description: Include/exclude company display names, resolved case-insensitively.
        industries:
          type: object
          allOf:
            - $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
            enum:
              - full-time
              - part-time
              - contract
              - internship
              - freelance
              - temporary
          nullable: true
          description: >-
            Filter by employment type: full-time, part-time, contract,
            internship, freelance, temporary
        experience_levels:
          type: array
          items:
            type: string
            enum:
              - intern
              - entry
              - mid
              - senior
              - lead
              - executive
          nullable: true
          description: >
            Exact-match experience-level filter. Canonical values are `intern`,
            `entry`, `mid`, `senior`, `lead`, and `executive`.
        salary_usd:
          type: object
          allOf:
            - $ref: '#/components/schemas/RangeFilterInt'
          nullable: true
          description: >
            Annualized USD range-overlap filter. A job matches when its
            disclosed

            salary range intersects the requested range. Jobs without disclosed

            compensation are excluded.
        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
        discovered_after:
          type: string
          format: date-time
          nullable: true
          description: Only return jobs first indexed on or after this UTC timestamp
        discovered_before:
          type: string
          format: date-time
          nullable: true
          description: Only return jobs first indexed on or before this UTC timestamp
        page:
          type: integer
          default: 1
          minimum: 1
        page_size:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        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
      required:
        - jobs
        - total
        - page
        - page_size
        - total_pages
        - facets
      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: 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
        code:
          type: string
          nullable: true
          description: Stable machine-readable code for Auto Apply domain errors.
        api_version:
          $ref: '#/components/schemas/AutoApplyApiVersion'
    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
          minimum: 0
          nullable: true
        max:
          type: integer
          minimum: 0
          nullable: true
    JobDto:
      type: object
      required:
        - id
        - title
        - normalized_title
        - company
        - description
        - summary
        - listing_url
        - apply_url
        - locations
        - compensation
        - employment_type
        - workplace_type
        - experience_level
        - source
        - created_at
        - updated_at
        - date_posted
        - valid_through
        - qualifications
        - responsibilities
        - benefits
        - is_work_auth_required
        - is_h1b_sponsor
        - is_clearance_required
      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:
          type: object
          allOf:
            - $ref: '#/components/schemas/JobCompensationDto'
          nullable: true
          description: |
            Compensation as published by the employer. USD annualization is
            used for salary filters but is not returned in this object.
        employment_type:
          type: string
          nullable: true
          enum:
            - Full-time
            - Part-time
            - Contract
            - Internship
            - Freelance
            - Temporary
        workplace_type:
          type: string
          nullable: true
          enum:
            - Remote
            - Hybrid
            - On-site
        experience_level:
          type: string
          nullable: true
          enum:
            - Intern
            - Entry Level
            - Mid Level
            - Senior
            - Lead
            - Executive
        source:
          type: string
          example: greenhouse
          description: |
            ATS provider identifier. This remains an open string so newly
            supported providers do not break generated clients.
        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
      required:
        - key
        - count
      properties:
        key:
          type: string
        count:
          type: integer
          format: int64
    AutoApplyApiVersion:
      type: string
      description: Version of the profileless Auto Apply API contract.
      enum:
        - '2026-07-21'
      example: '2026-07-21'
    ApiRateLimitError:
      type: object
      description: API-key request-window rejection returned by rate-limit middleware.
      required:
        - error
        - detail
        - group
        - retry_after_seconds
      properties:
        error:
          type: string
          example: Rate limit exceeded
        detail:
          type: string
        group:
          type: string
          example: AutoApply
        retry_after_seconds:
          type: integer
          minimum: 0
          nullable: true
    JobCompanyDto:
      type: object
      required:
        - id
        - name
        - website
        - logo_url
        - summary
        - industries
        - categories
        - linkedin_url
        - crunchbase_url
        - details_url
      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 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: >
            Direct Jobo API URL to the full company profile endpoint

            (`GET https://connect.jobo.world/api/companies/{id}`).

            RapidAPI consumers should rebuild `/api/companies/{id}` on their

            marketplace gateway instead of following this URL with a RapidAPI
            key.
    JobLocationDto:
      type: object
      required:
        - location
        - city
        - region
        - country
        - latitude
        - longitude
      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
      required:
        - min
        - max
        - currency
        - period
      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
    JobQualificationsDto:
      type: object
      required:
        - must_have
        - preferred
      properties:
        must_have:
          $ref: '#/components/schemas/QualificationBucketDto'
        preferred:
          $ref: '#/components/schemas/QualificationBucketDto'
    QualificationBucketDto:
      type: object
      required:
        - education
        - certifications
        - skills
      properties:
        education:
          type: array
          items:
            type: string
        certifications:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            $ref: '#/components/schemas/QualificationSkillDto'
    QualificationSkillDto:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          type: string
          default: hard
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 0
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
        application/json:
          schema:
            $ref: '#/components/schemas/ApiRateLimitError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key provided by Jobo

````