# Pond for AI agents > Pond hosts static websites and files. Add Pond to Claude, ChatGPT or Gemini as a connector to publish sites from a chat, or let agents and scripts use a scoped API token over a small REST API. Human-readable version: https://pond.sh/docs/agents. OpenAPI spec: https://api.pond.sh/api/v1/openapi.json. ## Overview A pond is a website (`type: web`) or a file-sharing space (`type: doc`) at `https://.pond.domains`, optionally on a custom domain. The REST API lets an agent list and create ponds, publish a site from a zip, upload, read and delete single files, turn a site on or off, and check when an upload is live. Two ways in: add Pond to an AI app such as Claude, ChatGPT or Gemini as a connector (below), or give an agent or script an API token for the REST API. The API uses API tokens, never the user’s login. Tokens are scoped, can be limited to chosen ponds, and can be revoked or regenerated (a new secret, same permissions) at any time. They cannot touch billing, account settings or domains. ## Add Pond to Claude, ChatGPT or Gemini Pond is a connector (a remote MCP server) at `https://api.pond.sh/mcp`. Add it once, approve it on pond.sh, and the app can publish the sites it builds straight from a chat. No token to copy. Step-by-step for people using Claude, ChatGPT, Gemini or other AI apps (no code): https://pond.sh/docs/ai-apps. - Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector. Name `Pond`, URL `https://api.pond.sh/mcp`. Then Connect, and approve on pond.sh. - ChatGPT: add a custom connector (in developer mode) with the URL `https://api.pond.sh/mcp` and OAuth sign-in, then approve on pond.sh. - Gemini (gemini.google.com, still rolling out): add a custom connector with the URL `https://api.pond.sh/mcp`, then approve on pond.sh. Gemini CLI: `gemini mcp add --transport http --scope user pond https://api.pond.sh/mcp`, then run `/mcp auth pond` to sign in. - Claude Code: `claude mcp add --transport http pond https://api.pond.sh/mcp`, then run `/mcp` to sign in. - Other MCP clients: Streamable HTTP, with OAuth sign-in or an API token sent as `Authorization: Bearer pond_...`. | Tool | What it does | |---|---| | `pond_site_guide` | Rules for building a site that works on Pond (page links, metadata, sitemap); call before building or restructuring a site | | `pond_list_ponds` | List your ponds and their URLs | | `pond_account` | Your plan, its limits and features, and usage: ponds, live ponds, storage used and left, API uploads today | | `pond_list_plans` | The Free plan (every new account) and the paid plans: limits, features and prices | | `pond_upgrade` | A checkout link for a paid plan: you pay in your browser, never the AI | | `pond_create_pond` | Create a website or file pond (counts against the plan) | | `pond_deploy_site` | Publish a website from its files (text, or base64 for images). Replaces the site unless `merge` is true; returns the live URL | | `pond_upload_file` | Add or replace one file in any pond | | `pond_create_upload_link` | A 30-minute link the app’s code workspace can send real files to (images, PDFs) with `curl`, instead of writing them out as base64 | | `pond_list_files` | List the files in a pond, to see what is live | | `pond_read_file` | Read a page or other text file (up to 512 KB), to edit it | | `pond_delete_files` | Delete files from a pond (the app asks you first) | | `pond_set_site_enabled` | Turn a site on or off; its files are kept | | `pond_set_password` | Password-protect a pond, or remove the password (plans with password protection) | | `pond_job_status` | Check an upload that is still processing | | `pond_list_versions` | A website’s versions: the live one and the earlier ones your plan keeps (every whole-site upload makes one) | | `pond_restore_version` | Put an earlier version back live within seconds; the current one is kept (the app asks you first) | | `pond_list_domains` | A pond’s custom domains: status, what is still missing, and the DNS records each needs | | `pond_add_domain` | Put a pond on your own domain; returns the DNS records to add at your domain provider | | `pond_check_domain` | Check DNS now and finish setting the domain up once the records are in place | | `pond_set_primary_domain` | Make a domain the main address (the others redirect to it) | | `pond_remove_domain` | Remove a custom domain (the app asks you first) | When you approve, you can limit the app to the ponds you choose. The connection shows as “ (connector)” in Settings → API tokens; revoke it there to disconnect. Uploads through the connector are up to 20 MB each; send a bigger site in parts (merge), or use the dashboard uploader. ## Quick start - Ask the user to create a token in Pond: Settings → API tokens. Request only the scopes you need, and ideally limit it to the ponds you will work on. - Keep the token out of files you commit. Read it from an environment variable such as `POND_TOKEN`. ```bash export POND_TOKEN=pond_... # from Settings → API tokens API=https://api.pond.sh/api/v1 # Check the token curl -s -H "Authorization: Bearer $POND_TOKEN" $API/me # Create a website pond (needs ponds:write): my-site.pond.domains curl -s -X POST $API/ponds \ -H "Authorization: Bearer $POND_TOKEN" -H "Content-Type: application/json" \ -d '{"prefix": "my-site", "title": "My site"}' # Publish the site: zip the build folder with index.html at the zip root (cd dist && zip -r ../site.zip .) curl -s -X POST "$API/ponds//deploy" \ -H "Authorization: Bearer $POND_TOKEN" -H "Content-Type: application/zip" \ --data-binary @site.zip # Poll the job until "completed" (its "url" is the live site) or "failed" curl -s -H "Authorization: Bearer $POND_TOKEN" $API/jobs/ ``` Use the pond’s `folder` (from `GET /ponds` or the create response) in URLs, not its prefix. ## Authentication and scopes Send the token on every request: `Authorization: Bearer pond_...`. | Scope | Allows | |---|---| | `ponds:read` | List and view ponds, their files and custom domains, read text files, check upload jobs | | `ponds:write` | Create ponds (counts against the plan), turn them on or off, set passwords | | `sites:publish` | Deploy sites, upload and delete files | | `domains:write` | Add, check, set as main and remove custom domains. You still add the DNS records yourself | A token limited to some ponds only sees those ponds and cannot create ponds (`GET /me` lists them in `token.ponds`; `null` means all ponds). Revoked or expired tokens get `401`; a missing scope gets `403` with code `missing_scope`. ## Endpoints Base URL: `https://api.pond.sh/api/v1`. Full machine-readable spec: `https://api.pond.sh/api/v1/openapi.json`. | Method and path | Scope | What it does | |---|---|---| | `GET /guide` | none | How to build a site for Pond (Markdown; same rules as `pond_site_guide`) | | `GET /me` | any | Token owner, scopes, whether uploads are open | | `GET /account` | `ponds:read` | Plan (`free`: on the Free plan; `cancels_at`: a cancelled plan runs until then), limits (`null` = unlimited), features, and usage: ponds, storage used and left, API uploads today | | `GET /plans` | `ponds:read` | The Free plan and the paid plans: limits, features, monthly/yearly prices; `current` marks the account’s | | `POST /account/upgrade` | `ponds:write` | Body `{"plan": "Lake", "billing": "monthly"}`: a Stripe checkout link for the person to pay in their browser (`change_plan` and the billing page if they already pay or a payment failed). Errors: `already_free`, `invalid_plan`, `unknown_plan`, `invalid_billing`, `invalid_body`, `managed`; report `billing_error` and `billing_unavailable` to the user rather than retrying | | `GET /ponds?tag=…` | `ponds:read` | List ponds (each with the tags the user gave it); `tag` (optional) lists only the ponds in that tag | | `POST /ponds` | `ponds:write` | Create a pond: `{"prefix"?, "type": "web"|"doc", "title"?, "tags"?}` (prefix: 6 to 63 letters, numbers and hyphens; none: a random available name such as `calm-silver-heron`; tags: names of the user’s existing tags, an unknown one gets `tag_not_found`) | | `GET /ponds/{folder}` | `ponds:read` | One pond | | `PATCH /ponds/{folder}` | `ponds:write` | Turn the site on or off: `{"enabled": true|false}`. Password-protect it: `{"password": "..."}`, or `null` to remove (plans with password protection) | | `POST /ponds/{folder}/deploy` | `sites:publish` | Publish a website from a zip. `?mode=replace` (default) replaces the site; `?mode=merge` only adds and overwrites | | `POST /ponds/{folder}/files?path=dir/name.ext` | `sites:publish` | Add or replace one file (any pond type) | | `POST /ponds/{folder}/upload-link` | `sites:publish` | A link that takes uploads for this pond for 30 minutes without a token: `POST {upload_url}?path=dir/name.ext` with the file (multipart `file` or raw body). Any number of files; revoking the token stops it | | `GET /ponds/{folder}/files` | `ponds:read` | List files: `?under=folder`, `?search=name`, `?offset=` and `?limit=` (up to 500) | | `GET /ponds/{folder}/files/content?path=…` | `ponds:read` | A text file’s content as JSON (up to 512 KB), to edit it | | `DELETE /ponds/{folder}/files?path=…` | `sites:publish` | Delete one file from the live pond | | `GET /ponds/{folder}/versions` | `ponds:read` | The website’s versions, newest first: each with `id`, `live`, `kind` (`upload`, or `nightly`: a restore point of single-file changes made that day), `published_at`, `files`, `size_bytes`; `kept` and `restore_points_kept` are how many of each the plan keeps (0 on free plans) | | `POST /ponds/{folder}/versions/{id}/restore` | `sites:publish` | Serve an earlier version again (live within seconds; the current one is kept). `pond_busy` while an upload is being published: try again shortly | | `GET /ponds/{folder}/domains` | `ponds:read` | Custom domains, each with `status` (pending, active, failed), `message` (what is missing) and `dns_records` | | `POST /ponds/{folder}/domains` | `domains:write` | Add a domain: `{"domain": "www.example.com"}`. A bare domain (`example.com`) also adds www and redirects to it, unless `"serve_bare": true`. Returns the DNS records to add | | `POST /ponds/{folder}/domains/{domain}/check` | `domains:write` | Check DNS now and finish setup once the records are in place (spaced out per domain: `retry_too_soon`) | | `PATCH /ponds/{folder}/domains/{domain}` | `domains:write` | Make it the main address: `{"primary": true}` | | `DELETE /ponds/{folder}/domains/{domain}` | `domains:write` | Remove the domain; the site stays on its pond.domains address | | `GET /jobs/{id}` | `ponds:read` | Upload status: queued, processing, completed (with `url`) or failed (with `error`) | Uploads take the raw file as the body (`Content-Type: application/zip` or `application/octet-stream`) or a multipart field named `file`. They return `202` with a job; processing usually takes seconds, longer for big sites. ## Limits and errors - 50 MB per upload through the API. The limit is per upload: one-file uploads and `mode=merge` deploys keep the rest of the pond, so a bigger site can go up in several uploads. A single file over 50 MB: the dashboard uploader. Per account: 10 uploads a minute, 5 publishing at once, 2 GB a day; an upload that can't fit in the account's storage gets 413 `storage_full`. All limits: https://pond.sh/docs/limits. - Plan limits apply as in the dashboard: number of ponds, how many can be live at once (turning one on past it gets 403 `live_pond_limit`) and total storage. - File types: free plans can upload web files, images, fonts, media and common documents; paid plans anything except programs and scripts (e.g. `.exe`, `.vbs`). A refused file fails the upload with code `file_type_not_allowed`, or a failed job naming the files. - 120 requests a minute per token (`429` when exceeded). - Pond can pause uploads during maintenance: `503` with code `uploads_paused`. Try again later. Errors are JSON with a stable `code` and a message you can show the user: ```json {"error": {"code": "pond_limit", "message": "The Free plan allows 1 pond. Upgrade at pond.sh/settings/billing (or ask your AI app to upgrade with Pond)."}} ``` ## Guidance for agents - Never ask the user for their password, login link or session token. Ask them to create an API token instead. - Ask before replacing a live site (`mode=replace` removes files not in the zip), deleting files, removing a domain, turning a site off or creating ponds that count against their plan. - Pond cannot change DNS. After adding a domain, show the user each record from `dns_records` (type, name, value) and where to add it, then check the domain once they have. - To change a live site, list its files and read the pages you will edit first, then send only the changed files with `mode=merge`, so nothing else is lost. - Before building or restructuring a website, call `pond_site_guide` (or fetch `GET /guide`) and follow its page link (`about/index.html` linked as `/about/`, never `.html`), metadata and sitemap rules. - Put `index.html` at the root of the zip, not inside a folder. - After deploying, poll `GET /jobs/{id}` every few seconds and give the user the `url` when it is completed, or the `error` if it failed. - If a request fails with `uploads_paused`, `custom_domains_paused`, `maintenance`, `pond_limit`, `live_pond_limit`, `domain_taken`, `plan_feature` (not in the user’s plan, e.g. custom domains on Free), `tag_not_found`, `billing_error`, `billing_unavailable` or a storage error, tell the user; do not retry in a loop. New tags are made in the dashboard. For a plan limit, offer `pond_list_plans` / `pond_upgrade` (or `GET /plans` and `POST /account/upgrade`): the user pays through the link themselves.