# List Deployments

### Endpoint

**POST** `/api/k8s/v2/deployments/list`

### Authentication

This endpoint requires API Key authentication via the Authorization header.

### Headers

| Header          | Required | Description                    |
| --------------- | -------- | ------------------------------ |
| `Authorization` | Yes      | Bearer token with your API key |
| `X-Backend-Id`  | Yes      | Your backend identifier        |
| `Content-Type`  | Yes      | Must be `application/json`     |
| `Accept`        | Yes      | Must be `application/json`     |

#### Request Body

The request body requires a time range and supports filtering by fields:

```json
{
  "start": "2025-08-24T07:21:36.944Z",
  "end": "2025-08-24T08:51:36.944Z", 
  "namespaces": ["groundcover"],
  "sources": []
}
```

**Parameters**

| Parameter    | Type   | Required | Description                                                                |
| ------------ | ------ | -------- | -------------------------------------------------------------------------- |
| `start`      | string | Yes      | Start time in ISO 8601 UTC format (e.g., `"2025-08-24T07:21:36.944Z"`)     |
| `end`        | string | Yes      | End time in ISO 8601 UTC format (e.g., `"2025-08-24T08:51:36.944Z"`)       |
| `namespaces` | array  | No       | Array of namespace names to filter by (e.g., `["groundcover", "default"]`) |
| `sources`    | array  | No       | Source filters                                                             |

### Response

#### Response Schema

```json
{
  "deployments": [
    {
      "name": "string",
      "namespace": "string", 
      "workloadName": "string",
      "creationTime": "2023-08-30T18:27:01Z",
      "cluster": "string",
      "env": "string",
      "available": 1,
      "desired": 1,
      "ready": 1,
      "conditions": [
        {
          "type": "string",
          "status": "string",
          "lastProbeTime": null,
          "lastHeartbeatTime": null,
          "lastTransitionTime": "string",
          "reason": "string",
          "message": "string"
        }
      ],
      "warnings": [],
      "id": "string",
      "resourceVersion": 0
    }
  ]
}
```

**Field Descriptions**

| Field                             | Type        | Description                                           |
| --------------------------------- | ----------- | ----------------------------------------------------- |
| `deployments`                     | array       | Array of deployment objects                           |
| `name`                            | string      | Deployment name                                       |
| `namespace`                       | string      | Kubernetes namespace                                  |
| `workloadName`                    | string      | Associated workload name                              |
| `creationTime`                    | string      | Deployment creation timestamp in ISO 8601 format      |
| `cluster`                         | string      | Kubernetes cluster name                               |
| `env`                             | string      | Environment name (e.g., `"prod"`, `"staging"`)        |
| `available`                       | integer     | Number of available replicas                          |
| `desired`                         | integer     | Number of desired replicas                            |
| `ready`                           | integer     | Number of ready replicas                              |
| `conditions`                      | array       | Array of deployment condition objects                 |
| `conditions[].type`               | string      | Condition type (e.g., `"Available"`, `"Progressing"`) |
| `conditions[].status`             | string      | Condition status (`"True"`, `"False"`, `"Unknown"`)   |
| `conditions[].lastProbeTime`      | string/null | Last time the condition was probed                    |
| `conditions[].lastHeartbeatTime`  | string/null | Last time the condition was updated                   |
| `conditions[].lastTransitionTime` | string      | Last time the condition transitioned                  |
| `conditions[].reason`             | string      | Machine-readable reason for the condition             |
| `conditions[].message`            | string      | Human-readable message explaining the condition       |
| `warnings`                        | array       | Array of warning messages (usually empty)             |
| `id`                              | string      | Unique identifier for the deployment                  |
| `resourceVersion`                 | integer     | Kubernetes resource version                           |

**Common Condition Types**

| Type          | Description                                         |
| ------------- | --------------------------------------------------- |
| `Available`   | Deployment has minimum availability                 |
| `Progressing` | Deployment is making progress towards desired state |

**Common Condition Reasons**

| Reason                     | Description                                         |
| -------------------------- | --------------------------------------------------- |
| `MinimumReplicasAvailable` | Deployment has minimum number of replicas available |
| `NewReplicaSetAvailable`   | New ReplicaSet has successfully progressed          |

### Examples

#### Basic Request

Get deployments for a specific time range:

```bash
curl 'https://api.groundcover.com/api/k8s/v2/deployments/list' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --data-raw '{"start":"2025-08-24T07:21:36.944Z","end":"2025-08-24T08:51:36.944Z","namespaces":[],"sources":[]}'
```

#### Filter by Namespace

Get deployments from specific namespaces:

```bash
curl 'https://api.groundcover.com/api/k8s/v2/deployments/list' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --data-raw '{"start":"2025-08-24T07:21:36.944Z","end":"2025-08-24T08:51:36.944Z","namespaces":["groundcover","monitoring"],"sources":[]}'
```

#### Response Example

```json
{
  "deployments": [
    {
      "name": "db-manager",
      "namespace": "groundcover",
      "workloadName": "db-manager",
      "creationTime": "2023-08-30T18:27:01Z",
      "cluster": "karma-cluster",
      "env": "prod",
      "available": 1,
      "desired": 1,
      "ready": 1,
      "conditions": [
        {
          "type": "Available",
          "status": "True",
          "lastProbeTime": null,
          "lastHeartbeatTime": null,
          "lastTransitionTime": "2025-08-22T06:18:27Z",
          "reason": "MinimumReplicasAvailable",
          "message": "Deployment has minimum availability."
        },
        {
          "type": "Progressing",
          "status": "True",
          "lastProbeTime": null,
          "lastHeartbeatTime": null,
          "lastTransitionTime": "2023-08-30T18:27:01Z",
          "reason": "NewReplicaSetAvailable",
          "message": "ReplicaSet \"db-manager-867bc8f5b8\" has successfully progressed."
        }
      ],
      "warnings": [],
      "id": "f3b1f4a5-f38a-4c63-a7c0-9333fcbf1906",
      "resourceVersion": 747039184
    }
  ]
}
```

### Time Range Guidelines

* Use ISO 8601 UTC format for timestamps
* Typical time ranges: 1-24 hours for operational monitoring
* Maximum recommended range: 7 days
* Format: `YYYY-MM-DDTHH:MM:SS.sssZ`