CronPulser API

openapi: 3.1.0
info:
  title: CronPulser API
  version: '2026-11-04'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-04: 12 operation(s) read from 6 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; CronPulser has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 9
    pages-with-code: 4
    pages-read: 6
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-04'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://cronpulser.com/docs/api
  - https://cronpulser.com/guides/schedule-api-calls-with-cron
  - https://cronpulser.com/docs/runner
  - https://cronpulser.com/docs/agents
  - https://cronpulser.com/guides/authenticate-cronpulser-requests
  - https://cronpulser.com/guides/how-to-monitor-cron-jobs
servers:
- url: https://api.cronpulser.com
paths:
  /api/v1/jobs:
    get:
      operationId: get_api_v1_jobs
      tags:
      - Api
      summary: GET /api/v1/jobs
      x-source: https://cronpulser.com/docs/api
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1JobsResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl --request GET  --url https://api.cronpulser.com/api/v1/jobs  --header "Authorization: Bearer $CRONPULSER_API_KEY"  --header
          "Accept: application/json" A successful response is a JSON array ordered from newest to oldest. Reference Endpoints Method Path Description
          GET /jobs List jobs. Optionally filter with ?project_id=<uuid>. POST /jobs Create and schedule an HTTP, Runner, or TLS certificate '
  /cronpulser/cronpulser-runner/releases/download/v0.3.5/SHA256SUMS:
    get:
      operationId: get_cronpulser_cronpulser_runner_releases_download_v0_3_5_SHA256SUMS
      tags:
      - Cronpulser
      summary: GET /cronpulser/cronpulser-runner/releases/download/v0.3.5/SHA256SUMS
      x-source: https://cronpulser.com/docs/runner
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl -fsSL https://github.com/cronpulser/cronpulser-runner/releases/download/v0.3.5/SHA256SUMS Step 4 Install and register Run
          the installer for the target operating system, replacing the placeholder with the one-time token. Linux curl -fsSL https://github.com/cronpulser/cronpulser-runner/releases/download/v0.3.5/install-runner.sh
          |  sudo sh -s --  --server https://api.cronpulser.com  --token cp_r
  /internal/jobs/finalize-expired-contracts:
    post:
      operationId: post_internal_jobs_finalize_expired_contracts
      tags:
      - Internal
      summary: Authenticate Incoming CronPulser Requests
      description: Endpoint that processes the scheduled job after verifying the X-CronPulser-Secret header (and optional bearer token). Returns
        401 Unauthorized if the secret does not match, otherwise proceeds with business logic.
      x-source: https://cronpulser.com/guides/authenticate-cronpulser-requests
      parameters:
      - name: X-CronPulser-Secret
        in: header
        required: true
        schema:
          type: string
        description: Job‑specific secret sent by CronPulser; must match the server‑side secret.
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
        description: Bearer token for endpoint credential, if the endpoint uses additional authentication.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /internal/jobs/reconcile-invoices:
    post:
      operationId: post_internal_jobs_reconcile_invoices
      tags:
      - Internal
      summary: 'Step 2: design a narrow endpoint'
      x-source: https://cronpulser.com/guides/schedule-api-calls-with-cron
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostInternalJobsReconcileInvoicesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /jobs:
    get:
      operationId: get_jobs
      tags:
      - Jobs
      summary: List jobs.
      x-source: https://cronpulser.com/docs/api
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          type: string
        description: Optionally filter with ?project_id=<uuid>.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_jobs
      tags:
      - Jobs
      summary: Create and schedule an HTTP, Runner, or TLS certificate job.
      x-source: https://cronpulser.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostJobsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostJobsResponse'
      x-evidence:
        kind: documentation
  /jobs/{id}:
    delete:
      operationId: delete_jobs_id
      tags:
      - Jobs
      summary: Delete the job and unregister its schedule.
      x-source: https://cronpulser.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteJobsIdResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_jobs_id
      tags:
      - Jobs
      summary: Get one job and its computed next run.
      x-source: https://cronpulser.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobsIdResponse'
      x-evidence:
        kind: documentation
    put:
      operationId: put_jobs_id
      tags:
      - Jobs
      summary: Replace the editable job configuration.
      x-source: https://cronpulser.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutJobsIdRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutJobsIdResponse'
      x-evidence:
        kind: documentation
  /jobs/{id}/logs:
    get:
      operationId: get_jobs_id_logs
      tags:
      - Jobs
      summary: List execution history with page and limit parameters.
      x-source: https://cronpulser.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number, default 1.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Results per page, default 20, max 100.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobsIdLogsResponse'
      x-evidence:
        kind: documentation
  /jobs/{id}/logs/{executionid}:
    get:
      operationId: get_jobs_id_logs_executionid
      tags:
      - Jobs
      summary: Get one execution record.
      x-source: https://cronpulser.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: executionid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobsIdLogsExecutionidResponse'
      x-evidence:
        kind: documentation
  /ping/{jobid}:
    get:
      operationId: get_ping_jobid
      tags:
      - Ping
      summary: GET /ping/{jobId}
      x-source: https://cronpulser.com/guides/how-to-monitor-cron-jobs
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -fsS -m 10 --retry 3 https://hb.example.com/ping/JOB_ID \n The URL is illustrative; replace it with your monitor’s private\
          \ ping URL. Set the expected schedule and a grace period in the monitor. If a completion signal is absent, the monitor can alert even\
          \ when the host never started the job. \n Schedule-aware heartbeats cover both C1 and C4. A monitor can independently expect a run at\
          \ a particul"
components:
  schemas:
    GetApiV1JobsResponse:
      type: object
      properties:
        name:
          type: string
    PostInternalJobsReconcileInvoicesRequest:
      type: object
      properties:
        scope:
          type: string
          description: Scope of the reconciliation, e.g., "previous-day"
      required:
      - scope
    GetJobsResponse:
      type: object
      properties:
        jobs:
          type: array
          description: A JSON array ordered from newest to oldest.
    PostJobsRequest:
      type: object
      properties:
        project_id:
          type: string
          description: Project UUID.
        name:
          type: string
          description: Job name.
        cron_schedule:
          type: string
          description: Cron expression (five fields).
        url:
          type: string
          description: Target URL (or hostname for TLS jobs).
        method:
          type: string
          description: HTTP method, default POST.
        headers:
          type: object
          description: Up to 20 header name/value pairs; values are write‑only.
        retry_enabled:
          type: boolean
          description: Enable retry (default depends on method).
        response_log_mode:
          type: string
          description: on_failure, always, or never.
      required:
      - project_id
      - name
      - cron_schedule
      - url
    PostJobsResponse:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        project_id:
          type: string
        name:
          type: string
        cron_schedule:
          type: string
        executor_type:
          type: string
        url:
          type: string
        method:
          type: string
        header_names:
          type: array
          description: List of stored header names.
        retry_enabled:
          type: boolean
        response_log_mode:
          type: string
        is_active:
          type: boolean
        schedule_status:
          type: string
        secret_key:
          type: string
        next_run_at:
          type: string
          description: ISO‑8601 timestamp.
    DeleteJobsIdResponse:
      type: object
      properties:
        status:
          type: string
          description: 202 Accepted if cleanup pending.
    GetJobsIdResponse:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        project_id:
          type: string
        name:
          type: string
        cron_schedule:
          type: string
        executor_type:
          type: string
        url:
          type: string
        method:
          type: string
        header_names:
          type: array
        retry_enabled:
          type: boolean
        response_log_mode:
          type: string
        is_active:
          type: boolean
        schedule_status:
          type: string
        secret_key:
          type: string
        next_run_at:
          type: string
    PutJobsIdRequest:
      type: object
      properties:
        project_id:
          type: string
        name:
          type: string
        cron_schedule:
          type: string
        executor_type:
          type: string
        url:
          type: string
        method:
          type: string
        headers:
          type: object
          description: Full new set of headers; omit to keep existing.
        payload:
          type: object
        retry_enabled:
          type: boolean
        response_log_mode:
          type: string
        is_active:
          type: boolean
          description: Set false to pause, true to resume.
      required:
      - name
      - cron_schedule
      - executor_type
      - url
      - method
    PutJobsIdResponse:
      type: object
      properties:
        id:
          type: string
        schedule_status:
          type: string
        next_run_at:
          type: string
          description: May be null if pending.
    GetJobsIdLogsResponse:
      type: object
      properties:
        logs:
          type: array
          description: Array of execution records.
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    GetJobsIdLogsExecutionidResponse:
      type: object
      properties:
        id:
          type: string
        job_id:
          type: string
        executor_type:
          type: string
        status:
          type: string
        status_code:
          type: integer
        latency_ms:
          type: integer
        response_body:
          type: string
          description: May be null depending on logging mode.
        error_message:
          type: string
          description: May be null.
        error_kind:
          type: string
          description: May be null.
        is_retry:
          type: boolean
        executed_at:
          type: string
          description: ISO‑8601 timestamp.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Cronpulser
- name: Internal
- name: Jobs
- name: Ping