openapi: 3.1.0
info:
  title: Nomado24 Jobs API
  version: "1.0.0"
  summary: Free public API for remote & hybrid jobs in Germany and the EU.
  description: >
    Free, unauthenticated REST API for remote and hybrid job listings across
    Germany and the EU, aggregated and deduplicated from multiple sources.
    Every result links to its canonical listing on nomado24.de.
    Free to use with an attribution link back to nomado24.de.
  contact:
    name: Nomado24
    url: https://www.nomado24.de/en/developers
    email: anton.petuchow@nomado24.de
  license:
    name: Free to use with attribution to nomado24.de
    url: https://www.nomado24.de/en/developers
servers:
  - url: https://api.nomado24.de
    description: Production
externalDocs:
  description: API documentation
  url: https://www.nomado24.de/en/developers
paths:
  /api/public/v1/jobs:
    get:
      operationId: listJobs
      summary: List remote and hybrid jobs
      description: >
        Returns a paginated list of remote and hybrid job postings. No
        authentication. Rate limit ~240 requests per 15 minutes per IP. Open CORS.
      parameters:
        - name: page
          in: query
          description: Page number (1-based).
          required: false
          schema: { type: integer, minimum: 1, default: 1 }
        - name: per_page
          in: query
          description: Results per page (clamped to 1..100).
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
        - name: q
          in: query
          description: Free-text search across title, company and tags.
          required: false
          schema: { type: string }
        - name: language
          in: query
          description: Filter by detected job-content language.
          required: false
          schema: { type: string, enum: [de, en, fr] }
      responses:
        "200":
          description: A page of jobs.
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Job" }
                  meta: { $ref: "#/components/schemas/Meta" }
        "404":
          description: API not enabled (dormant gate; returns 200 in production).
components:
  schemas:
    Job:
      type: object
      required: [slug, title, companyName, location, remote, workArrangement, language, tags, source, publishedAt, url]
      properties:
        slug: { type: string }
        title: { type: string }
        companyName: { type: string }
        location: { type: string }
        remote: { type: boolean }
        workArrangement: { type: string, description: "e.g. remote, hybrid" }
        language: { type: string, enum: [de, en, fr] }
        tags:
          type: array
          items: { type: string }
        source: { type: string, description: "Origin feed, e.g. arbeitnow" }
        publishedAt: { type: string, format: date-time }
        url:
          type: string
          format: uri
          description: Canonical nomado24.de listing page (never an external apply URL).
        salaryMin: { type: number, description: "Present only when known." }
        salaryMax: { type: number, description: "Present only when known." }
        currency: { type: string, description: "Present only when salary is known." }
    Meta:
      type: object
      required: [page, perPage, count, attribution, docsUrl, license]
      properties:
        page: { type: integer }
        perPage: { type: integer }
        count: { type: integer }
        attribution: { type: string, example: "Data: Nomado24 (https://www.nomado24.de)" }
        docsUrl: { type: string, format: uri, example: "https://www.nomado24.de/en/developers" }
        license: { type: string, example: "Free to use with an attribution link to nomado24.de" }