Forming orchestrator API requests

The orchestrator API accepts well-formed HTTPS requests and requires authentication.

Orchestrator API requests must include a URI path following the pattern:

https://<DNS>:8143/orchestrator/v1/<ENDPOINT>

The variable path components derive from:

DNS: Your PE console host's DNS name. You can use localhost, manually enter the DNS name, or use a puppet command (as explained in Using example commands).
ENDPOINT: One or more sections specifying the endpoint, such as command or jobs. Some endpoints require additional sections, such as POST /command/deploy.

For example, you could use any of these paths to call the GET /inventory endpoint:

https://$(puppet config print server):8143/orchestrator/v1/inventory
https://localhost:8143/orchestrator/v1/inventory
https://puppet.example.dns:8143/orchestrator/v1/inventory

To form a complete curl command, you need to provide appropriate curl arguments, authentication, and you might need to supply the content type and/or additional parameters specific to the endpoint you are calling.

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Orchestrator API authentication

You must authenticate orchestrator API requests with user authentication tokens. For instructions on generating, configuring, revoking, and deleting authentication tokens in PE, go to Token-based authentication.

To use a token in an orchestrator API request, you can use puppet-access show, such as:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/jobs"

curl --insecure --header "$auth_header" "$uri"

Or you can use the actual token, such as:

auth_header="X-Authentication: <TOKEN>"
uri="https://$(puppet config print server):8143/orchestrator/v1/jobs"

curl --insecure --header "$auth_header" "$uri"