Himalayas Jobs API

openapi: 3.2.0
info:
  title: Himalayas App Jobs API
  version: 1.0.0
  contact:
    name: Himalayas
    url: https://himalayas.app
    email: hi@himalayas.app
  license:
    name: Free to use with attribution
    url: https://himalayas.app/docs/remote-jobs-api
  termsOfService: https://himalayas.app/docs/remote-jobs-api
  x-logo:
    url: https://himalayas.app/logos/android-icon-192x192.png
    altText: Himalayas
  description: 'Operations tagged Jobs across 2 of this provider''s published API definitions: himalayas-app-api-openapi.json, himalayas-app-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://himalayas.app
  description: Production
tags:
- name: Jobs
  description: Remote job listings from Himalayas. Use the browse endpoint to page through the full feed, or the search endpoint to filter by keyword, country, seniority, employment type, company slug, timezone, and sort order.
  externalDocs:
    description: Remote Jobs API documentation
    url: https://himalayas.app/docs/remote-jobs-api
paths:
  /jobs/api:
    get:
      operationId: browseHimalayasRemoteJobs
      summary: Browse the full Himalayas remote jobs feed
      description: 'Returns the full unfiltered remote jobs feed from Himalayas (https://himalayas.app) with cursor pagination. Use this endpoint when you want to page through all current jobs, backfill a job board, or sync the entire feed into your own system. Paginate with `cursor`: omit it on the first request, then pass each response''s `nextCursor` back until a response omits it. `offset` is still accepted but is deprecated and will be removed in a future release. If you want filtered search results instead, use `GET /jobs/api/search`.'
      tags:
      - Jobs
      externalDocs:
        description: Browse endpoint documentation with code examples
        url: https://himalayas.app/docs/remote-jobs-api#browse-all-jobs-with-pagination
      parameters:
      - name: limit
        in: query
        description: Number of jobs per page. Maximum and default is 20. Use 20 for fastest pagination.
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 20
      - name: cursor
        in: query
        description: 'Preferred pagination. Opaque pointer to your position in the feed: omit on the first request, then pass back the `nextCursor` value from each response. When a response has no `nextCursor`, the walk is complete. Do not construct or parse cursor values; the format is opaque and may change.'
        required: false
        schema:
          type: string
        example: MjAyNi0wOC0yMVQwODozODoxNC4xNzc1NTBafDIwNjc2OTc
      - name: offset
        in: query
        description: 'Deprecated: use `cursor` instead; this parameter will be removed in a future release. Number of jobs to skip. Start at 0, then increment by limit (e.g., 0, 20, 40, 60). Offset pagination can skip or repeat jobs when the feed changes mid-walk, and gets slower the deeper you page.'
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
        deprecated: true
      responses:
        '200':
          description: Successful response with remote job listings from Himalayas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobsResponse'
          headers:
            Cache-Control:
              description: Caching directive
              schema:
                type: string
                example: public, s-maxage=86400, stale-while-revalidate=86400
        '400':
          description: Invalid query parameters. Check that limit is between 1-20, offset is a non-negative integer, and cursor is a value previously returned as nextCursor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                ok: false
                errors: Invalid cursor.
        '429':
          description: Request limit reached. Retry-After gives seconds before retrying. Account allowances are shared across integrations and keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                ok: false
                errors: 'Too many requests. Please try again in a few seconds. #9143'
          headers:
            Retry-After:
              description: Seconds to wait
              schema:
                type: integer
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Minute-Limit:
              $ref: '#/components/headers/X-RateLimit-Minute-Limit'
            X-RateLimit-Minute-Remaining:
              $ref: '#/components/headers/X-RateLimit-Minute-Remaining'
            X-RateLimit-Minute-Reset:
              $ref: '#/components/headers/X-RateLimit-Minute-Reset'
        '401':
          description: Invalid, revoked, suspended or unverified API key.
        '503':
          description: Job data or authorization is temporarily unavailable. Retry later.
      security:
      - JobsApiKey: []
      - {}
    servers:
    - url: https://himalayas.app
      description: Production
  /jobs/api/search:
    get:
      operationId: searchHimalayasRemoteJobs
      summary: Search Himalayas remote jobs with filters
      description: Returns filtered remote job results in the same JSON shape as `GET /jobs/api`. Use this endpoint when you want to search by keyword, country, worldwide availability, seniority, employment type, company slug, timezone, sort order, or page without paging through the full feed locally.
      tags:
      - Jobs
      externalDocs:
        description: Search endpoint documentation with filter examples
        url: https://himalayas.app/docs/remote-jobs-api#search-jobs-with-filters
      parameters:
      - name: q
        in: query
        description: Free-text job search query.
        required: false
        schema:
          type: string
      - name: country
        in: query
        description: Country filter. Supports ISO alpha-2, common country names, slugs, and common abbreviations.
        required: false
        schema:
          type: string
      - name: worldwide
        in: query
        description: Limit results to worldwide-friendly jobs.
        required: false
        schema:
          type: boolean
          default: false
      - name: exclude_worldwide
        in: query
        description: Exclude worldwide matches when a country filter is present.
        required: false
        schema:
          type: boolean
          default: false
      - name: seniority
        in: query
        description: Comma-separated seniority filters. Valid values are Entry-level, Mid-level, Senior, Manager, Director, and Executive.
        required: false
        schema:
          type: string
      - name: employment_type
        in: query
        description: Comma-separated employment type filters. Valid values are Full Time, Part Time, Contractor, Temporary, Intern, Volunteer, and Other.
        required: false
        schema:
          type: string
      - name: company
        in: query
        description: Canonical company slug. Supports comma-separated values.
        required: false
        schema:
          type: string
      - name: timezone
        in: query
        description: Timezone filter. Supports numeric UTC offsets and variants like `UTC-5` or `UTC+05:30`.
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: Sort order for results. 'relevant' ranks by best match to the query and filters (default). 'recent' returns newest jobs first. 'salaryAsc' returns lowest salary first. 'salaryDesc' returns highest salary first. 'nameAToZ' sorts by company name A to Z. 'nameZToA' sorts by company name Z to A. 'jobs' sorts by companies with the most open roles first.
        required: false
        schema:
          type: string
          enum:
          - relevant
          - recent
          - salaryAsc
          - salaryDesc
          - nameAToZ
          - nameZToA
          - jobs
          default: relevant
      - name: page
        in: query
        description: 1-based results page. Pages can hold fewer jobs than the limit before the end of the results, so keep requesting until a page returns no jobs, and de-duplicate on guid because results can shift between pages.
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: Successful filtered response with remote job listings from Himalayas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobsResponse'
          headers:
            Cache-Control:
              description: Caching directive
              schema:
                type: string
                example: public, s-maxage=86400, stale-while-revalidate=86400
        '400':
          description: Invalid explicit filter value, such as an unrecognized country or timezone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                ok: false
                errors: Invalid country
        '429':
          description: Request limit reached. Retry-After gives seconds before retrying. Account allowances are shared across integrations and keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                ok: false
                errors: 'Too many requests. Please try again in a few seconds. #9143'
          headers:
            Retry-After:
              description: Seconds to wait
              schema:
                type: integer
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Minute-Limit:
              $ref: '#/components/headers/X-RateLimit-Minute-Limit'
            X-RateLimit-Minute-Remaining:
              $ref: '#/components/headers/X-RateLimit-Minute-Remaining'
            X-RateLimit-Minute-Reset:
              $ref: '#/components/headers/X-RateLimit-Minute-Reset'
        '401':
          description: Invalid, revoked, suspended or unverified API key.
        '503':
          description: Job data or authorization is temporarily unavailable. Retry later.
      security:
      - JobsApiKey: []
      - {}
    servers:
    - url: https://himalayas.app
      description: Production
  /jobs/api/companies/{company}/jobs/{slug}:
    get:
      operationId: getHimalayasRemoteJob
      summary: Check one Himalayas remote job is still open
      description: 'Returns one job by the path in its feed `guid`: put `/jobs/api` after the domain. 200 while the job is open, 410 once it has closed, 404 if the API never listed it. Jobs can close before their expiryDate, so use this instead of requesting job pages. Answers are cached for up to 10 minutes. An API key gives higher limits.'
      tags:
      - Jobs
      parameters:
      - name: company
        in: path
        required: true
        description: Company slug from the job's guid.
        schema:
          type: string
        example: linear
      - name: slug
        in: path
        required: true
        description: Job slug from the job's guid.
        schema:
          type: string
        example: senior-product-engineer
      responses:
        '200':
          description: The job is open.
          content:
            application/json:
              schema:
                type: object
                required:
                - job
                properties:
                  job:
                    $ref: '#/components/schemas/Job'
        '401':
          description: Invalid, revoked, suspended or unverified API key.
        '404':
          description: There is no job at this path in the API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                ok: false
                errors: Job not found.
        '410':
          description: The job has closed. Remove it from your listings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  errors:
                    type: string
                  expired:
                    type: boolean
                  expiryDate:
                    type: integer
                    description: Unix seconds when the job closed.
              example:
                ok: false
                errors: This job has expired.
                expired: true
                expiryDate: 1760918400
        '429':
          description: Request limit reached. Retry-After gives seconds before retrying.
          headers:
            Retry-After:
              description: Seconds to wait
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Job data or authorization is temporarily unavailable. Retry later.
      security:
      - JobsApiKey: []
      - {}
    servers:
    - url: https://himalayas.app
      description: Production
components:
  schemas:
    Location:
      type: object
      required:
      - alpha2
      - name
      - slug
      properties:
        alpha2:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        name:
          type: string
          description: Full country name
          example: United States
        slug:
          type: string
          description: URL-friendly country identifier
          example: united-states
    JobsResponse:
      type: object
      required:
      - updatedAt
      - offset
      - limit
      - totalCount
      - jobs
      properties:
        comments:
          type: string
          description: Release notes or changelog for the Himalayas API
          example: '21/08/2026: Cursor pagination is now available and is the preferred way to page through the feed. Pass the nextCursor value from each response back as ?cursor=. It is faster than offset and will never return the same job twice. The offset parameter is deprecated and will be removed in a future release. 13/03/2026: The API has been updated to include the companySlug field in the response.'
        updatedAt:
          type: integer
          description: Unix timestamp (seconds) of the most recently updated job in the response
          example: 1740300000
        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.'
          example: MjAyNi0wOC0yMVQwODozODoxNC4xNzc1NTBafDIwNjc2OTc
        offset:
          type: integer
          description: The offset used in this request (deprecated; prefer cursor)
          example: 0
        limit:
          type: integer
          description: The limit used in this request
          example: 20
        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.'
          example: 1250
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
    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
          example: Senior Software Engineer
        excerpt:
          type: string
          description: Short summary of the job (first few sentences of the description)
          example: We are looking for a Senior Software Engineer to join our remote team...
        companyName:
          type: string
          description: Name of the hiring company
          example: Stripe
        companySlug:
          type: string
          description: Canonical company slug for filtering and stable lookups
          example: stripe
        companyLogo:
          type: string
          format: uri
          description: URL of the company logo image
          example: https://ik.imagekit.io/himalayas/stripe-logo.png
        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.
          example: 120000
        maxSalary:
          type:
          - number
          - 'null'
          description: Maximum salary in the pay period specified by salaryPeriod (default annual), in the currency field. Null if not disclosed.
          example: 180000
        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: '#/components/schemas/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.
          example:
          - UTC-5
          - UTC-4
          - UTC-3
        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.
          example:
          - Software Engineering
          - React
          - TypeScript
        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.
          example:
          - Engineering
        description:
          type: string
          description: Full job description as sanitized HTML. Strip HTML tags before summarizing or presenting as plain text.
          example: <p>We are looking for a Senior Software Engineer...</p>
        pubDate:
          type: integer
          description: Unix timestamp (seconds) when the job was last updated
          example: 1740200000
        expiryDate:
          type: integer
          description: Unix timestamp (seconds) of the latest the job stays listed. Jobs can close earlier; check with the single-job endpoint.
          example: 1742800000
        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.
          example: https://stripe.com/careers/senior-engineer
        guid:
          type: string
          description: Unique identifier for the job listing
          example: stripe-senior-software-engineer-abc123
        salaryPeriod:
          type: string
          description: Pay period for minSalary and maxSalary. Defaults to annual for legacy data.
          enum:
          - hourly
          - weekly
          - fortnightly
          - monthly
          - annual
          default: annual
          example: annual
    Error:
      type: object
      properties:
        ok:
          type: boolean
          description: Always false on an error response
          example: false
        errors:
          type: string
          description: Message describing what went wrong
          example: Too many requests. Please try again in a few seconds.
  headers:
    X-RateLimit-Minute-Limit:
      description: Requests allowed per minute for the API key's account. Sent on 429 responses to requests with an API key.
      schema:
        type: integer
    X-RateLimit-Minute-Remaining:
      description: Requests left in the current minute. Sent on 429 responses to requests with an API key.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Requests allowed per UTC day for the API key's account. Sent on 429 responses to requests with an API key.
      schema:
        type: integer
    X-RateLimit-Minute-Reset:
      description: Unix time in seconds when the minute window resets. Sent on 429 responses to requests with an API key.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix time in seconds when the daily window resets. Sent on 429 responses to requests with an API key.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current UTC day. Sent on 429 responses to requests with an API key.
      schema:
        type: integer
  securitySchemes:
    JobsApiKey:
      type: http
      scheme: bearer
      bearerFormat: hml_<secret>
      description: Optional. Requests work without a key; a free key gives higher rate limits (60 per minute, 10,000 per UTC day per account) and usage tracking. Responses served from cache are free and do not count. Server-to-server jobs:read key. Create one at /signup/developer. Never put keys in URLs.
externalDocs:
  description: Full API documentation, code examples, and integration guides for the Himalayas Remote Jobs API
  url: https://himalayas.app/docs/remote-jobs-api
x-refined-from:
- himalayas-app-api-openapi.json
- himalayas-app-openapi.json