Command endpoints

Use the command endpoints to run Puppet, jobs, and plans on demand or stop in-progress jobs. You can also create task-targets, which provide privilege escalation for users who would otherwise not be able to run certain tasks or run tasks on certain nodes or node groups.

You can:

The schedule_deploy, schedule_task, and schedule_plan endpoints are deprecated. Instead, use POST /scheduled_jobs/environment_jobs.

POST /command/deploy

Run Puppet on demand – run the orchestrator across all nodes in an environment.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using keys described in the following table. The environment key is always required. Additional keys might be required depending on the values of other keys.
Key Format Definition
environment String Required: The name of the environment to deploy or an empty string. If you supply an empty string, you must set enforce_environment to false.
scope JSON object Contains exactly one key defining the deployment target:
  • nodes: A list of node names to target.
  • query: A PuppetDB or PQL query to use to discover nodes. The target is built from certname values collected at the top level of the query.
  • node_group: The ID of a classifier node group that has defined rules. The node group itself must have defined rules – It is not sufficient for only the node group's parent groups to define rules. The user submitting the request must also have permissions to view the specified node group.

Required if environment is an empty string.

concurrency Integer or range The maximum number of nodes to run at one time. The default is a range between 1 and the value of the global_concurrent_compiles parameter.

For information about global_concurrent_compiles, refer to Orchestrator and pe-orchestration-services parameters.

debug Boolean Whether to use the --debug flag on Puppet agent runs.
description String A description of the job.
enforce_environment Boolean Whether to force agents to run in the specified environment. This key must be false if environment is an empty string.
evaltrace Boolean Whether to use the --evaltrace flag on Puppet agent runs.
filetimeout Integer The value for the --filetimeout flag on Puppet agent runs.
http_connect_timeout Integer The value for the --http_connect_timeout flag on Puppet agent runs.
http_keepalive_timeout Integer The value for the --http_keepalive_timeout flag on Puppet agent runs.
http_read_timeout Integer The value for the --http_read_timeout flag on Puppet agent runs.
noop Boolean Whether to run the agent in no-op mode. The default is false.
no_noop Boolean Whether to run the agent in enforcement mode. The default is false. This flag overrides noop = true if set in the agent's puppet.conf file. This flag can't be set to true if the noop flag is also set to true.
ordering String Sets the --ordering flag on Puppet agent runs.
skip_tags String Sets the --skip_tags flag on Puppet agent runs.
tags String Sets the --tags flag on Puppet agent runs.
trace Boolean Whether to use the --trace flag on Puppet agent runs.
use_cached_catalog Boolean Whether to use the --use_cached_catalog flag on Puppet agent runs.
usecacheonfailure Boolean Whether to use the --usecacheonfailure flag on Puppet agent runs.
userdata JSON object Arbitrary key/value data supplied to the job.
Here is an example of a complete curl command for the /command/deploy endpoint. This request targets nodes in the All Nodes node group in the production environment:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/deploy"
data='{"environment": "production", "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

The following are additional examples of valid JSON bodies for the /command/deploy endpoint.

This body deploys two specific nodes in the production environment:
{
  "environment" : "production",
  "scope" : {
    "nodes" : ["node1.example.com", "node2.example.com"]
  }
}
This body deploys the node1.example.com node in no-op mode:
{
  "environment" : "",
  "enforce_environment": false,
  "noop" : true,
  "scope" : {
    "nodes" : ["node1.example.com"]
  },
  "userdata": {
    "servicenow_ticket": "INC0011211"
  }
}
This body deploys any node in the production environment with a certname value matching a regex:
{
  "environment" : "production",
  "scope" : {
    "query" : ["from", "nodes", ["~", "certname", ".*"]]
  }
}

Response format

If all node runs succeed and the environment is successfully deployed, the server returns 202 and a JSON object using these keys:
  • id: An absolute URL that links to the newly created job.
  • name: A stringified number identifying the newly created job. You can use this with other endpoints, such as GET /jobs/<job-id> (retrieve information about the status of the job) and POST /command/stop.
For example:
{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
    "name" : "81"
  }
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:
Response code Value Definition
404 puppetlabs.orchestrator/unknown-environment The specified environment does not exist.
400 puppetlabs.orchestrator/empty-environment The specified environment contains no applications or no nodes.
400 puppetlabs.orchestrator/empty-target The specified scope resolves to an empty list of nodes.
400 puppetlabs.orchestrator/puppetdb-error If the request specified a query for the scope, the orchestrator is unable to make a query to PuppetDB.
400 puppetlabs.orchestrator/query-error If the request specified a query for the scope, the query is invalid or the user submitting the request does not have permission to run the query.

POST /command/stop

Stop an orchestrator job that is currently in progress.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object containing the job key, which specifies the job ID of the job to stop, such as:
{
  "job": "1234"
}
Job IDs are returned in responses from POST /command/deploy and GET /jobs.

By default, this request halts the specified job. This prevents the job from starting new Puppet agent runs but allows any in-progress runs to finish. While in-progress runs are finishing, the server continues to produce events for the job. The job's status changes to stopped once all in-progress runs finish.

Tip: If you want to completely stop the job (to stop in-progress runs and prevent new runs from starting), add the force key to the request, such as:
{
  "job": "1234"
  "force": true
}
You can force, for example, to stop a task that is hanging. Be aware that force immediately ends the job. This can result in an inconsistent or undesirable state due to job components (tasks, plans, Puppet runs, and so on) being ended prematurely.
Here is an example of a complete curl command:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/stop"
data='{"job": "1234"}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

POST /command/stop is idempotent – you can use it against the same job any number of times.

Response format

If the job is stopped successfully, the server returns a 202 response and a JSON object containing these keys:
  • id: An absolute URL that links to the stopped job. This is based on the job key in the request.
  • name: A stringified number identifying the stopped job.
  • nodes: A hash showing all possible node statuses, and how many nodes are currently in each status.
For example:
{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
    "name" : "1234",
    "nodes" : {
      "new" : 5,
      "running" : 8,
      "failed"  : 3,
      "errored" : 1,
      "skipped" : 2,
      "finished": 5
    }
  }
}
Important: When a job is successfully stopped, any in-progress Puppet agent runs finish, but no new agent runs start. While agents are finishing, the server continues to produce events for the job, and the job itself transitions to stopped status when all in-progress agent runs have finished.

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:
Response code Key Definition
400 puppetlabs.orchestrator/validation-error The specified job ID is not formatted correctly or is otherwise not valid.
404 puppetlabs.orchestrator/unknown-job The specified job ID does not exist.

POST /command/stop_plan

Stop an orchestrator plan job that is currently in progress.

This command interrupts the thread that is running the plan.

If the plan doesn't have code to explicitly handle the interrupt, the plan finishes with an error. If the plan can handle the interrupt, whether or not the plan stops depends on the plan's interruption handling.

If the plan is running a task (or otherwise) when interrupted, an error occurs and the plan stops, but the underlying in-progress task job finishes. If you need to force stop an in-progress job, use POST /command/stop.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object containing the plan_job key, which specifies the string-formatted ID of the plan job to stop, such as:
{
  "plan_job": "1234"
}
The plan_job ID is the name value that is returned from POST /command/plan_run and GET /plan_jobs.
Here is an example of a complete curl command:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/stop_plan"
data='{"plan_job": "1234"}'

curl --insecure --header "$type_header" --header "$auth_header" -X POST "$uri" --data "$data"

POST /command/stop_plan is idempotent – you can use it against the same plan job any number of times.

Response format

If the specified plan job exists, the server returns a 202 response containing the name key, which is the same as the plan_job key in the request. For example:
{
  "name": "1234"
}
Important:

If the plan is running a task (or otherwise) when interrupted, the plan stops, but the underlying in-progress task job finishes. If you need to force stop an in-progress job, use POST /command/stop.

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:
Response code Key Definition
400 puppetlabs.orchestrator/validation-error The specified plan job ID is not formatted correctly or is otherwise not valid.
404 puppetlabs.orchestrator/unknown-job The specified plan job ID does not exist.

POST /command/task

Run a task on a set of nodes. The task does not run on any nodes in the defined scope that you do not have permission to run tasks on.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using keys described in the following table. Most keys are required, some keys are optional, and some required keys can be empty.

Key Format Definition
environment String Required: The name of the environment to load the task from. The default is production.
scope JSON object Required: Contains exactly one key defining the nodes to run the task on:
  • nodes: An array of node names to target.
  • query: A PuppetDB or PQL query to use to discover nodes. The target is built from certname values collected at the top level of the query.
  • node_group: The ID of a classifier node group that has defined rules. The node group itself must have defined rules – It is not sufficient for only the node group's parent groups to define rules. The user submitting the request must also have permissions to view the specified node group.
The task does not run on any nodes specified in the scope that the user does not have permission to run the task on.
description String A optional description of the job.
noop Boolean Whether to run the job in no-op mode. The default is false.
params JSON object Required: Parameters to pass to the task. Can be an empty object.
targets Array of JSON objects Required: A collection of keys used to run the task on nodes through SSH or WinRM via Bolt server, such as user account information, run-as specifications, or a designated temporary directory. Refer to the Targets section, below, for information about optional and required keys to use in targets.
task String Required: The task to run on the target nodes. Use the GET /tasks endpoint to get task names.
timeout Integer The maximum number of seconds a task can take to execute on any individual node. Task execution on a node is forcibly ended if the timeout limit is reached. If unspecified, this key takes the value of default-task-node-timeout, which is one of the Orchestrator and pe-orchestration-services parameters.
userdata JSON object Optional arbitrary key/value data supplied to the job.
For example, this body runs the package task on the node1.example.com node in the test-env-1 environment. It passes action and name parameters to the task.
{
  "environment" : "test-env-1",
  "task" : "package",
  "params" : {
    "action" : "install",
    "name" : "httpd"
  },
  "scope" : {
    "nodes" : ["node1.example.com"]
  }
}
A complete curl request using this body might look like:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/task"
data='{"environment": "test-env-1", "task" : "package", "params" : { "action": "install", "name" : "httpd" }, "scope" : { "nodes" : ["node1.example.com"] }}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

For additional scope examples, refer to the POST /command/deploy request format examples.

Targets

The targets key contains an array of JSON objects, where each object contains the following keys:
Key Format Definition
hostnames Array Required: An array of hostnames sharing the same target attributes. Each hostname must match an entry in the tasks' node list scope.
user String Required: Specify the user on the remote system to use to run the task.
transport String Required: Specify ssh or winrm.
password String Conditionally required: Specify the password associated with the user key. You must specify either this key or private-key-content.
private-key-content String Conditionally required: Specify the content of the SSH key used to ssh to the remote node to run on. You must specify either this key or password.
port Integer Specifies the port, on the remote node, to use to connect.
run-as String When using SSH, specify an optional user to use to run commands.
sudo-password String If you specify run-as, specify a password to use when changing users.
run-as-command String If you specify run-as, specify a command to use to elevate permissions.
connect-timeout Integer How long, in seconds, you want Bolt to wait when establishing connections.
tty Boolean Whether Bolt uses pseudo tty to meet sudoer restrictions.
tmpdir String Specify the directory the task can use to upload and execute temporary files on the target.
extensions String A list of file extensions that are accepted for scripts or tasks.
For example, this target array contains two JSON objects:
[
  {
    "hostnames": ["sshnode1.example.com", "sshnode2.example.com"],
    "private-key-content": "<SSH_KEY>",
    "port": 4444,
    "user": "<USER_NAME>",
    "transport": "ssh"
  },
  {
    "hostnames": ["winrmnode.example.com"],
    "password": "<PASSWORD>",
    "port": 4444,
    "user": "<USER_NAME>",
    "transport": "winrm"
  }
]

Response format

If the task starts successfully, the server returns 202 and a JSON object using these keys:
  • id: An absolute URL that links to the newly created job. You can use it with the GET /jobs/<job-id> endpoint to retrieve information about the status of the job.
  • name: A stringified number identifying the newly created job.
For example:
{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
    "name" : "81"
  }
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:

Response code Value Definition
404 puppetlabs.orchestrator/unknown-environment The specified environment does not exist.
400 puppetlabs.orchestrator/empty-target There is a problem with the target entry in the request body, such as the hostnamesdo not match nodes defined by the scope.
400 puppetlabs.orchestrator/puppetdb-error If the request specified a query for the scope, the orchestrator is unable to make a query to PuppetDB.
400 puppetlabs.orchestrator/query-error If the request specified a query for the scope, the query is invalid or the user submitting the request does not have permission to run the query.
403 puppetlabs.orchestrator/not-permitted This error occurs when a user does not have permission to run the task on the requested nodes.

POST /command/task_target

Create a task-target, which is a set of tasks and nodes/node groups you can use to provide specific privilege escalation for users who would otherwise not be able to run certain tasks or run tasks on certain nodes or node groups. When you grant a user permission to use a task-target, the user can run the task(s) in the task-target on the set of nodes defined in the task-target.

Important: After using the POST /command/task_target endpoint to create a task-target, you must use the POST /roles endpoint to create a role controlling the permission to use the task-target. For an overview of the task-target workflow, read about Puppet Enterprise RBAC API, or how to manage access to tasks on the Puppet blog.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using these keys:
Key Format Definition
display_name String Required: The task-target name. There are no uniqueness requirements.
tasks Array of strings Conditionally required: You must specify either tasks or all_tasks.

If you want to include specific tasks in the task-target, use tasks to supply an array of relevant task names. This key can be empty. If tasks is omitted or empty, you must set all_tasks to true. This key is required if all_tasks is omitted.

Important: The endpoint does not check if the specified tasks correspond to existing tasks. This means you can create task-targets that include tasks you have not yet created, and that you must manually confirm the task names are spelled correctly.
all_tasks Boolean Conditionally required: You must specify either tasks or all_tasks.
all_tasks indicates whether any tasks can be run on designated node targets. The default is false and expects you to define specific tasks in the tasks key. However:
  • If tasks is omitted or empty, you must set all_tasks to true.
  • If all_tasks is omitted, you must provide a valid tasks key.
  • If all_tasks is true, omit tasks. If you specify tasks and set all_tasks to true, the endpoint ignores tasks and takes the all_tasks value.
nodes Array of strings Required: Use nodes, node_groups, and pql_query to identify nodes users can run tasks against when using this task-target. The endpoint combines these keys to form a total node pool. If you specified tasks, the user can run only those specific tasks against the specified nodes.

nodes must be either empty array or an array of certnames identifying specific agent nodes or agentless nodes to associate with this task-target.

Important: The endpoint does not check if the nodes certnames correspond to existing nodes. This means you can create task-targets that include individual nodes you have not yet configured, and that you must manually confirm the node certnames are specified correctly.
node_groups Array of strings Required: Use nodes, node_groups, and pql_query to identify nodes users can run tasks against when using this task-target. The endpoint combines these keys to form a total node pool. If you specified tasks, the user can run only those specific tasks against the specified nodes.

node_groups must be either an empty array or an array of node group IDs describing node groups associated with this task-target.

pql_query String Use nodes, node_groups, and pql_query to identify nodes users can run tasks against when using this task-target. The endpoint combines these keys to form a total node pool. If you specified tasks, the user can run only those specific tasks against the specified nodes.

pql_query is an optional string specifying a single PQL query to use to fetch nodes for this task-target. Query results must contain the certnames key to identify the nodes.

Important: While pql_query is optional, if you only use pql_query to define the nodes in the task-target, you must supply nodes and node_groups as empty arrays.
For example, this body creates a task target that allows users to run task_1 and task_2 on node1, node2, and all nodes a specific node group.
{
  "display_name": "task_target_example_1",
  "tasks": ["task_1", "task_2"],
  "nodes": ["node1" "node2"],
  "node_groups": ["00000000-0000-4000-8000-000000000000"]
}
This body allows users to run any task against node1 and node2.
{
  "display_name": "task_target_example_2",
  "all_tasks": "true",
  "nodes": ["node1" "node2"],
  "node_groups": []
}
A complete curl request for the command/task_target endpoint might look like:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/task_target"
data='{"display_name": "task_target_example_2", "all_tasks": "true", "nodes": ["node1" "node2"], "node_groups": []}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

If the task-target is successfully created, the server returns a 200 response and a JSON object using these keys:
  • id: An absolute URL that links to the task-target. You can use it with the GET /scopes/task_targets/<task-target-id> endpoint to retrieve information about the task-target.
  • name: The task-target's unique identifier.
For example:
{
  "task_target": {
    "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1",
    "name": "1"
  }
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. There are several reasons this endpoint might return a 400 puppetlabs.orchetrator/validation-error response, including:
  • display_name is missing or empty.
  • tasks is missing or empty when all_tasks is false or omitted.
  • Task names in tasks are not supplied as strings.
  • If all_tasks is defined, the value is not a Boolean.
  • tasks is missing or empty and all_tasks is not true.
  • Node names in nodes are not supplied as strings.
  • Node group IDs in node_groups are not supplied as strings.
  • The value of pql_query is not a string.

POST /command/plan_run

Use the plan executor to run a plan.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using these keys:
Key Format Definition
plan_name String Required: The name of the plan to run.
Tip: Use the GET /plans endpoint to find plan names.
params JSON object The parameters you want the plan to use.
environment String The environment to load the plan from. The default is production.
description String A description of the job.
timeout Integer The maximum number of seconds allowed for the plan to run. Reaching the timeout limit cancels queued plan actions and attempts to interrupt in-progress actions. If unspecified, this key takes the value of default-plan-timeout, which is one of the Orchestrator and pe-orchestration-services parameters.
userdata JSON object Arbitrary key/value data supplied to the job.
For example, this body starts the canary plan on two specific nodes:
{
  "plan_name" : "canary",
  "description" : "Start the canary plan on node1 and node2",
  "params" : {
    "nodes" : ["node1.example.com", "node2.example.com"],
    "command" : "whoami",
    "canary" : 1
  }
}
A complete curl request using this body might look like:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/plan_run"
data='{"plan_name" : "canary", "description" : "Start the canary plan on node1 and node2", "params" : { "nodes" : ["node1.example.com", "node2.example.com"], "command" : "whoami", "canary" : 1}}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

If the plan starts successfully, the server returns 202 and a JSON object containing the name of the newly created plan job. For example:
{
  "name" : "1234"
}

If you need to stop this plan while it is running, use the name ID with POST /command/stop_plan.

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:
Response code Key Description
400 puppetlabs.orchestrator/validation-error The plan_name is not valid. Most likely, it is not a properly-formatted string.
403 puppetlabs.orchestrator/not-permitted This error occurs when a user does not have permission to run the plan, cannot run the plan on the specified nodes, or otherwise lacks permission to complete the request.

POST /command/environment_plan_run

Use parameters to run a plan on specific nodes in a specific environment.

Request format

This endpoint is similar to the POST /command/plan_run endpoint. You must define nodes to run the plan on by supplying parameters in your request.

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using these keys:
Key Format Definition
plan_name String Required: The name of the plan to run.
Tip: Use the GET /plans endpoint to find plan names.
params JSON object containing objects Required: The parameters you want the plan to use. Use the type key to identify whether a parameter is a query or a node group.
environment String The environment to load the plan from. The default is production.
description String A description of the job.
timeout Integer The maximum number of seconds allowed for the plan to run. Reaching the timeout limit cancels queued plan actions and attempts to interrupt in-progress actions. If unspecified, this key takes the value of default-plan-timeout, which is one of the Orchestrator and pe-orchestration-services parameters.
userdata JSON object Arbitrary key/value data supplied to the job.
For example, this body runs the example_plan on nodes specified in the targets and more_targets parameters:
{
  "plan_name" : "example_plan",
  "description" : "Output 'message' on the targets contained in 'targets' and 'more targets'",
  "params": {
    "message": {
      "value": "hello"
    },
    "example_object_param": {
       "value": {
         "value": "xyz"
       }
    },
    "targets": {
      "type": "query",
      "value": "nodes[certname] { }"
    },
    "more_targets": {
      "type": "node_group",
      "value": "<UUID>"
    }
  }
}

In this example, the parameters follow the format {<PARAM_NAME>: {"value": "<PARAM_VALUE>"}}, such as {"message": {"value": "hello"}}. The orchestrator passes <PARAM_VALUE> to the plan as the parameter's value. For object parameters, such as example_object_param, the object {"value": "xyz"} is passed to the plan as the value for example_object_param.

You can use the optional type key to give the orchestrator additional information about the parameter. This tells the orchestrator how to interpret the parameter's value. It has no relationship to the parameter's type in the plan metadata. The type key accepts these values:
  • query: The parameter's value in the request is interpreted as a PuppetDB query. Orchestrator executes the query and passes the resulting list of nodes to the plan as the parameter's value. For example, if the targets parameter is set to nodes[certname] { } and resolves to ["node1", "node2"], orchestrator passes ["node1", "node2"] into the plan as the parameter's value.
  • node_group: The parameter's value in the request is interpreted as a node group UUID. Orchestrator fetches all the nodes in the node group and passes them to the plan as the parameter's value. For example, if the more_targets parameter is set to a specific UUID and resolves to ["node_group1", "node_group2"], orchestrator passes that array into the plan as the parameter's value.

Refer to POST /command/plan_run for curl command examples you can modify to use with this endpoint.

Response format

If the plan starts successfully, the server returns 202 and a JSON object containing the name of the newly created plan job. For example:
{
  "name" : "1234"
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:
Response code Key Description
400 puppetlabs.orchestrator/validation-error Any of various possible validation errors, such as the plan_name not being a properly-formatted string or an error in the params.
403 puppetlabs.orchestrator/not-permitted This error occurs when a user does not have permission to run the plan, cannot run the plan on the specified nodes, or otherwise lacks permission to complete the request.

POST /command/schedule_deploy (deprecated)

Prior to deprecation, this endpoint scheduled a Puppet run on a set of nodes.

Important: This endpoint is deprecated. Instead, use POST /scheduled_jobs/environment_jobs.

Request format

Prior to deprecation, requests to this endpoint:
  • Specified the content type as application/json
  • Contained a JSON object body
  • Included these required keys: environment, scope, scheduled_time
  • Could include several optional keys.
For example, this request scheduled a deployment targeting nodes in the All Nodes node group in the production environment:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/schedule_deploy"
data='{"environment": "production", "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }, "scheduled_time": "2027-05-05T19:50:08Z"}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

Prior to deprecation, if the deployment was successfully scheduled, the server returned 202 and a JSON object containing the job's id and name. For example:
{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/81"
    "name" : "81"
  }
}

POST /command/schedule_task (deprecated)

Prior to deprecation, this endpoint scheduled a task to run at a future date and time.

Important: This endpoint is deprecated. Instead, use POST /scheduled_jobs/environment_jobs.

Request format

Prior to deprecation, requests to this endpoint:
  • Specified the content type as application/json
  • Contained a JSON object body
  • Included these required keys: environment, params, scope, scheduled_time, and task
  • Could include several optional keys.
For example, this request scheduled the package task to run on nodes in the All Nodes node group in the production environment and passed no parameters to the task:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/schedule_task"
data='{"environment" : "production", "task" : "package", "params" : {}, "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }, "scheduled_time": "2027-05-05T19:50:08Z"}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

Prior to deprecation, if the task was successfully scheduled, the server returned 202 and a JSON object containing the job's id and name. For example:
{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81"
    "name" : "81"
  }
}

POST /command/schedule_plan (deprecated)

Schedule a plan to run at a later time.

Important: This endpoint is deprecated. Instead, use POST /scheduled_jobs/environment_jobs.

Request format

Prior to deprecation, requests to this endpoint:
  • Specified the content type as application/json
  • Contained a JSON object body
  • Included these required keys: plan_name and scheduled_time
  • Could include some optional keys.
For example, this request scheduled the canary plan to run on two specific nodes:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/schedule_plan"
data='{"plan_name" : "canary", "params" : { "nodes" : ["node1.example.com", "node2.example.com"]}, "scheduled_time" : "2027-05-05T19:50:08Z"}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

Prior to deprecation, if the plan was successfully scheduled, the server returned 202 and a JSON object containing the job's id and name. For example:
{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81",
    "name" : "81"
  }
}