GET /tasks/<module>/<task-name>

Get information about a specific task, including metadata and file information. This endpoint provides more information than the GET /tasks endpoint.

Request format

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

GET "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install"

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

To request a module's default task, use init as the task name, such as:

GET "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/init"

If a task is available in multiple environments, you can append the environment parameter to retrieve details about the task 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 install task in the development environment:

GET "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install?environment=development"

Response format

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

Key Definition
id The URI path identifying the module and task, as supplied in the request.
name A stringified number identifying the task. You can use this with, for example, the POST /command/task endpoint.
environment A JSON object containing the name of the environment specified in the request and the code_id.

code_id is either null or a unique string specifying where the environment's tasks are listed. 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.
metadata A JSON object containing the Task metadata.
files An array of JSON objects describing files used by the task. Each file object can use these keys:
  • filename: The base name of the file.
  • uri: An object containing the path and params you can use to locate the file and the version of the file used (such as the version from the production environment). The client determines which host to download the file from.
  • sha256: The SHA-256 hash of the file content, in lowercase hexadecimal form.
  • size_bytes: The size of the file content in bytes.

For example: 

{
  "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install",
  "name": "package::install",
  "environment": {
    "name": "production",
    "code_id": "urn:puppet:code-id:1:a86da166c30f871823f9b2ea224796e834840676;production"
  },
  "metadata": {
    "description": "Install a package",
    "supports_noop": true,
    "input_method": "stdin",
    "parameters": {
      "name": {
        "description": "The package to install",
        "type": "String[1]"
      },
      "provider": {
        "description": "The provider to use to install the package",
        "type": "Optional[String[1]]"
      },
      "version": {
        "description": "The version of the package to install, defaults to latest",
        "type": "Optional[String[1]]"
      }
    }
  },
  "files": [
    {
      "filename": "install",
      "uri": {
        "path": "/package/tasks/install",
        "params": {
          "environment": "production"
        }
      },
      "sha256": "a9089b5b9720dca38a49db6f164cf8a053a7ea528711325da1c23de94672980f",
      "size_bytes": 693
    }
  ]
}

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, task 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-task The endpoint can't find a match for the specified task. There are several possible reasons for this, including:
  • The endpoint can't find a valid relationship between the specified module and task.
  • The task name is well-formed but doesn't match any existing tasks.
  • There is no such task in the specified environment.

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