Finding environments

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": "https://github.com/mgoltzsche/sample-app-helm.git",
          "commitSHA": "b49f34af0888c7c3cd676ba78ec64864754705be"
        },
        "context": "default"           (6)
      },
      "status": {
        "phase": "ready",              (7)
        "urls": [
          {                            (8)
            "url": "https://env-xyz.preview.example.org/myapp"
          }
        ]
      }
    }
  ]
}▼

1	`<SERVER_ADDRESS>` must be substituted with the Helm chart’s value `apiserver.ingress.host` (defaults to `api.<global.ingress.host>`). `<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.
2	Name of the environment.
3	Namespace of the environment.
4	Environment labels that can be used as `<LABELSELECTOR>`.
5	Git source used to provision the environment.
6	Context used to provision the environment. This value refers to the preview declaration within the .preview.yaml file specified by the Git source.
7	Phase the environment is currently in. When the phase is `ready`, the environment is provisioned.
8	Ingress 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.