replynodes-com Jobs API

openapi: 3.2.0
info:
  title: ReplyNodes Fetcher Jobs API
  version: v1
  description: 'Read-only data APIs for AI agents. Bearer auth. Prepaid credits / free tier.


    Click **Authorize** and paste ONLY the API key (no "Bearer" prefix) — Swagger adds it automatically.'
servers:
- url: https://api.replynodes.com
security:
- bearerAuth: []
tags:
- name: Jobs
paths:
  /v1/jobs/search:
    get:
      operationId: job_search
      summary: Search Ashby job listings
      description: Search the hash-verified Ashby snapshot using literal filters and source order. Returns up to 10 jobs with the raw provider field omitted. A fresh successful logical search costs 10 credits, including an empty result; errors cost none. Same-identity calls replay the original response while its terminal snapshot is available. Without X-Idempotency-Key, identity is the canonical endpoint and query, so repeating an identical request replays it; send a new X-Idempotency-Key for a fresh logical search.
      tags:
      - Jobs
      parameters:
      - name: query
        in: query
        required: false
        description: Case-insensitive literal substring of the title; empty is a no-op.
        schema:
          type: string
      - name: location
        in: query
        required: false
        description: Case-insensitive literal substring of location; empty is a no-op.
        schema:
          type: string
      - name: company
        in: query
        required: false
        description: Case-insensitive literal substring of company; empty is a no-op.
        schema:
          type: string
      - name: ats
        in: query
        required: false
        description: Ashby only; omitted or ashby selects the Ashby snapshot.
        schema:
          type: string
      - name: remote
        in: query
        required: false
        description: Filter remote state. false matches only explicitly false rows.
        schema:
          type: boolean
      - name: salary_min
        in: query
        required: false
        description: Minimum salary compared with each row salary_max.
        schema:
          type: number
      - name: salary_max
        in: query
        required: false
        description: Maximum salary compared with each row salary_min.
        schema:
          type: number
      - name: experience_max
        in: query
        required: false
        description: Unsupported because the Ashby snapshot has no experience field; any presence is rejected.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum rows, in source order. Defaults to 10; allowed range is 1 through 10.
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 10
      - name: X-Idempotency-Key
        in: header
        required: false
        description: Optional caller-supplied identity for a fresh logical search. Reusing the same key and query replays its terminal response; send a new key to request a fresh search.
        schema:
          type: string
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Successful Ashby search. Each successful fresh logical search costs 10 credits, including an empty result.
          headers:
            X-Request-Id:
              description: Correlation identifier echoed as meta.request_id.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSearchResponse'
        '400':
          description: Invalid or unsupported search input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '401':
          description: Missing or invalid credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '402':
          description: Prepaid credit balance is insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditTopupRequired'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '409':
          description: The same logical search is in progress or its terminal response snapshot is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets.
              schema:
                type: integer
                minimum: 1
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '500':
          description: Gateway error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '502':
          description: Job database or provider error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '503':
          description: Billing or service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
        '504':
          description: Search timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            X-Request-Id:
              description: Correlation identifier returned by the gateway.
              schema:
                type: string
components:
  schemas:
    AnonymousContinuation:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          const: https://replynodes.com/auth.md
    JobSearchRecord:
      type: object
      required:
      - global_id
      - url
      - title
      - company
      - ats_type
      - ats_id
      - location
      - country_iso
      - region
      - lat
      - lon
      - is_remote
      - salary_currency
      - salary_period
      - salary_summary
      - salary_min
      - salary_max
      - employment_type
      - department
      - team
      - requisition_id
      - apply_url
      - commitment
      - description
      - posted_at
      - language
      properties:
        global_id:
          type: string
        url:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        company:
          type:
          - string
          - 'null'
        ats_type:
          type:
          - string
          - 'null'
        ats_id:
          type:
          - string
          - 'null'
        location:
          type:
          - string
          - 'null'
        country_iso:
          type:
          - string
          - 'null'
        region:
          type:
          - string
          - 'null'
        lat:
          type:
          - string
          - 'null'
        lon:
          type:
          - string
          - 'null'
        is_remote:
          type:
          - boolean
          - 'null'
        salary_currency:
          type:
          - string
          - 'null'
        salary_period:
          type:
          - string
          - 'null'
        salary_summary:
          type:
          - string
          - 'null'
        salary_min:
          type:
          - number
          - 'null'
        salary_max:
          type:
          - number
          - 'null'
        employment_type:
          type:
          - string
          - 'null'
        department:
          type:
          - string
          - 'null'
        team:
          type:
          - string
          - 'null'
        requisition_id:
          type:
          - string
          - 'null'
        apply_url:
          type:
          - string
          - 'null'
        commitment:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        posted_at:
          type:
          - string
          - 'null'
        language:
          type:
          - string
          - 'null'
      additionalProperties: false
    JobSearchResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JobSearchRecord'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      additionalProperties: false
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
            retryable:
              type: boolean
            reason:
              type: string
            continuation:
              $ref: '#/components/schemas/AnonymousContinuation'
            status:
              type: integer
            detail:
              type: string
            readme:
              type: string
            next_action:
              $ref: '#/components/schemas/NextAction'
          additionalProperties: false
          required:
          - code
          - message
          - request_id
      additionalProperties: false
      required:
      - error
    NextAction:
      type: object
      description: Typed next step for an agent (ADR 0024). Present only where a next step exists; branch on action, never on message text.
      required:
      - action
      - method
      - url
      - required_fields
      - docs
      properties:
        action:
          type: string
          enum:
          - get_api_key
          - verify_email
          - resend_code
          - renew_key
          - top_up
          - retry_later
          description: Closed set; values may be added, never renamed or removed.
        method:
          type: string
          enum:
          - GET
          - POST
        url:
          type: string
          format: uri
        required_fields:
          type: array
          items:
            type: string
        optional_fields:
          type: array
          items:
            type: string
        human_message:
          type: string
          description: Short sentence the agent can show its human.
        docs:
          type: string
          format: uri
        retry_after_seconds:
          type: integer
          minimum: 1
          description: When the same request may be retried without completing the action.
        auth:
          type: string
          enum:
          - bearer_api_key
          description: Credential the call needs; bearer_api_key means send the same API key as a Bearer token.
      additionalProperties: false
    ResponseMeta:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        contract_version:
          type: string
        generated_at:
          type: string
          format: date-time
        availability:
          type: string
        next_cursor:
          type: string
        missing_fields:
          type: array
          items:
            type: string
        stale:
          type: boolean
      additionalProperties: true
    CreditTopupRequired:
      type: object
      required:
      - code
      - balance_micro
      - price_micro
      - topup_url
      properties:
        code:
          type: string
          enum:
          - topup_required
        balance_micro:
          type: integer
        price_micro:
          type: integer
        topup_url:
          type: string
          format: uri
          description: Owner billing page for managing prepaid credits.
        message:
          type: string
        upgrade:
          type: object
          required:
          - url
          - plans
          - pricing
          properties:
            url:
              type: string
              format: uri
            plans:
              type: array
              items:
                type: object
                required:
                - id
                - url
                properties:
                  id:
                    type: string
                  url:
                    type: string
                    format: uri
                additionalProperties: false
            pricing:
              type: string
              format: uri
          additionalProperties: false
        next_action:
          type: object
          description: 'Typed next step (ADR 0024): only the human can add credits, on the billing page.'
          required:
          - action
          - method
          - url
          - required_fields
          - docs
          properties:
            action:
              type: string
              enum:
              - top_up
            method:
              type: string
              enum:
              - GET
            url:
              type: string
              format: uri
            required_fields:
              type: array
              items:
                type: string
            human_message:
              type: string
            docs:
              type: string
              format: uri
          additionalProperties: false
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rn_test_<64hex> or rn_live_<64hex>
      description: API key. Paste the raw key only (e.g. rn_test_...) — the "Bearer " prefix is added automatically.