Command endpoints

Use the command endpoints to run Puppet, jobs, and plans on demand; stop in-progress jobs; or schedule future runs of Puppet, jobs, or plans. 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:

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:
  • application: The name of an application or application instance to deploy. If an application type is specified, all instances of that application are deployed.
  • 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 Configuring orchestration.

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 same environment where their assigned applications are defined. 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 an application instance in the production environment:
{
  "environment" : "production",
  "scope" : {
    "application" : "Wordpress_app[demo]"
  }
}
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. You can use it with the GET /jobs/<job-id> endpoint to retrieve information about the status of the job.
  • name: The name of 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-environment The specified environment contains no applications or no nodes.
400 puppetlabs.orchestrator/empty-target If the request specified an application for the scope, the specified application instance does not exist or is empty.
400 puppetlabs.orchestrator/dependency-cycle If the request specified an application for the scope, the application code contains a cycle.
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/schedule_deploy

Schedule a Puppet run on a set of nodes.

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 required keys:
Key Definition
environment A string specifying 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 A JSON object containing exactly one key defining the deployment target:
  • application: The name of an application or application instance to deploy. If an application type is specified, all instances of that application are deployed.
  • 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.
scheduled_time A timestamp, in ISO-8601 format, defining the time to run the scheduled job.
You can use these optional keys:
Key Definition
concurrency An integer specifying the maximum number of nodes to run at one time. The default, if unspecified, is unlimited.
debug A Boolean specifying whether to use the --debug flag on Puppet agent runs.
description A string describing the job.
enforce_environment A Boolean specifying whether to force agents to run in the same environment where their assigned applications are defined. This key must be false if environment is an empty string.
evaltrace A Boolean specifying whether to use the --evaltrace flag on Puppet agent runs.
filetimeout An integer specifying the value of the --filetimeout flag on Puppet agent runs.
http_connect_timeout An integer specifying the value for the --http_connect_timeout flag on Puppet agent runs.
http_keepalive_timeout An integer specifying the value for the --http_keepalive_timeout flag on Puppet agent runs.
http_read_timeout An integer specifying the value for the --http_read_timeout flag on Puppet agent runs.
interval A JSON object containing units and value to define intervals for the deployment. This object resides inside schedule_options.
noop A Boolean specifying whether to run the agent in no-op mode. The default is false.
no_noop A Boolean specifying 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 A string defining the value of the --ordering flag on Puppet agent runs.
schedule_options A JSON object containing the interval JSON object. Defines intervals for the deployment.
skip_tags A string defining the value of the --skip_tags flag on Puppet agent runs.
tags A string defining the value of the --tags flag on Puppet agent runs.
trace A Boolean specifying whether to use the --trace flag on Puppet agent runs.
units Used with interval and schedule_options. It is a string specifying enum as seconds.
use_cached_catalog A Boolean specifying whether to use the --use_cached_catalog flag on Puppet agent runs.
usecacheonfailure A Boolean specifying whether to use the --usecacheonfailure flag on Puppet agent runs.
value Used with interval and schedule_options. It is a positive integer specifying the amount of seconds per interval.
Here is an example of a complete curl command for the /command/schedule_deploy endpoint. This request schedules 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"
As an additional example, this body schedules a deployment of the node1.example.com node in noop mode:
{
  "environment" : "",
  "enforce_environment": false,
  "noop" : true,
  "scope" : {
    "nodes" : ["node1.example.com"]
  },
  "scheduled_time": "2027-05-05T19:50:08Z",
  "schedule_options": {
    "interval": {
      "units": "seconds",
      "value": 86400
    }
  }
}

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

Response format

If the deployment is successfully scheduled, 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: The name of 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-environment The specified environment contains no applications or no nodes.
400 puppetlabs.orchestrator/empty-target If the request specified an application for the scope, the specified application instance does not exist or is empty.
400 puppetlabs.orchestrator/dependency-cycle If the request specified an application for the scope, the application code contains a cycle.
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.
400 puppetlabs.orchestrator/invalid-time The supplied scheduled_time timestamp is in the past.

POST /command/stop

Stop an orchestrator job that is currently in progress. 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.

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 to job ID of the job to stop, such as:
{
  "job": "1234"
}
You can get job IDs from the POST /command/deploy or GET /jobs responses.
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: The name of 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/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. Furthermore, unlike other orchestrator API endpoints, application scopes are not allowed for task jobs.
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.
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: The name of 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/schedule_task

Schedule a task to run at a future date and time.

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
description String A description of the job.
environment String Required: The name of the environment to load the task from. The default is production.
interval JSON object Contains units and value to define intervals for running the task. This object resides inside schedule_options.
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.
schedule_options JSON object Contains the interval JSON object and defines intervals for running the task.
scheduled_time Timestamp Required: A timestamp, in ISO-8601 format, defining the time to run the scheduled job.
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. Furthermore, unlike other orchestrator API endpoints, application scopes are not allowed for task jobs.
task String Required: The task to run on the target nodes.
units String Used with interval and schedule_options. Specifies enum as seconds.
value Integer Used with interval and schedule_options. It is a positive integer specifying the amount of seconds per interval.
For example, this body schedules a run of the package task on the node1.example.com node in the test-env-1 environment. It passes the action and package parameters to the task.
{
  "environment": "test-env-1",
  "task": "package",
  "params": {
    "action": "install",
    "package": "httpd"
  },
  "scope": {
    "nodes": [
      "node1.example.com"
    ]
  },
  "scheduled_time": "2027-05-05T19:50:08Z",
  "schedule_options": {
    "interval": {
      "units": "seconds",
      "value": 86400
    }
  }
}
Here is an example of a complete curl command for the /command/schedule_task endpoint. This request schedules the package task to run on nodes in the All Nodes node group in the production environment and passes 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"

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

Response format

If the task is successfully scheduled, 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 DELETE /scheduled_jobs/<job-id> endpoint to delete the scheduled job.
  • name: The name of the newly created job.
For example:
{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81"
    "name" : "81"
  }
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 400 puppetlabs.orchestrator/invalid-time response if the scheduled_time timestamp is in the past.

For other error codes this endpoint might return, refer to the POST /command/task error responses.

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.
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"
}

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/schedule_plan

Schedule a plan to run at a later time.

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.
scheduled_time Timestamp Required: A timestamp, in ISO-8601 format, defining the time to run the scheduled plan.
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.
userdata JSON object Arbitrary key/value data supplied to the job.
For example, this body schedules the canary plan to run on two specific nodes:
{
  "plan_name" : "canary",
  "params" : {
    "nodes" : ["node1.example.com", "node2.example.com"],
  },
  "scheduled_time": "2027-05-05T19:50:08Z"
}
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/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

If the plan is successfully scheduled, the server returns 202 and a JSON object using these keys:
  • id: An absolute URL that links to the newly created plan job. You can use it with the GET /plan_jobs/<job-id> to get information about the status of the plan job.
  • name: The name of the newly created plan job.
For example:
{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/81",
    "name" : "81"
  }
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 400 puppetlabs.orchestrator/invalid-time response if the scheduled_time timestamp is in the past.

For other error codes this endpoint might return, refer to the POST /command/plan_run error responses.

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.
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.