> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instapods.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pods

> Create, manage, and control pod lifecycle via the API.

## Create a Pod

```
POST /api/pods
```

**Request Body:**

```json theme={null}
{
  "name": "my-app",
  "preset": "nodejs",
  "plan_slug": "launch",
  "region": "eu-nbg",
  "ssh_key": "ssh-ed25519 AAAA...",
  "description": "My Node.js app",
  "customizations": {
    "env_vars": {
      "NODE_ENV": "production"
    }
  }
}
```

| Field            | Type   | Required | Description                                    |
| ---------------- | ------ | -------- | ---------------------------------------------- |
| `name`           | string | Yes      | Pod name (lowercase, alphanumeric + hyphens)   |
| `preset`         | string | Yes      | `static`, `php`, `nodejs`, or `python`         |
| `plan_slug`      | string | No       | Plan slug (default: `launch`)                  |
| `region`         | string | No       | Region slug (auto-detected from IP if omitted) |
| `server_id`      | string | No       | Specific server ID (overrides region)          |
| `ssh_key`        | string | No       | Public SSH key to inject                       |
| `description`    | string | No       | Pod description                                |
| `customizations` | object | No       | Custom env vars, cron jobs, workers            |

**Response: `202 Accepted`**

Returns the [Pod object](#pod-object) with `status: "creating"`.

**Errors:**

| Code  | Reason                                         |
| ----- | ---------------------------------------------- |
| `400` | Invalid name, unknown preset, validation error |
| `402` | No payment method or subscription suspended    |
| `409` | Pod name already exists                        |
| `503` | Insufficient server capacity                   |

## List Pods

```
GET /api/pods
```

| Query Param | Type | Default | Description        |
| ----------- | ---- | ------- | ------------------ |
| `limit`     | int  | —       | Max pods to return |
| `offset`    | int  | 0       | Pagination offset  |

**Response: `200 OK`**

```json theme={null}
{
  "pods": [{ ... }],
  "total": 12,
  "limit": 25,
  "offset": 0,
  "status_counts": {
    "running": 8,
    "stopped": 3,
    "creating": 1
  }
}
```

## Get a Pod

```
GET /api/pods/{name}
```

Returns the [Pod object](#pod-object) with live status synced from the container runtime.

## Delete a Pod

```
DELETE /api/pods/{name}
```

**Response: `200 OK`**

```json theme={null}
{
  "status": "deleted"
}
```

<Note>
  Pod names are reserved for 7 days after deletion to prevent SSH host key conflicts. Creating a pod with a recently deleted name will return a conflict error.
</Note>

## Start / Stop / Restart

```
POST /api/pods/{name}/start
POST /api/pods/{name}/stop
POST /api/pods/{name}/restart
```

No request body. Returns the updated [Pod object](#pod-object).

## Reload

```
POST /api/pods/{name}/reload
```

Restarts app services inside the pod. Auto-installs dependencies if `package.json` (Node.js) or `requirements.txt` (Python) is detected.

**Response: `200 OK`**

```json theme={null}
{
  "status": "reloaded",
  "services": ["app"],
  "preset": "nodejs",
  "deps_installed": "npm"
}
```

| Field            | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| `services`       | Which systemd services were restarted                        |
| `preset`         | Pod's preset                                                 |
| `deps_installed` | `"npm"` or `"pip"` if deps were installed, omitted otherwise |

## Resize

```
POST /api/pods/{name}/resize
```

**Request Body:**

```json theme={null}
{
  "plan_slug": "build"
}
```

Returns the updated [Pod object](#pod-object) with new CPU, memory, and disk values from the plan.

| Code  | Reason                                     |
| ----- | ------------------------------------------ |
| `400` | Invalid plan, disk usage exceeds new quota |
| `409` | Insufficient server resources for upgrade  |

## Clone

```
POST /api/pods/{name}/clone
```

**Request Body:**

```json theme={null}
{
  "new_name": "my-app-copy"
}
```

**Response: `201 Created`** — returns the new [Pod object](#pod-object).

## Get Preset Config

```
GET /api/pods/{name}/preset
```

Returns the preset configuration for this pod (port, app root, public root, runtime details).

## Get Disk Usage

```
GET /api/pods/{name}/disk-usage
```

Returns current disk usage statistics for the pod.

***

## Pod Object

All pod endpoints return this shape:

```json theme={null}
{
  "id": "abc123",
  "name": "my-app",
  "preset": "nodejs",
  "status": "running",
  "ip": "10.0.0.5",
  "domain": "my-app.nbg1-1.instapods.app",
  "ssh_port": 2201,
  "ssh_user": "instapod",
  "cpu": 1,
  "memory": "512MB",
  "disk": "10GB",
  "plan_slug": "launch",
  "app_root": "/home/instapod/app",
  "region": "eu-nbg",
  "server_name": "instapod-nbg1-1",
  "description": "",
  "created_at": "2026-02-20T10:00:00Z",
  "updated_at": "2026-02-20T10:00:00Z"
}
```

**Pod statuses:** `creating`, `running`, `stopped`, `deleted`, `error`, `suspended`