Use the /tasks endpoint to view details about the tasks pre-installed by PE and those you've installed.
GET /tasks
Lists all tasks in a given environment.
Parameters
The request accepts this query parameter:
| Parameter | Definition |
|---|---|
environment | Returns the tasks in the specified environment. If unspecified, defaults to production. |
Response format
The response is a JSON object that lists each known task with a link to additional information, and uses these keys:
| Key | Definition |
|---|---|
environment | A map containing a name key specifying the environment's name and a code_id key indicating the code ID where the task is listed. |
items | Contains an array of all known tasks. |
id | An absolute URL where the task's details are listed. |
name | The full name of the task. |
{
"environment": {
"name": "production",
"code_id": "urn:puppet:code-id:1:a86da166c30f871823f9b2ea224796e834840676;production"
},
"items": [
{
"id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install",
"name": "package::install"
},
{
"id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/upgrade",
"name": "package::upgrade"
},
{
"id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/exec/init",
"name": "exec"
}
]
}Error responses
See the error response documentation for the general format of 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 /tasks/:module/:taskname
Returns data about a specified task, including metadata and file information. For the default task in a module, :taskname should be init.
Parameters
The request accepts this query parameter:
| Parameter | Definition |
|---|---|
environment
| Returns the tasks in the specified environment. If unspecified, defaults to production. |
Response format
The response is a JSON object that includes information about the specified task, and uses these keys:
For example:
| Key | Definition |
|---|---|
id
| An absolute URL where the task's details are listed. |
name
| The full name of the task. |
environment
| A map containing a name key specifying the environment's name and a code_id key indicating the code ID where the task is listed.
|
metadata
| A map containing the contents of the <task>.json file.
|
files
| An array of the files in the task. |
filename
| The base name of the file. |
uri
| A map containing path and params fields to construct a URL to download the file content. The client should determine 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. |
{
"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
See the error response documentation for the general format of 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, or the module or taskname 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-task | If the specified task doesn't exist within the specified environment, the server returns a 404 response. |