# Kubernetes

Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md
## DELETE /k8/delete-service/{namespace}/{kind}/{name}

**Delete a Kubernetes resource**

`operationId: K8sManagementController_deleteService`

Deletes a resource from the cluster. **Takes the workload down immediately** and cannot be undone — the manifest has to be re-applied to bring it back.

#### Signature

```http
DELETE /k8/delete-service/{namespace}/{kind}/{name} (namespace: string, kind: string, name: string) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Immediately destructive.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /k8/apply-service`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `kind` | path | string | yes | Resource kind. |
| `namespace` | path | string | yes | Namespace. |
| `name` | path | string | yes | Resource name. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The result |
| `202` | Service deletion accepted |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## DELETE /k8/namespaces/{name}

**Delete a namespace**

`operationId: K8sManagementController_deleteNamespace`

**Deletes an entire Kubernetes namespace and everything in it** — every deployment, service, secret and volume claim it holds.

This is the most destructive endpoint in the module. Namespaces typically correspond to a customer's workloads, so deleting one takes that customer offline entirely. There is no confirmation and no undo.

#### Signature

```http
DELETE /k8/namespaces/{name} (name: string) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Destroys every resource in the namespace. No undo.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /k8/cleanup-resources`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `name` | path | string | yes | Namespace to delete. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The result |
| `202` | Namespace deletion accepted |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /k8/namespaces/{namespaceName}/pods

**List pods in a namespace**

`operationId: K8sManagementController_getPods`

Pods running in a namespace, with their status — the first look when a site is not responding.

#### Signature

```http
GET /k8/namespaces/{namespaceName}/pods (namespaceName: string) -> Pods
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /k8/check-status/{namespace}/{kind}/{resource}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespaceName` | path | string | yes | Namespace. |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Pods |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /k8/namespaces/{namespaceName}

**Get a namespace**

`operationId: K8sManagementController_getNamespace`

One namespace and its metadata.

#### Signature

```http
GET /k8/namespaces/{namespaceName} (namespaceName: string) -> The namespace
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /k8/namespaces/{namespaceName}/pods`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespaceName` | path | string | yes | Namespace. |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The namespace |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /k8/check-status/{namespace}/{kind}/{resource}

**Check a resource's status**

`operationId: K8sManagementController_checkStatus`

The status of one Kubernetes resource, by namespace, kind and name.

#### Signature

```http
GET /k8/check-status/{namespace}/{kind}/{resource} (namespace: string, kind: string, resource: string) -> The status
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /k8/apply-service`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `namespace` | path | string | yes | Namespace. |
| `kind` | path | string | yes | Resource kind. |
| `resource` | path | string | yes | Resource name. |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The status |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /k8/namespaces

**List namespaces**

`operationId: K8sManagementController_listNamespaces`

Kubernetes namespaces on the cluster.

#### Signature

```http
GET /k8/namespaces () -> Namespaces
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /k8/namespaces/{namespaceName}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Namespaces |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /k8/apply-service

**Apply a Kubernetes service**

`operationId: K8sManagementController_applyService`

Applies a service manifest to the cluster. Applying is declarative: it creates or replaces, so a partial manifest can remove fields that were previously set.

#### Signature

```http
POST /k8/apply-service (body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Declarative apply — omitted fields are dropped.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `DELETE /k8/delete-service/{namespace}/{kind}/{name}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The manifest.

```json
{
  "namespace": "org-4821",
  "kind": "Deployment",
  "name": "acme-shop",
  "spec": {}
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /k8/cleanup-resources

**Clean up site resources**

`operationId: K8sManagementController_cleanupSiteResources`

Removes the cluster resources belonging to a site. Destructive by design — it exists to reclaim what a deleted site left behind, so confirm the site really is gone first.

#### Signature

```http
POST /k8/cleanup-resources (body) -> What was removed
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Deletes cluster resources.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `DELETE /k8/delete-service/{namespace}/{kind}/{name}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

Which site.

```json
{
  "siteName": "acme-shop",
  "namespace": "org-4821"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Site resources cleanup initiated |
| `201` | What was removed |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /k8/scale-up

**Scale up a deployment**

`operationId: K8sManagementController_scaleUp`

Raises a deployment's replica count — bringing a scaled-to-zero workload back, or adding capacity. Costs cluster resources.

#### Signature

```http
POST /k8/scale-up (body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /k8/scale-down`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

What to scale.

```json
{
  "namespace": "org-4821",
  "name": "acme-shop",
  "replicas": 2
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /k8/scale-down

**Scale a deployment to zero**

`operationId: K8sManagementController_scaleToZero`

Scales a deployment down to zero replicas. The workload stops serving entirely — this is how an idle site is parked, and it is indistinguishable from an outage to anyone visiting it.

#### Signature

```http
POST /k8/scale-down (body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Takes the workload offline.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /k8/scale-up`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

What to scale down.

```json
{
  "namespace": "org-4821",
  "name": "acme-shop"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |