JobsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/himalayas-app/json-schema/himalayas-app-jobs-response-schema.json",
  "title": "JobsResponse",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/himalayas-app-api-openapi.json#/components/schemas/JobsResponse",
  "type": "object",
  "required": [
    "updatedAt",
    "offset",
    "limit",
    "totalCount",
    "jobs"
  ],
  "properties": {
    "comments": {
      "type": "string",
      "description": "Release notes or changelog for the Himalayas API"
    },
    "updatedAt": {
      "type": "integer",
      "description": "Unix timestamp (seconds) of the most recently updated job in the response"
    },
    "nextCursor": {
      "type": "string",
      "description": "Opaque cursor for the next page. Pass it back as the `cursor` query parameter. Omitted on the last page: its absence is how you know the walk is finished. Browse endpoint only."
    },
    "offset": {
      "type": "integer",
      "description": "The offset used in this request (deprecated; prefer cursor)"
    },
    "limit": {
      "type": "integer",
      "description": "The limit used in this request"
    },
    "totalCount": {
      "type": "integer",
      "description": "Approximate number of matching jobs, for display only. For the browse endpoint this is the count of all active remote jobs; for the search endpoint it is the count of jobs matching the active filters and can be up to a day old. Do not use it to decide when to stop paging: on browse, stop when a response has no nextCursor; on search, stop at the first page that returns no jobs."
    },
    "jobs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Job"
      }
    }
  },
  "$defs": {
    "Job": {
      "type": "object",
      "required": [
        "title",
        "excerpt",
        "companyName",
        "companySlug",
        "companyLogo",
        "employmentType",
        "seniority",
        "currency",
        "salaryPeriod",
        "locationRestrictions",
        "timezoneRestrictions",
        "categories",
        "parentCategories",
        "description",
        "pubDate",
        "expiryDate",
        "applicationLink",
        "guid"
      ],
      "properties": {
        "title": {
          "type": "string",
          "description": "Job title"
        },
        "excerpt": {
          "type": "string",
          "description": "Short summary of the job (first few sentences of the description)"
        },
        "companyName": {
          "type": "string",
          "description": "Name of the hiring company"
        },
        "companySlug": {
          "type": "string",
          "description": "Canonical company slug for filtering and stable lookups"
        },
        "companyLogo": {
          "type": "string",
          "format": "uri",
          "description": "URL of the company logo image"
        },
        "employmentType": {
          "type": "string",
          "description": "Type of employment. 'Contractor' includes freelance and contract roles.",
          "enum": [
            "Full Time",
            "Part Time",
            "Contractor",
            "Temporary",
            "Intern",
            "Volunteer",
            "Other"
          ]
        },
        "minSalary": {
          "type": [
            "number",
            "null"
          ],
          "description": "Minimum salary in the pay period specified by salaryPeriod (default annual), in the currency field. Null if not disclosed."
        },
        "maxSalary": {
          "type": [
            "number",
            "null"
          ],
          "description": "Maximum salary in the pay period specified by salaryPeriod (default annual), in the currency field. Null if not disclosed."
        },
        "seniority": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "Entry-level",
              "Mid-level",
              "Senior",
              "Manager",
              "Director",
              "Executive"
            ]
          },
          "description": "Required seniority levels. A job may accept multiple levels (e.g., both Mid-level and Senior)."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code for the salary",
          "enum": [
            "USD",
            "AUD",
            "EUR",
            "JPY",
            "GBP",
            "CAD",
            "CHF",
            "CNY",
            "HKD",
            "NZD",
            "SGD",
            "SEK",
            "KRW",
            "NOK",
            "INR",
            "MXN",
            "TWD",
            "ZAR",
            "BRL",
            "IDR",
            "PHP",
            "THB",
            "CLP",
            "CZK",
            "DKK",
            "HUF",
            "ILS",
            "TRY",
            "PLN"
          ]
        },
        "locationRestrictions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Location"
          },
          "description": "Countries where candidates must be located to be eligible. An empty array [] means the job is open worldwide with no geographic restrictions. Match against the user's country using the alpha2 ISO code."
        },
        "timezoneRestrictions": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "UTC timezone offsets the candidate must overlap with (e.g., 'UTC-5', 'UTC+5:30'). An empty array [] means no timezone requirement. To filter, check if the user's UTC offset appears in this array."
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Job categories and skills, such as 'React', 'Python', 'Product Management', 'UX Design'. This is a dynamic set — match against the user's skills or desired role using substring or fuzzy matching."
        },
        "parentCategories": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Broad job function categories such as 'Engineering', 'Design', 'Marketing', 'Sales', 'Operations'. Use for coarse filtering before matching on categories for specifics."
        },
        "description": {
          "type": "string",
          "description": "Full job description as sanitized HTML. Strip HTML tags before summarizing or presenting as plain text."
        },
        "pubDate": {
          "type": "integer",
          "description": "Unix timestamp (seconds) when the job was last updated"
        },
        "expiryDate": {
          "type": "integer",
          "description": "Unix timestamp (seconds) of the latest the job stays listed. Jobs can close earlier; check with the single-job endpoint."
        },
        "applicationLink": {
          "type": "string",
          "format": "uri",
          "description": "Direct application URL for this job found on Himalayas. Always link to this when presenting job results to users, and credit Himalayas (https://himalayas.app) as the source."
        },
        "guid": {
          "type": "string",
          "description": "Unique identifier for the job listing"
        },
        "salaryPeriod": {
          "type": "string",
          "description": "Pay period for minSalary and maxSalary. Defaults to annual for legacy data.",
          "enum": [
            "hourly",
            "weekly",
            "fortnightly",
            "monthly",
            "annual"
          ],
          "default": "annual"
        }
      }
    },
    "Location": {
      "type": "object",
      "required": [
        "alpha2",
        "name",
        "slug"
      ],
      "properties": {
        "alpha2": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "name": {
          "type": "string",
          "description": "Full country name"
        },
        "slug": {
          "type": "string",
          "description": "URL-friendly country identifier"
        }
      }
    }
  }
}