Plans endpoints

Use the /plans endpoint to see all known plans in your environments.

GET /plans

List all known plans in a given environment.

Parameters

The request accepts the following query parameters:


Parameter	Definition
`environment`	Return the plans in a particular environment. Defaults to production.

Response format

The response is a JSON object that lists the known plans and where to find more information about them. It uses the following keys:


Key	Definition
`items`	Contains an array of all known plans for the specified environment.
`environment`	A map containing the `name` key with the environment name and a `code_id` key indicating the code id the plans are listed from. Note: `code_id` is always `null`.

Each item above has the following keys:


Key	Definition
`id`	An absolute URL to retrieve plan details.
`name`	The full name of the plan.
`permitted`	A boolean indicating if the user making the request is permitted to use the plan.

For example:

{
  "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

For this endpoint, the kind key of the error displays the conflict.


Key	Definition
`puppetlabs.orchestrator/validation-error`	If the `environment` parameter is not a legal environment name, the server returns a `400` response.
`puppetlabs.orchestrator/unknown-environment`	If the specified `environment` doesn't exist, the server returns a `404` response.

GET /plans/:module/:planname

Return data about the specified plan, including metadata.

Parameters


Parameter	Definition
`environment`	Return the plan from a particular environment. Defaults to production. Note: `code_id` is always `null`.

Response format

The response is a JSON object that includes information about the specified plan. The following keys are used:


Key	Definition
`id`	An absolute URL to retrieve plan details.
`name`	The full name of the plan.
`environment`	A map containing a `name` key with the environment name and a `code_id` key indicating the code id the plan is being listed from.
`permitted`	A boolean indicating if the user is permitted to use the plan or not.
`metadata`	A map containing a `description` field with the plan's description, as well as a `parameters` map where keys are parameter names and values that map to `type`, `default_value`, and `description`.
`type`	The type of the parameter, matches a puppet type. If no type is present for the parameter, defaults to {{Any`
`default_value`	The default value of the parameter when it is not set. Optional.
`description`	A description of the parameter. Optional.

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


Key	Definition
`puppetlabs.orchestrator/validation-error`	If the `environment` parameter is not a legal environment name, or the module or plan name is invalid, the server returns a `400` response.
`puppetlabs.orchestrator/unknown-environment`	If the specified `environment` doesn't exist, the server returns a `404` response.
`puppetlabs.orchestrator/unknown-plan`	If the specified plan doesn't exist within that environment, the server returns a `404` response.