Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Orchestrating Puppet runs, tasks, and plans Grey arrow pointing right Orchestrator API v1 Grey arrow pointing right Forming orchestrator API requests Grey arrow pointing right

Forming orchestrator API requests

Sections

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>Copied!
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 the POST /command/schedule_task endpoint.
For example, you could use any of these paths to call the GET /inventory endpoint:
GET https://$(puppet config print server):8143/orchestrator/v1/inventory
GET https://localhost:8143/orchestrator/v1/inventory
GET https://puppet.example.dns:8143/orchestrator/v1/inventoryCopied!

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" GET "$uri"Copied!
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" GET "$uri"Copied!