API Overview - InstaPods

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:

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.

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:

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

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:

{
  "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`, `/api/pods/from-repo`, `/api/pods/from-image`, `/api/pods/from-zip`	50/hour per IP, shared across the four
`POST /api/repos/detect`	60/hour per IP
`POST /api/repos/analyze`	30/hour per IP
`POST /api/pods/{name}/transfer`	10/hour per IP
`POST /api/imports`	20/hour per IP

Per-pod concurrency

Three routes are also limited by how many requests one pod is serving at the same moment, not by how many you send per minute:

Endpoint	In flight per pod
`GET /api/pods/{name}/files/content`	4
`GET /api/pods/{name}/files/download`	4
`POST /api/pods/{name}/exec`	8

An HTTP request over the limit gets 429 with Retry-After: 1 straight away - it is not queued (the MCP tools wait up to 5 seconds for a slot before giving up). Wait for the ones in progress to finish, then send it again. The count is shared by everything that reaches the pod: the dashboard, the Web IDE, the CLI, the API and the MCP tools. A long-running command or a slow download holds its place until it ends.

Per-pod concurrency

Three routes are also limited by how many requests one pod is serving at the same moment, not by how many you send per minute:

Endpoint	In flight per pod
`GET /api/pods/{name}/files/content`	4
`GET /api/pods/{name}/files/download`	4
`POST /api/pods/{name}/exec`	8

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, convert to a worker
Deploy from source	Detect a repo, deploy from a repo, deploy or re-upload a project ZIP
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	List, read, write, upload, download, rename, copy, delete, mkdir, sync
SSH keys	Connection info, key management (per-pod and account-level)
Domains	Custom domain mapping with DNS verification
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	Connect a repo, deploy, roll back, GitHub App installations
Feedback	The in-page comment widget and its moderation
Teams	Team CRUD, member management, invitations
Billing	Subscriptions, invoices, payment methods, credits
API tokens	Long-lived `ipk_` credentials for CI and automation
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
`POST`	`/api/pods/{name}/apply-fix`	Apply the 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.

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 and Import an 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 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.

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.

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.

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.

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.

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.

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

​Base URL

​Authentication

​Bearer Token

​Session Cookie

​Request Format

​Error Responses

​Rate Limits

​Per-pod concurrency

​Per-pod concurrency

​Available Endpoints

​Authentication

​Pods

​Environment Variables

​Imports

​AI Agents

​Deploy from source

​Backups

​Ownership transfer

​1-Click Apps

​Files

​SSH

​Domains

​Git

​Feedback

​Services

​Logs & Metrics

​Teams

​Billing

​Account

​Affiliate

​Catalog

​Public

​What’s New

Base URL

Authentication

Bearer Token

Session Cookie

Request Format

Error Responses

Rate Limits

Per-pod concurrency

Per-pod concurrency

Available Endpoints

Authentication

Pods

Environment Variables

Imports

AI Agents

Deploy from source

Backups

Ownership transfer

1-Click Apps

Files

SSH

Domains

Git

Feedback

Services

Logs & Metrics

Teams

Billing

Account

Affiliate

Catalog

Public

What’s New