Skip to main content
Documentation Powered by Redocly

Dkron REST API (1-oas3)

Download OpenAPI specification:Download

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.

default

status

Gets Status object.

Responses

Response samples

Content type
application/json
{
  • "agent": {
    },
  • "serf": {
    },
  • "tags": {
    }
}

getLeader

List leader of cluster.

Responses

Response samples

Content type
application/json
{
  • "Name": "dkron1",
  • "Addr": "192.168.1.137",
  • "Port": 8946,
  • "Tags": {
    },
  • "Status": 1,
  • "ProtocolMin": 5,
  • "ProtocolMax": 2,
  • "ProtocolCur": 2,
  • "DelegateMin": 0,
  • "DelegateMax": 5,
  • "DelegateCur": 4
}

getIsLeader

Check if node is a leader or follower.

Responses

leave

Force the node to leave the cluster.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

busy

Returns the running executions.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

jobs

getJobs

List jobs.

query Parameters
metadata
Array of strings

Filter jobs by metadata

_sort
string

Sorting field

_order
string

Sort order (ASC/DESC)

q
string

Filter query text

_start
integer

Start index

_end
integer

End index

Responses

Response samples

Content type
application/json
[
  • {
    }
]

createOrUpdateJob

Create or updates a new job.

query Parameters
runoncreate
boolean

If present, regardless of any value, causes the job to be run immediately after being succesfully created or updated.

Request Body schema: application/json

Updated job object

name
required
string

Name for the job. Use only lower case letters (unicode), digits, underscore and dash.

displayname
string

Nice name for the job. Optional.

schedule
required
string

Cron expression for the job.

timezone
string

Timezone where the job will be executed. By default and when field is set to empty string, the job will run in local time.

owner
string

Owner of the job

owner_email
string

Email of the owner

disabled
boolean

Disabled state of the job

object

Target nodes tags of this job

object

Extra metadata tags for this job

retries
integer

Number of times to retry a failed job execution

parent_job
string

The name/id of the job that will trigger the execution of this job

object (processors)

Processor plugins used to process executions results of this job

concurrency
string

Concurrency policy for the job allow/forbid

executor
string

Executor plugin used to run the job

object

Executor plugin parameters

Responses

Request samples

Content type
application/json
{
  • "name": "job1",
  • "displayname": "string",
  • "schedule": "@every 10s",
  • "timezone": "Europe/Berlin",
  • "owner": "Platform Team",
  • "owner_email": "[email protected]",
  • "disabled": true,
  • "tags": {
    },
  • "metadata": {
    },
  • "retries": 2,
  • "parent_job": "parent_job",
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    }
}

Response samples

Content type
application/json
{
  • "name": "job1",
  • "displayname": "string",
  • "schedule": "@every 10s",
  • "timezone": "Europe/Berlin",
  • "owner": "Platform Team",
  • "owner_email": "[email protected]",
  • "success_count": 0,
  • "error_count": 0,
  • "last_success": "2019-08-24T14:15:22Z",
  • "last_error": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "tags": {
    },
  • "metadata": {
    },
  • "retries": 2,
  • "parent_job": "parent_job",
  • "dependent_jobs": [
    ],
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success"
}

showJobByName

Show a job.

path Parameters
job_name
required
string

The job that needs to be fetched.

Responses

Response samples

Content type
application/json
{
  • "name": "job1",
  • "displayname": "string",
  • "schedule": "@every 10s",
  • "timezone": "Europe/Berlin",
  • "owner": "Platform Team",
  • "owner_email": "[email protected]",
  • "success_count": 0,
  • "error_count": 0,
  • "last_success": "2019-08-24T14:15:22Z",
  • "last_error": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "tags": {
    },
  • "metadata": {
    },
  • "retries": 2,
  • "parent_job": "parent_job",
  • "dependent_jobs": [
    ],
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success"
}

runJob

Executes a job.

path Parameters
job_name
required
string

The job that needs to be run.

Responses

Response samples

Content type
application/json
{
  • "name": "job1",
  • "displayname": "string",
  • "schedule": "@every 10s",
  • "timezone": "Europe/Berlin",
  • "owner": "Platform Team",
  • "owner_email": "[email protected]",
  • "success_count": 0,
  • "error_count": 0,
  • "last_success": "2019-08-24T14:15:22Z",
  • "last_error": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "tags": {
    },
  • "metadata": {
    },
  • "retries": 2,
  • "parent_job": "parent_job",
  • "dependent_jobs": [
    ],
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success"
}

deleteJob

Delete a job.

path Parameters
job_name
required
string

The job that needs to be deleted.

Responses

Response samples

Content type
application/json
{
  • "name": "job1",
  • "displayname": "string",
  • "schedule": "@every 10s",
  • "timezone": "Europe/Berlin",
  • "owner": "Platform Team",
  • "owner_email": "[email protected]",
  • "success_count": 0,
  • "error_count": 0,
  • "last_success": "2019-08-24T14:15:22Z",
  • "last_error": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "tags": {
    },
  • "metadata": {
    },
  • "retries": 2,
  • "parent_job": "parent_job",
  • "dependent_jobs": [
    ],
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success"
}

toggleJob

Toggle a job.

path Parameters
job_name
required
string

The job that needs to be toggled.

Responses

Response samples

Content type
application/json
{
  • "name": "job1",
  • "displayname": "string",
  • "schedule": "@every 10s",
  • "timezone": "Europe/Berlin",
  • "owner": "Platform Team",
  • "owner_email": "[email protected]",
  • "success_count": 0,
  • "error_count": 0,
  • "last_success": "2019-08-24T14:15:22Z",
  • "last_error": "2019-08-24T14:15:22Z",
  • "disabled": true,
  • "tags": {
    },
  • "metadata": {
    },
  • "retries": 2,
  • "parent_job": "parent_job",
  • "dependent_jobs": [
    ],
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success"
}

restore

Restore jobs from json file.

Request Body schema: multipart/form-data
file
required
string <binary>

Json file that needs to be restored.

Responses

Response samples

Content type
application/json
[
  • "success create job_1"
]

members

getMember

List members.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

executions

listExecutionsByJob

List executions.

path Parameters
job_name
required
string

The job that owns the executions to be fetched.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

showExecutionByID

Show execution.

path Parameters
job_name
required
string

The job that owns the execution to be fetched.

execution
required
string

The executions to be fetched.

Responses

Response samples

Content type
application/json
{
  • "job_name": "job_1",
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "success": true,
  • "output": "Hello from Dkron",
  • "node_name": "dkron1"
}