> ## 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.

# API Overview

> Authenticate and interact with the InstaPods REST API.

The InstaPods API is a RESTful HTTP API that powers the dashboard, CLI, and third-party integrations.

## Base URL

```
https://app.instapods.com
```

## Authentication

The API supports two authentication methods:

### Bearer Token

Include an `Authorization` header with your token:

```bash theme={null}
curl https://app.instapods.com/api/pods \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Obtain a token by logging in via the API:

```bash theme={null}
curl -X POST https://app.instapods.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

### Session Cookie

The dashboard uses session cookies (`instapod_session`) set at login. This is handled automatically by the browser.

## Request Format

* All request bodies must be JSON with `Content-Type: application/json`
* All responses are JSON

## Error Responses

Errors return an appropriate HTTP status code with a JSON body:

```json theme={null}
{
  "error": "Pod not found"
}
```

Common status codes:

| Code  | Meaning                                 |
| ----- | --------------------------------------- |
| `400` | Bad request — invalid input             |
| `401` | Unauthorized — missing or invalid token |
| `403` | Forbidden — insufficient permissions    |
| `404` | Not found                               |
| `429` | Rate limited                            |
| `500` | Internal server error                   |

## Rate Limits

| Endpoint                         | Limit           |
| -------------------------------- | --------------- |
| `POST /api/auth/login`           | 5/minute per IP |
| `POST /api/auth/register`        | 3/minute per IP |
| `POST /api/auth/forgot-password` | 3/minute per IP |
| `POST /api/pods`                 | 50/hour per IP  |

## Available Endpoints

The API organizes endpoints into groups:

| Group              | Scope                                                            |
| ------------------ | ---------------------------------------------------------------- |
| **Authentication** | Register, login, password reset, email verification              |
| **Pods**           | Create, start, stop, restart, reload, resize, clone, delete      |
| **Files**          | List, read, write, upload, download, rename, copy, delete, mkdir |
| **SSH**            | Connection info, key management (per-pod and account-level)      |
| **Domains**        | Custom domain mapping with DNS verification                      |
| **Services**       | Install and manage MySQL, PostgreSQL, Redis                      |
| **Logs & Metrics** | Application logs, events, resource metrics                       |
| **Teams**          | Team CRUD, member management, invitations                        |
| **Billing**        | Subscriptions, invoices, payment methods, credits                |
| **Catalog**        | Plans, presets, regions, runtimes                                |

***

## Authentication

| Method | Path                            | Description               |
| ------ | ------------------------------- | ------------------------- |
| `POST` | `/api/auth/register`            | Create a new account      |
| `POST` | `/api/auth/login`               | Log in and get a session  |
| `POST` | `/api/auth/logout`              | Log out                   |
| `GET`  | `/api/auth/user`                | Get current user          |
| `POST` | `/api/auth/forgot-password`     | Request password reset    |
| `POST` | `/api/auth/reset-password`      | Reset password with token |
| `POST` | `/api/auth/verify-email`        | Verify email address      |
| `POST` | `/api/auth/resend-verification` | Resend verification email |

## Pods

| Method   | Path                          | Description                              |
| -------- | ----------------------------- | ---------------------------------------- |
| `GET`    | `/api/pods`                   | List all pods                            |
| `POST`   | `/api/pods`                   | Create a pod                             |
| `GET`    | `/api/pods/{name}`            | Get pod details                          |
| `DELETE` | `/api/pods/{name}`            | Delete a pod                             |
| `POST`   | `/api/pods/{name}/start`      | Start a pod                              |
| `POST`   | `/api/pods/{name}/stop`       | Stop a pod                               |
| `POST`   | `/api/pods/{name}/restart`    | Restart a pod                            |
| `POST`   | `/api/pods/{name}/reload`     | Reload app services (auto-installs deps) |
| `POST`   | `/api/pods/{name}/resize`     | Resize a pod (change plan)               |
| `POST`   | `/api/pods/{name}/clone`      | Clone a pod                              |
| `GET`    | `/api/pods/{name}/preset`     | Get pod's preset config                  |
| `GET`    | `/api/pods/{name}/disk-usage` | Get pod disk usage                       |

## Files

| Method   | Path                              | Description               |
| -------- | --------------------------------- | ------------------------- |
| `GET`    | `/api/pods/{name}/files`          | List files in a directory |
| `GET`    | `/api/pods/{name}/files/content`  | Read a file               |
| `PUT`    | `/api/pods/{name}/files/content`  | Write/update a file       |
| `POST`   | `/api/pods/{name}/files/upload`   | Upload a file             |
| `GET`    | `/api/pods/{name}/files/download` | Download a file           |
| `DELETE` | `/api/pods/{name}/files`          | Delete a file             |
| `POST`   | `/api/pods/{name}/files/rename`   | Rename/move a file        |
| `POST`   | `/api/pods/{name}/files/copy`     | Copy a file or directory  |
| `POST`   | `/api/pods/{name}/folders`        | Create a folder           |

## SSH

| Method   | Path                        | Description                  |
| -------- | --------------------------- | ---------------------------- |
| `GET`    | `/api/pods/{name}/ssh`      | Get SSH connection info      |
| `GET`    | `/api/pods/{name}/ssh/keys` | List SSH keys on a pod       |
| `POST`   | `/api/pods/{name}/ssh/keys` | Add an SSH key to a pod      |
| `DELETE` | `/api/pods/{name}/ssh/keys` | Remove an SSH key from a pod |
| `GET`    | `/api/ssh-keys`             | List account-level SSH keys  |
| `POST`   | `/api/ssh-keys`             | Add an account SSH key       |
| `PUT`    | `/api/ssh-keys/{id}`        | Update an account SSH key    |
| `DELETE` | `/api/ssh-keys/{id}`        | Delete an account SSH key    |

## Domains

| Method   | Path                                   | Description         |
| -------- | -------------------------------------- | ------------------- |
| `GET`    | `/api/pods/{name}/domains`             | List custom domains |
| `POST`   | `/api/pods/{name}/domains`             | Add a custom domain |
| `DELETE` | `/api/pods/{name}/domains/{id}`        | Remove a domain     |
| `POST`   | `/api/pods/{name}/domains/{id}/verify` | Verify domain DNS   |

## Services

| Method   | Path                                           | Description             |
| -------- | ---------------------------------------------- | ----------------------- |
| `GET`    | `/api/pods/{name}/services`                    | List installed services |
| `POST`   | `/api/pods/{name}/services`                    | Install a service       |
| `DELETE` | `/api/pods/{name}/services/{type}`             | Remove a service        |
| `GET`    | `/api/pods/{name}/services/{type}/credentials` | Get service credentials |

## Logs & Metrics

| Method | Path                               | Description         |
| ------ | ---------------------------------- | ------------------- |
| `GET`  | `/api/pods/{name}/logs`            | Get pod logs        |
| `GET`  | `/api/pods/{name}/events`          | List pod events     |
| `GET`  | `/api/pods/{name}/metrics`         | Get current metrics |
| `GET`  | `/api/pods/{name}/metrics/history` | Get metrics history |

## Teams

| Method   | Path                                  | Description              |
| -------- | ------------------------------------- | ------------------------ |
| `GET`    | `/api/teams`                          | List your teams          |
| `POST`   | `/api/teams`                          | Create a team            |
| `POST`   | `/api/teams/switch`                   | Switch active team       |
| `GET`    | `/api/teams/{id}`                     | Get team details         |
| `PUT`    | `/api/teams/{id}`                     | Update a team            |
| `DELETE` | `/api/teams/{id}`                     | Delete a team            |
| `GET`    | `/api/teams/{id}/members`             | List team members        |
| `POST`   | `/api/teams/{id}/members`             | Add a team member        |
| `DELETE` | `/api/teams/{id}/members/{uid}`       | Remove a member          |
| `GET`    | `/api/teams/{id}/invitations`         | List pending invitations |
| `POST`   | `/api/teams/{id}/invitations`         | Send an invitation       |
| `DELETE` | `/api/teams/{id}/invitations/{invId}` | Revoke an invitation     |

## Billing

| Method   | Path                                   | Description                   |
| -------- | -------------------------------------- | ----------------------------- |
| `GET`    | `/api/billing/subscription`            | Get current subscription      |
| `POST`   | `/api/billing/subscribe`               | Subscribe to a plan           |
| `PUT`    | `/api/billing/subscription/plan`       | Change plan                   |
| `POST`   | `/api/billing/subscription/cancel`     | Cancel subscription           |
| `POST`   | `/api/billing/subscription/resume`     | Resume cancelled subscription |
| `GET`    | `/api/billing/invoices`                | List invoices                 |
| `GET`    | `/api/billing/invoices/{invoiceId}`    | Get invoice details           |
| `GET`    | `/api/billing/payment-methods`         | List payment methods          |
| `POST`   | `/api/billing/payment-methods`         | Add payment method            |
| `DELETE` | `/api/billing/payment-methods/{pmId}`  | Remove payment method         |
| `POST`   | `/api/billing/payment-methods/default` | Set default payment method    |
| `POST`   | `/api/billing/setup-intent`            | Create Stripe SetupIntent     |
| `GET`    | `/api/billing/credits`                 | Get account credits           |
| `GET`    | `/api/billing/upcoming`                | Preview upcoming charges      |

## Catalog

| Method | Path            | Description             |
| ------ | --------------- | ----------------------- |
| `GET`  | `/api/plans`    | List available plans    |
| `GET`  | `/api/presets`  | List available presets  |
| `GET`  | `/api/regions`  | List available regions  |
| `GET`  | `/api/runtimes` | List available runtimes |