Skip to main content
API docs 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.

Authorizations:
TokenAuth

Responses

Response samples

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

getLeader

List leader of cluster.

Authorizations:
TokenAuth

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.

Authorizations:
TokenAuth

Responses

leave

Force the node to leave the cluster.

Authorizations:
TokenAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

busy

Returns the running executions.

Authorizations:
TokenAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

jobs

getJobs

List jobs.

Authorizations:
TokenAuth
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.

Authorizations:
TokenAuth
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
required

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": "dependent_job",
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success",
  • "next": "2019-08-24T14:15:22Z"
}

showJobByName

Show a job.

Authorizations:
TokenAuth
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": "dependent_job",
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success",
  • "next": "2019-08-24T14:15:22Z"
}

runJob

Executes a job.

Authorizations:
TokenAuth
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": "dependent_job",
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success",
  • "next": "2019-08-24T14:15:22Z"
}

deleteJob

Delete a job.

Authorizations:
TokenAuth
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": "dependent_job",
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success",
  • "next": "2019-08-24T14:15:22Z"
}

toggleJob

Toggle a job.

Authorizations:
TokenAuth
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": "dependent_job",
  • "processors": {
    },
  • "concurrency": "allow",
  • "executor": "shell",
  • "executor_config": {
    },
  • "status": "success",
  • "next": "2019-08-24T14:15:22Z"
}

restore

Restore jobs from json file.

Authorizations:
TokenAuth
Request Body schema: multipart/form-data
required
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.

Authorizations:
TokenAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

executions

listExecutionsByJob

List executions.

Authorizations:
TokenAuth
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.

Authorizations:
TokenAuth
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"
}

policies

showPolicyByName

Show a policy.

Authorizations:
TokenAuth
path Parameters
name
required
string

The policy that needs to be fetched.

Responses

Response samples

Content type
application/json
{
  • "Name": "read_all",
  • "Rules": "PolicyJSON"
}

upsertPolicy

Store or updates a policy.

Authorizations:
TokenAuth
path Parameters
name
required
string

The policy name to store.

Responses

Response samples

Content type
application/json
{
  • "Name": "read_all",
  • "Rules": "PolicyJSON"
}

deletePolicy

Delete a policy.

Authorizations:
TokenAuth
path Parameters
name
required
string

The policy that needs to be deleted.

Responses

Response samples

Content type
application/json
{
  • "Name": "read_all",
  • "Rules": "PolicyJSON"
}