Finding environments

2 minute read

The CloudBees Previews API provides an endpoint that you can use to search for environments across namespaces. It supports using optional parameters to filter environments. Before you can find environments, you must authenticate requests by providing the API token.

You can use a curl query similar to the following to search for environments:

Getting a filtered list of existing environments
$ curl -H 'X-Api-Token: <API_TOKEN>' \ (1)
	"<SERVER_ADDRESS>/api/v1/environments?labels=<LABELSELECTOR>" \
	| jq .
  "items": [
      "metadata": {
        "name": "env-xyz",             (2)
        "namespace": "previews",       (3)
        "labels": {                    (4)
          "commit-sha": "b49f34af0888c7c3cd676ba78ec64864754705be",
          "context": "default",
          "pr-number": "42",
          "repo-namespace": "sample-org",
          "repo-name": "sample-app-helm"
      "spec": {
        "gitSource": {                 (5)
          "cloneURL": "",
          "commitSHA": "b49f34af0888c7c3cd676ba78ec64864754705be"
        "context": "default"           (6)
      "status": {
        "phase": "ready",              (7)
        "urls": [
          {                            (8)
            "url": ""
1<SERVER_ADDRESS> must be substituted with the Helm chart’s value (defaults to api.<>). <API_TOKEN> must be substituted with the API token that was configured with the apiserver.auth chart value. <LABELSELECTOR> is optional, and can specify comma-separated <LABEL>=<VALUE> pairs to find environments that match all specified labels. For example, if you specify the value repo-namespace=sample-org,repo-name=sample-app-helm, you can find all environments associated with that git repository.
2Name of the environment.
3Namespace of the environment.
4Environment labels that can be used as <LABELSELECTOR>.
5Git source used to provision the environment.
6Context used to provision the environment. This value refers to the preview declaration within the .preview.yaml file specified by the Git source.
7Phase the environment is currently in. When the phase is ready, the environment is provisioned.
8Ingress URL the environment exposes. This is where you can access the provisioned preview. Ingress URLs are only listed when the environment is in the ready phase.

If you want to find a specific environment, obtain its URL, and use it to create jobs, refer to Obtaining the ingress URL for an environment.