GET /plans

Lists all known plans in a specific environment.

Request format

When Forming orchestrator API requests to this endpoint, you can use the default URI path to query plans in the production environment, such as:

https://orchestrator.example.com:8143/orchestrator/v1/plans

For any other environments, you must use the environment parameter to specify the environment whose plans you want to query. For example, this request queries plans in the development environment:

https://orchestrator.example.com:8143/orchestrator/v1/plans?environment=development

Response format

The response is a JSON object containing an environment object and a items array.

The environment object contains these keys:

• name: The environment specified in the request.
• code_id: Either null or a unique string. Puppet Server uses the code_id 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 Puppet Static catalogs documentation.

The items array contains one JSON object for each plan in the environment. Each plan object uses these keys:

Key	Definition
id	A URI path you can use with the GET /plans/<module>/<plan-name> endpoint to learn more about the plan.
name	The plan's name. You can use this with, for example, the POST /command/plan_run endpoint.
permitted	A Boolean indicating if you are permitted to run the plan.

For example, this response describes three plans in the production environment:

{
  "environment": {
    "name": "production",
    "code_id": null
  },
  "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/firewall",
      "name": "profile::firewall",
      "permitted": true
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/rolling_update",
      "name": "profile::rolling_update",
      "permitted": true
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/canary/random",
      "name": "canary::random",
      "permitted": false
    }
  ]
}

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 environment parameter does not supply a legal environment name. For example, the name is not a string or contains illegal characters.
404	puppetlabs.orchestrator/unknown-environment	No environment exists that matches the specified environment.