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.
- Claude
- ChatGPT
- Gemini
- Cursor
- Copilot
- Claude Code
- VS Code
- Windsurf
- Model Context Protocol
Overview
A pond is a website (type: web) or a file-sharing space (type: doc) at https://<prefix>.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, URLhttps://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/mcpand 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 pondto sign in. - Claude Code:
claude mcp add --transport http pond https://api.pond.sh/mcp, then run/mcpto 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 “<app> (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.
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/<folder>/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/<job id>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=mergedeploys 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 413storage_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 codefile_type_not_allowed, or a failed job naming the files. - 120 requests a minute per token (
429when exceeded). - Pond can pause uploads during maintenance:
503with codeuploads_paused. Try again later.
Errors are JSON with a stable code and a message you can show the user:
{"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=replaceremoves 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 fetchGET /guide) and follow its page link (about/index.htmllinked as/about/, never.html), metadata and sitemap rules. - Put
index.htmlat the root of the zip, not inside a folder. - After deploying, poll
GET /jobs/{id}every few seconds and give the user theurlwhen it is completed, or theerrorif 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_unavailableor a storage error, tell the user; do not retry in a loop. New tags are made in the dashboard. For a plan limit, offerpond_list_plans/pond_upgrade(orGET /plansandPOST /account/upgrade): the user pays through the link themselves.
Agents: the same guide is at /llms-full.txt and indexed in /llms.txt.