> ## 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"
```

For anything unattended, use an **API token**. Create one in the dashboard under **Settings → API Tokens**; it starts with `ipk_`, is shown only once, and doesn't expire unless you give it an expiry. It is bound to the team that was active when you created it, so it always acts on the same team.

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

You can also obtain a short-lived session 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"}'
```

Manage API tokens over the API too:

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/api-tokens` | List your tokens (metadata only) |
| `POST` | `/api/api-tokens` | Create a token - returns the raw value once |
| `DELETE` | `/api/api-tokens/{id}` | Revoke a token |

### 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**](/api-reference/pods) | Create, start, stop, restart, reload, resize, clone, delete, convert to a worker |
| **Deploy from source** | Detect a repo, deploy from a repo, deploy or re-upload a project ZIP |
| [**Imports**](/api-reference/imports) | Create a pod from a live URL, an AI artifact, or pasted source |
| **Backups** | List, create, restore, download, import, and schedule pod backups |
| **1-Click Apps** | Catalog, per-pod setup variables, update, start, stop |
| **Transfers** | Offer a pod to another account, accept or decline an offer |
| [**Files**](/api-reference/files) | List, read, write, upload, download, rename, copy, delete, mkdir, sync |
| [**SSH keys**](/api-reference/ssh-keys) | Connection info, key management (per-pod and account-level) |
| **Domains** | Custom domain mapping with DNS verification |
| [**Services**](/api-reference/services) | Install and manage MySQL, PostgreSQL, Redis |
| **Environment & exec** | Read and write env vars, run a command inside a pod |
| **Logs & Metrics** | Application logs, events, resource metrics |
| **AI agents** | Install Claude Code, Codex, Aider or OpenCode inside a pod |
| [**Git**](/api-reference/git) | Connect a repo, deploy, roll back, GitHub App installations |
| [**Feedback**](/api-reference/feedback) | The in-page comment widget and its moderation |
| [**Teams**](/api-reference/teams) | Team CRUD, member management, invitations |
| [**Billing**](/api-reference/billing) | Subscriptions, invoices, payment methods, credits |
| [**API tokens**](/api-reference/api-tokens) | Long-lived `ipk_` credentials for CI and automation |
| [**Affiliate**](/api-reference/affiliate) | Enrollment, referrals, earnings, payouts |
| **Account** | Active sessions, self-service account deletion |
| **Catalog** | Plans, presets, regions, runtimes, apps, agents |

***

## 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 |
| `GET` | `/api/auth/providers` | Which sign-in providers are enabled on this deployment |

## 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 |
| `POST` | `/api/pods/{name}/kind` | Convert between a web pod and a [worker pod](/guides/worker-pods) |
| `POST` | `/api/pods/{name}/apply-fix` | Apply the [Deploy Doctor](/support/troubleshooting#deploy-doctor) fix for the pod's current diagnosis |
| `POST` | `/api/pods/{name}/node-version` | Switch a Node.js pod to another Node major in place |
| `GET` | `/api/pods/{name}/preset` | Get pod's preset config |
| `GET` | `/api/pods/{name}/disk-usage` | Get pod disk usage |
| `POST` | `/api/pods/{name}/exec` | Run a command inside the pod |

## Environment Variables

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/pods/{name}/env` | Read the pod's environment variables |
| `PUT` | `/api/pods/{name}/env` | Set variables (merges into the existing file) |
| `DELETE` | `/api/pods/{name}/env` | Unset variables by key |

## Imports

See [Import an existing app](/guides/import-existing-app).

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/imports` | Create a pod from a live URL, an AI artifact, or pasted source |
| `GET` | `/api/imports/sources` | The import catalog: routes in, guided platforms, what each carries |

## AI Agents

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/agents` | List installable coding agents |
| `GET` | `/api/pods/{name}/agents` | List agents installed in a pod |
| `POST` | `/api/pods/{name}/agents` | Install an agent |
| `DELETE` | `/api/pods/{name}/agents/{agentType}` | Remove an agent |

## Deploy from source

Create a pod straight from a repository or an uploaded project. See
[Git Deployment](/guides/git-deployment) and [Import an existing app](/guides/import-existing-app).

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/repos/detect` | Inspect a GitHub repo and report the runtime and plan we would use. No side effects |
| `POST` | `/api/repos/analyze` | Full deploy plan for a repo: install/build/start/release commands, services, env vars |
| `POST` | `/api/pods/from-repo` | Create a pod for a repo, attach it, and deploy on boot |
| `POST` | `/api/pods/from-zip` | Create a pod from an uploaded project `.zip` (multipart) |
| `POST` | `/api/pods/{name}/from-zip` | Replace an uploaded pod's source with a new `.zip` and rebuild in place |

## Backups

See [Backups](/dashboard/backups) for what is captured and how retention works.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/pods/{name}/backups` | List backups |
| `POST` | `/api/pods/{name}/backups` | Take a backup now |
| `GET` | `/api/pods/{name}/backups/{backupId}` | Get one backup |
| `DELETE` | `/api/pods/{name}/backups/{backupId}` | Delete a backup |
| `POST` | `/api/pods/{name}/backups/{backupId}/restore` | Restore from a backup |
| `GET` | `/api/pods/{name}/backups/{backupId}/download` | Download the archive |
| `POST` | `/api/pods/{name}/backups/import` | Upload an archive as a new backup |
| `GET` | `/api/pods/{name}/backups/schedule` | Get the automatic schedule |
| `PUT` | `/api/pods/{name}/backups/schedule` | Change or disable the schedule |

## Ownership transfer

See [Transfer a Pod](/guides/transfer-a-pod).

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/pods/{name}/transfer` | Offer the pod to another account |
| `GET` | `/api/pods/{name}/transfer` | Get the pod's pending offer |
| `DELETE` | `/api/pods/{name}/transfer` | Withdraw the pending offer |
| `GET` | `/api/pod-transfers` | List offers addressed to you |
| `POST` | `/api/pod-transfers/{id}/accept` | Accept an offer |
| `POST` | `/api/pod-transfers/{id}/decline` | Decline an offer |

## 1-Click Apps

See [1-Click Apps](/guides/one-click-apps).

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/apps` | List the app catalog |
| `GET` | `/api/pods/{name}/apps` | List apps installed in a pod |
| `GET` | `/api/pods/{name}/apps/{appType}` | Get one installed app |
| `GET` | `/api/pods/{name}/apps/{appType}/credentials` | Get the logins the app generated for this pod |
| `GET` | `/api/pods/{name}/apps/{appType}/setup` | Get the app's setup variables and whether setup is complete |
| `POST` | `/api/pods/{name}/apps/{appType}/setup` | Save setup values and restart the app |
| `POST` | `/api/pods/{name}/apps/{appType}/update` | Update the app to its latest version |
| `POST` | `/api/pods/{name}/apps/{appType}/start` | Start a stopped app |
| `POST` | `/api/pods/{name}/apps/{appType}/stop` | Stop a running app |

## 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 |
| `GET` | `/api/pods/{name}/files/manifest` | Recursive listing with sizes, for incremental sync |
| `POST` | `/api/pods/{name}/files/hashes` | SHA-256 of specific files, for incremental sync |
| `POST` | `/api/pods/{name}/files/upload-archive` | Upload and extract a `.tar.gz` in one request |

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

## Git

See [Git](/api-reference/git).

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/pods/{name}/git` | Get the pod's Git config |
| `POST` | `/api/pods/{name}/git` | Connect a repository |
| `PUT` | `/api/pods/{name}/git` | Update branch, commands or auto-deploy |
| `DELETE` | `/api/pods/{name}/git` | Disconnect the repository |
| `POST` | `/api/pods/{name}/git/deploy` | Trigger a deploy |
| `POST` | `/api/pods/{name}/git/webhook` | Repair a broken auto-deploy webhook |
| `GET` | `/api/pods/{name}/git/deployments` | List deployments |
| `GET` | `/api/pods/{name}/git/deployments/{deployId}` | Get one deployment |
| `POST` | `/api/pods/{name}/git/rollback` | Roll back to the previous deployment |
| `GET` | `/api/github/installations` | List your GitHub App installations |
| `GET` | `/api/github/installations/{installationId}/repos` | Repos visible to an installation |
| `POST` | `/api/github/repos` | Create a repository on your GitHub account |

## Feedback

See [Feedback](/api-reference/feedback).

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/pods/{name}/feedback` | List comments left on the pod |
| `POST` | `/api/pods/{name}/feedback/settings` | Turn collection on/off and set visibility |
| `PATCH` | `/api/pods/{name}/feedback/{id}` | Resolve or edit one comment |
| `DELETE` | `/api/pods/{name}/feedback/{id}` | Delete one comment |
| `POST` | `/api/feedback/{token}` | Submit feedback from the widget (public) |
| `GET` | `/api/feedback/{token}/mine` | A submitter's own comments (public) |

## 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 |
| `GET` | `/api/teams/{id}/members/details` | List members with their names and emails |
| `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 |
| `GET` | `/api/invitations/{token}` | Look up an invitation before signing up (public) |
| `POST` | `/api/invitations/accept` | Accept an invitation, signing up in the same call if needed |

## 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/open` | List unpaid invoices only |
| `GET` | `/api/billing/invoices/{invoiceId}` | Get invoice details |
| `POST` | `/api/billing/invoices/{invoiceId}/pay` | Charge the default card for an open invoice now |
| `GET` | `/api/billing/payment-methods` | List payment methods |
| `POST` | `/api/billing/payment-methods` | Add payment method |
| `GET` | `/api/billing/payment-methods/other-teams` | Cards on your other teams, to reuse one |
| `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 |

## Account

See [Account Settings](/dashboard/account-settings).

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/account/sessions` | List your live sessions (tokens are never returned) |
| `DELETE` | `/api/account/sessions/{sessionId}` | Revoke one of your sessions |
| `GET` | `/api/account/deletion-preview` | What deleting your account would destroy, and what blocks it |
| `POST` | `/api/account/delete` | Permanently delete your account and every pod you own |

## Affiliate

See [Affiliate Program](/api-reference/affiliate).

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/affiliates/enroll` | Join the affiliate program |
| `GET` | `/api/affiliates/dashboard` | Tier, progress, balance, and your referral links |
| `GET` | `/api/affiliates/referrals` | People who signed up through your link |
| `GET` | `/api/affiliates/earnings` | Commission per qualifying payment |
| `GET` | `/api/affiliates/payouts` | Payouts we've sent you |
| `PUT` | `/api/affiliates/settings` | PayPal email and custom referral slug |
| `POST` | `/api/affiliate/visit` | Record a click on a referral code (public) |

## 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 |
| `GET` | `/api/apps` | List the 1-Click App catalog |
| `GET` | `/api/agents` | List installable AI coding agents |

## Public

No authentication required.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/public/apps` | The 1-Click App catalog |
| `GET` | `/api/public/changelog` | Published release notes, newest first |
| `GET` | `/api/public/trial` | Whether cardless [trial pods](/mcp/trial) are currently on |

## What's New

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/changelog/unseen` | Release notes published since you last dismissed them |
| `POST` | `/api/changelog/seen` | Mark them read, so the dashboard stops showing the badge |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.