---
openapi: 3.1.0
info:
  title: Dkron REST API
  description: |
    You can communicate with Dkron using a RESTful JSON API over HTTP. Dkron nodes usually listen on port `8080` for API requests. All examples in this section assume that you've found a running leader at `localhost:8080`.

    Dkron implements a RESTful JSON API over HTTP to communicate with software clients. Dkron listens in port `8080` by default. All examples in this section assume that you're using the default port.

    Default API responses are unformatted JSON add the `pretty=true` param to format the response.
  version: 1-oas3
servers:
  - url: http://localhost:8080/v1

paths:
  /:
    get:
      tags:
        - default
      description: |
        Gets `Status` object.
      operationId: status
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
  /jobs:
    get:
      tags:
        - jobs
      description: |
        List jobs.
      operationId: getJobs
      parameters:
        - name: metadata
          in: query
          description: Filter jobs by metadata
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: _sort
          in: query
          description: Sorting field
          required: false
          style: form
          explode: true
          schema:
            type: string
        - name: _order
          in: query
          description: Sort order (ASC/DESC)
          required: false
          style: form
          explode: true
          schema:
            type: string
        - name: q
          in: query
          description: Filter query text
          required: false
          style: form
          explode: true
          schema:
            type: string
        - name: _start
          in: query
          description: Start index
          required: false
          style: form
          explode: true
          schema:
            type: integer
        - name: _end
          in: query
          description: End index
          required: false
          style: form
          explode: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/job'
        "500":
          description: Internal error

    post:
      tags:
        - jobs
      description: |
        Create or updates a new job.
      operationId: createOrUpdateJob
      parameters:
        - name: runoncreate
          in: query
          description: If present, regardless of any value, causes the job to be run immediately after being succesfully created or updated.
          required: false
          allowEmptyValue: true
          style: form
          explode: true
          schema:
            type: boolean
      requestBody:
        description: Updated job object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/job'
        required: true
      responses:
        "201":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
        "400":
          description: Bad request, the job is invalid
          content:
            text/plain:
              schema:
                type: string
                examples:
                  - "Bad request, the job is invalid. Please check the job definition."
        "500":
          description: Internal error
          content:
            text/plain:
              schema:
                type: string
                examples:
                  - "Internal error, please try again later."

    patch:
      tags:
        - jobs
      description: |
        Create or updates a new job.
      operationId: createOrUpdateJobPatch
      parameters:
        - name: runoncreate
          in: query
          description: If present, regardless of any value, causes the job to be run immediately after being succesfully created or updated.
          required: false
          allowEmptyValue: true
          style: form
          explode: true
          schema:
            type: boolean
      requestBody:
        description: Updated job object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/job'
        required: true
      responses:
        "201":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
        "400":
          description: Bad request, the job is invalid
          content:
            text/plain:
              schema:
                type: string
                examples:
                  - "Internal error, please try again later."
        "500":
          description: Internal error
          content:
            text/plain:
              schema:
                type: string
                examples:
                  - "Internal error, please try again later."

  /jobs/{job_name}:
    get:
      tags:
        - jobs
      description: |
        Show a job.
      operationId: showJobByName
      parameters:
        - name: job_name
          in: path
          description: The job that needs to be fetched.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
    post:
      tags:
        - jobs
      description: |
        Executes a job.
      operationId: runJob
      parameters:
        - name: job_name
          in: path
          description: The job that needs to be run.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "202":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
    delete:
      tags:
        - jobs
      description: |
        Delete a job.
      operationId: deleteJob
      parameters:
        - name: job_name
          in: path
          description: The job that needs to be deleted.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
  /jobs/{job_name}/toggle:
    post:
      tags:
        - jobs
      description: |
        Toggle a job.
      operationId: toggleJob
      parameters:
        - name: job_name
          in: path
          description: The job that needs to be toggled.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
  /restore:
    post:
      tags:
        - jobs
      description: |
        Restore jobs from json file.
      operationId: restore
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/restore_body'
        required: true
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/restore'
  /members:
    get:
      tags:
        - members
      description: |
        List members.
      operationId: getMember
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/member'
  /leader:
    get:
      tags:
        - default
      description: |
        List leader of cluster.
      operationId: getLeader
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/member'
  /isleader:
    get:
      tags:
        - default
      description: |
        Check if node is a leader or follower.
      operationId: getIsLeader
      responses:
        "200":
          description: Node is a leader
        "404":
          description: Node is a follower
  /leave:
    post:
      tags:
        - default
      description: |
        Force the node to leave the cluster.
      operationId: leave
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/member'
  /jobs/{job_name}/executions:
    get:
      tags:
        - executions
      description: |
        List executions.
      operationId: listExecutionsByJob
      parameters:
        - name: job_name
          in: path
          description: The job that owns the executions to be fetched.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/execution'
    delete:
      tags:
        - executions
      description: |
        Delete all executions for a job and reset counters (success_count, error_count, last_success, last_error).
      operationId: deleteExecutionsByJob
      parameters:
        - name: job_name
          in: path
          description: The job whose executions should be deleted.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response - returns the updated job with reset counters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
        "404":
          description: Job not found
        "500":
          description: Internal server error
  /jobs/{job_name}/executions/{execution}:
    get:
      tags:
        - executions
      description: |
        Show execution.
      operationId: showExecutionByID
      parameters:
        - name: job_name
          in: path
          description: The job that owns the execution to be fetched.
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: execution
          in: path
          description: The executions to be fetched.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/execution'
  /busy:
    get:
      tags:
        - default
      description: |
        Returns the running executions.
      operationId: busy
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/execution'

  /pause:
    get:
      tags:
        - default
      description: |
        Returns the current pause status for new job submissions.
      operationId: pauseStatus
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  paused:
                    type: boolean
                    description: Whether new job submissions are currently paused
    post:
      tags:
        - default
      description: |
        Pauses new job submissions. Existing jobs continue to run, but no new jobs can be created or updated.
      operationId: pause
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  paused:
                    type: boolean
                    description: Whether new job submissions are currently paused

  /unpause:
    post:
      tags:
        - default
      description: |
        Resumes new job submissions after being paused.
      operationId: unpause
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  paused:
                    type: boolean
                    description: Whether new job submissions are currently paused

  /stats:
    get:
      tags:
        - statistics
      description: |
        Retrieves execution statistics for a specified number of days.
      operationId: getExecutionStats
      parameters:
        - name: days
          in: query
          description: "Number of days of statistics to retrieve (default: 30, max: 365)"
          required: false
          style: form
          explode: true
          schema:
            type: integer
            default: 30
            minimum: 1
            maximum: 365
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/execution_stats'
        "500":
          description: Internal error

  /acl/policies/{name}:
    get:
      tags:
        - policies
      description: |
        Show a policy.
      operationId: showPolicyByName
      parameters:
        - name: name
          in: path
          description: The policy that needs to be fetched.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policy'
    post:
      tags:
        - policies
      description: |
        Store or updates a policy.
      operationId: upsertPolicy
      parameters:
        - name: name
          in: path
          description: The policy name to store.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "202":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policy'
    delete:
      tags:
        - policies
      description: |
        Delete a policy.
      operationId: deletePolicy
      parameters:
        - name: name
          in: path
          description: The policy that needs to be deleted.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policy'
components:
  schemas:
    status:
      type: object
      properties:
        agent:
          type: object
          additionalProperties:
            type: object
          description: Node basic details
          readOnly: true
        serf:
          type: object
          additionalProperties:
            type: object
          description: Serf status
          readOnly: true
        tags:
          type: object
          additionalProperties:
            type: string
          description: Tags asociated with this node
          readOnly: true
      description: Status represents details about the node.
      readOnly: true
    job:
      required:
        - name
        - schedule
      type: object
      x-go-type: types.Job
      x-go-imports:
        - path: github.com/distribworks/dkron/v4/types
      properties:
        name:
          type: string
          description: Name for the job. Use only lower case letters (unicode), digits, underscore and dash.
          readOnly: false
          examples:
            - job1
        displayname:
          type: string
          description: Nice name for the job. Optional.
          readOnly: false
        schedule:
          type: string
          description: Cron expression for the job.
          readOnly: false
          examples:
            - '@every 10s'
        timezone:
          type: string
          description: Timezone where the job will be executed. By default and when field is set to empty string, the job will run in local time.
          readOnly: false
          examples:
            - Europe/Berlin
        owner:
          type: string
          description: Owner of the job
          readOnly: false
          examples:
            - Platform Team
        owner_email:
          type: string
          description: Email of the owner
          readOnly: false
          examples:
            - platform@example.com
        success_count:
          type: integer
          description: Number of successful executions
          readOnly: true
        error_count:
          type: integer
          description: Number of failed executions
          readOnly: true
        last_success:
          type: string
          description: Last time this job executed successfully
          format: date-time
          readOnly: true
        last_error:
          type: string
          description: Last time this job failed
          format: date-time
          readOnly: true
        disabled:
          type: boolean
          description: Disabled state of the job
          readOnly: false
        tags:
          type: object
          additionalProperties:
            type: string
          description: Target nodes tags of this job
          readOnly: false
          examples:
            - server: "true"
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Extra metadata tags for this job
          readOnly: false
          examples:
            - office: Barcelona
        retries:
          type: integer
          description: Number of times to retry a failed job execution
          readOnly: false
          examples:
            - 2
        parent_job:
          type: string
          description: The name/id of the job that will trigger the execution of this job
          readOnly: false
          examples:
            - parent_job
        dependent_jobs:
          type: array
          description: Array containing the jobs that depends on this one
          readOnly: true
          examples:
            - dependent_job
          items:
            type: string
        processors:
          $ref: '#/components/schemas/processors'
        concurrency:
          type: string
          description: Concurrency policy for the job allow/forbid
          readOnly: false
          examples:
            - allow
        executor:
          type: string
          description: Executor plugin used to run the job
          readOnly: false
          examples:
            - shell
        executor_config:
          type: object
          additionalProperties:
            type: string
          description: Executor plugin parameters
          examples:
            - command: echo 'Hello from Dkron'
        status:
          type: string
          description: Status of the job
          readOnly: true
          examples:
            - success
        next:
          type: string
          description: Next execution time
          readOnly: true
          format: date-time
        starts_at:
          type: string
          description: Job start time
          readOnly: false
          format: date-time
        expires_at:
          type: string
          description: Job expiration time
          readOnly: false
          format: date-time
      description: A Job represents a scheduled task to execute.
    member:
      type: object
      x-go-type: types.Member
      x-go-imports:
        - path: github.com/distribworks/dkron/v4/types
      properties:
        Name:
          type: string
          description: Node name
          examples:
            - dkron1
        Addr:
          type: string
          description: IP Address
          examples:
            - 192.168.1.137
        Port:
          type: integer
          description: Port number
          examples:
            - 8946
        Tags:
          type: object
          additionalProperties:
            type: string
          description: Tags asociated with this node
          examples:
            - rpc_addr: 192.168.1.137:6868
              server: "true"
              version": 1.0.0
        Status:
          type: integer
          description: 'The serf status of the node see: https://godoc.org/github.com/hashicorp/serf/serf#MemberStatus'
          examples:
            - 1
        ProtocolMin:
          type: integer
          description: Serf protocol minimum version this node can understand or speak
          examples:
            - 5
        ProtocolMax:
          type: integer
          description: Serf protocol maximum version this node can understand or speak
          examples:
            - 2
        ProtocolCur:
          type: integer
          description: Serf protocol current version this node can understand or speak
          examples:
            - 2
        DelegateMin:
          type: integer
          description: Serf delegate protocol minimum version this node can understand or speak
        DelegateMax:
          type: integer
          description: Serf delegate protocol maximum version this node can understand or speak
          examples:
            - 5
        DelegateCur:
          type: integer
          description: Serf delegate protocol current version this node can understand or speak
          examples:
            - 4
      description: A member represents a cluster member node.
    execution:
      type: object
      x-go-type: types.Execution
      x-go-imports:
        - path: github.com/distribworks/dkron/v4/types
      properties:
        job_name:
          type: string
          description: job name
          examples:
            - job_1
        started_at:
          type: string
          description: start time of the execution
          format: date-time
        finished_at:
          type: string
          description: when the execution finished running
          format: date-time
        success:
          type: boolean
          description: the execution run successfuly
        output:
          type: string
          description: partial output of the command execution
          examples:
            - Hello from Dkron
        node_name:
          type: string
          description: name of the node that executed the command
          examples:
            - dkron1
      description: An execution represents a timed job run.
    processors:
      type: object
      additionalProperties:
        type: object
        additionalProperties:
          type: string
      description: Processor plugins used to process executions results of this job
      examples:
        - files:
            forward: true
    restore:
      type: string
      description: Each job restore result.
      examples:
        - success create job_1
    restore_body:
      required:
        - file
      type: object
      properties:
        file:
          type: string
          description: Json file that needs to be restored.
          format: binary
    policy:
      type: object
      x-go-type: types.Policy
      x-go-imports:
        - path: github.com/distribworks/dkron/v4/types
      properties:
        Name:
          type: string
          description: Policy name
          examples:
            - read_all
        Rules:
          type: string
          description: Policy rules
          examples:
            - PolicyJSON
    execution_stat:
      type: object
      description: Execution statistics for a specific date
      properties:
        date:
          type: string
          format: date-time
          description: The date for which this statistic is recorded (truncated to day)
          examples:
            - "2026-01-28T00:00:00Z"
        success_count:
          type: integer
          description: Number of successful executions on this date
          examples:
            - 42
        failed_count:
          type: integer
          description: Number of failed executions on this date
          examples:
            - 3
    execution_stats:
      type: object
      description: Collection of execution statistics over a time period
      properties:
        stats:
          type: array
          description: Array of daily execution statistics
          items:
            $ref: '#/components/schemas/execution_stat'
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: X-Dkron-Token

security:
  - TokenAuth: [ ]