GET /plans/<module>/<plan-name>

Get information about a specific plan, including metadata. This endpoint provides more information than the GET /plans endpoint.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include a specific module and plan name, such as:

GET "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/firewall"

Use the GET /plans endpoint to get module and plan names.

If a plan is available in multiple environments, you can append the environment parameter to retrieve details about the plan in a specific environment. If you do not specify this parameter, the endpoint uses the default value, which is production. For example, this request retrieves details about the firewall plan in the development environment:

GET "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/firewall?environment=development"

Response format

The response is a JSON object that uses these keys to provide information about the specified plan:

Key	Definition
`id`	The URI path identifying the module and plan, as supplied in the request.
`name`	The plan's name. You can use this with, for example, the POST /command/plan_run endpoint.
`environment`	A JSON object containing the `name` of the environment specified in the request and the `code_id`. The `code_id` is either `null` or a unique string that Puppet Server uses to retrieve the version of file resources in an environment at the time when a catalog was compiled. You can learn more about `code_id` in the PuppetStatic catalogs documentation.
`metadata`	A JSON object that can be empty or contain a `description` of the plan and a `parameters` JSON object. The `parameters` object, if present, can use these keys: `type`: The required parameter type, as a valid Puppet type. If the parameter has no defined type, the value is `Any`. `default_value`: The parameter's default value. Omitted if the parameter has no default value. `description`: The parameter's description. Omitted if the parameter has no description. The `parameters` are determined by the plan's Parameters key.
`permitted`	A Boolean indicating if you are permitted to run the plan.

For example:

{
  "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/package/install",
  "name": "canary::random",
  "environment": {
    "name": "production",
    "code_id": null
  },
  "metadata": {},
  "permitted": true
}

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 There is a problem with the format of the module name, plan name, or environment parameter in the request. For example, one of the values contains illegal characters.

404 puppetlabs.orchestrator/unknown-environment No environment exists that matches the specified environment.

Response code	Key	Description
400	`puppetlabs.orchestrator/validation-error`	There is a problem with the format of the module name, plan name, or `environment` parameter in the request. For example, one of the values contains illegal characters.
404	`puppetlabs.orchestrator/unknown-environment`	No environment exists that matches the specified environment.
404	`puppetlabs.orchestrator/unknown-plan`	The endpoint can't find a match for the specified plan. There are several possible reasons for this, including: The endpoint can't find a valid relationship between the specified module and plan. The plan name is well-formed but doesn't match any existing plans. There is no such plan in the specified environment. For example, a plan that only exists in the `development` environment returns 404 if the request specified a different environment or used the default `environment` value.

404

puppetlabs.orchestrator/unknown-plan

The endpoint can't find a match for the specified plan. There are several possible reasons for this, including:

The endpoint can't find a valid relationship between the specified module and plan.
The plan name is well-formed but doesn't match any existing plans.
There is no such plan in the specified environment.

For example, a plan that only exists in the development environment returns 404 if the request specified a different environment or used the default environment value.