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.
POST /command/schedule_deploy: Schedule a Puppet run on a set of nodes.
POST /command/stop: Stop an orchestrator job that is currently running.
POST /command/task: Run a task on a set of nodes.
POST /command/task_target: Define a set of tasks and nodes/node groups you can use to escalate privileges for users who would otherwise not be able to run those tasks or run tasks on those nodes or node groups.
POST /command/schedule_task: Schedule a task to run in the future.
POST /command/plan_run: Run a plan.
POST /command/schedule_plan: Schedule a plan to run in the future.
POST /command/environment_plan_run: Run a plan in a specified environment.

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 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 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"Copied!

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]"
  }
}Copied!

This body deploys two specific nodes in the production environment:

{
  "environment" : "production",
  "scope" : {
    "nodes" : ["node1.example.com", "node2.example.com"]
  }
}Copied!

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"
  }
}
Copied!

This body deploys any node in the production environment with a certname value matching a regex:

{
  "environment" : "production",
  "scope" : {
    "query" : ["from", "nodes", ["~", "certname", ".*"]]
  }
}Copied!

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"
  }
}Copied!

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"Copied!

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
    }
  }
}Copied!

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"
  }
}Copied!

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"
}Copied!

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"Copied!

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
    }
  }
}Copied!

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"]
  }
}Copied!

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"Copied!

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"
  }
]Copied!

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"
  }
}Copied!

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 `hostnames`do 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"]
}Copied!

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": []
}Copied!

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"Copied!

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"
  }
}Copied!

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
    }
  }
}Copied!

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"Copied!

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"
  }
}Copied!

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
  }
}Copied!

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"Copied!

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"
}Copied!

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"
}Copied!

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"Copied!

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"
  }
}Copied!

Error responses

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>"
    }
  }
}Copied!

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"
}Copied!

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.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.