{"openapi": "3.1.0", "info": {"title": "Pond API", "version": "1", "description": "Create ponds (sites at <prefix>.pond.domains) and publish files to them. Authenticate with an API token from Settings > API tokens: \"Authorization: Bearer pond_...\". Uploads are processed in the background: poll the returned job until it is completed or failed. Max 50 MB per request."}, "servers": [{"url": "https://api.pond.sh/api/v1"}], "security": [{"token": []}], "components": {"securitySchemes": {"token": {"type": "http", "scheme": "bearer", "description": "pond_... API token"}}, "schemas": {"Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}, "Pond": {"type": "object", "properties": {"folder": {"type": "string", "description": "Identifier used in URLs below"}, "prefix": {"type": "string"}, "title": {"type": ["string", "null"]}, "type": {"type": "string", "enum": ["web", "doc"]}, "url": {"type": "string", "format": "uri"}, "live_url": {"type": "string", "format": "uri", "description": "Where visitors end up (the live primary custom domain, else url): use it in canonical links and sitemaps"}, "hide_html_extension": {"type": "boolean", "description": "When true, sub-pages built as folders (about/index.html) do not load"}, "enabled": {"type": "boolean"}, "password_protected": {"type": "boolean"}, "size_bytes": {"type": "integer"}, "upload_status": {"type": "string", "enum": ["idle", "processing", "failed"]}, "created_at": {"type": "string", "format": "date-time"}, "tags": {"type": "array", "items": {"type": "string"}, "description": "The owner's tags (set in the dashboard; read-only here)"}}}, "Job": {"type": "object", "properties": {"id": {"type": "integer"}, "pond": {"type": "string"}, "status": {"type": "string", "enum": ["queued", "processing", "completed", "failed"]}, "error": {"type": "string", "description": "When failed"}, "url": {"type": "string", "format": "uri", "description": "When completed"}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}}}, "Versions": {"type": "object", "properties": {"pond": {"type": "string"}, "kept": {"type": "integer", "description": "Earlier versions this account keeps (0 on free plans); older ones are removed shortly after each new upload"}, "restore_points_kept": {"type": "integer", "description": "Nightly restore points kept: copies of the site taken at night after single files were added, changed or deleted that day (0 when off or on free plans)"}, "versions": {"type": "array", "description": "Live first, then earlier ones, newest first", "items": {"type": "object", "properties": {"id": {"type": "string"}, "live": {"type": "boolean"}, "kind": {"type": "string", "enum": ["upload", "nightly"], "description": "upload: a deploy that replaced the site; nightly: a restore point of single-file changes made that day"}, "published_at": {"type": "string", "format": "date-time"}, "files": {"type": "integer"}, "size_bytes": {"type": "integer"}}}}}}, "Domain": {"type": "object", "properties": {"domain": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "active", "failed"]}, "message": {"type": ["string", "null"], "description": "What is still missing (e.g. which DNS record to add); null once active"}, "primary": {"type": "boolean", "description": "The pond's main address"}, "redirect_only": {"type": "boolean", "description": "A bare domain that only redirects to its www address"}, "redirect_to": {"type": ["string", "null"]}, "ownership_verified": {"type": "boolean", "description": "The optional TXT record was found"}, "dns_records": {"type": "array", "description": "Records the owner adds at their DNS provider (Pond cannot change DNS)", "items": {"type": "object", "properties": {"type": {"type": "string", "enum": ["CNAME", "A", "TXT"]}, "name": {"type": "string"}, "value": {"type": "string"}, "purpose": {"type": "string"}, "required": {"type": "boolean"}}}}, "created_at": {"type": "string", "format": "date-time"}}}, "Account": {"type": "object", "description": "Limits that are null are unlimited.", "properties": {"email": {"type": "string"}, "plan": {"type": "object", "properties": {"name": {"type": ["string", "null"], "description": "null: no plan"}, "managed": {"type": "boolean", "description": "Managed by Pond: no plan limits"}, "status": {"type": ["string", "null"], "description": "Subscription status (active, trialing, past_due, unpaid...); null without a paid subscription"}, "free": {"type": "boolean", "description": "On the Free plan (no paid subscription): see /plans and /account/upgrade"}, "cancels_at": {"type": ["string", "null"], "format": "date-time", "description": "A cancelled paid plan runs until then, then Free"}, "ended_at": {"type": ["string", "null"], "format": "date-time", "description": "When a paid plan ended; the Free plan limits then apply"}, "downgraded_at": {"type": ["string", "null"], "format": "date-time", "description": "When the account moved to its current plan, which allows fewer live ponds than the one before; live ponds over the limit may be switched off after a grace period"}}}, "limits": {"type": "object", "properties": {"ponds": {"type": ["integer", "null"]}, "storage_bytes": {"type": ["integer", "null"], "description": "All ponds together"}, "api_upload_bytes": {"type": "integer", "description": "Largest upload through the API"}, "api_upload_bytes_per_day": {"type": ["integer", "null"]}}}, "features": {"type": "object", "properties": {"password_protection": {"type": "boolean"}, "custom_404": {"type": "boolean"}, "analytics": {"type": "boolean"}}}, "usage": {"type": "object", "properties": {"ponds": {"type": "integer"}, "live_ponds": {"type": "integer"}, "storage_bytes": {"type": "integer"}, "storage_free_bytes": {"type": ["integer", "null"]}, "storage_percent": {"type": ["number", "null"]}, "api_uploaded_today_bytes": {"type": "integer"}}}, "uploads_open": {"type": "boolean"}}}}}, "paths": {"/guide": {"get": {"summary": "How to build a site for Pond (Markdown; no token needed). Read it before building.", "operationId": "getSiteGuide", "security": [], "responses": {"200": {"description": "The guide", "content": {"text/markdown": {}}}}}}, "/me": {"get": {"summary": "Who the token belongs to, its scopes, and whether uploads are open", "operationId": "getMe", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/account": {"get": {"summary": "The account's plan, limits, features and usage (scope ponds:read). Account-wide totals, also for a token limited to some ponds", "operationId": "getAccount", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Account"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/plans": {"get": {"summary": "The Free plan and the paid plans: limits, features, prices (scope ponds:read)", "description": "Every account without a paid plan is on Free (no card). Free comes first; 'current' marks the account's plan.", "operationId": "listPlans", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"managed": {"type": "boolean"}, "billing_page": {"type": "string"}, "plans": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string"}, "free": {"type": "boolean"}, "current": {"type": "boolean", "description": "The account's plan"}, "limits": {"type": "object", "description": "null means unlimited", "properties": {"ponds": {"type": ["integer", "null"]}, "storage_bytes": {"type": ["integer", "null"]}}}, "features": {"type": "object", "additionalProperties": {"type": "boolean"}}, "prices": {"type": "array", "items": {"type": "object", "properties": {"billing": {"type": "string", "enum": ["monthly", "yearly"]}, "amount": {"type": "number"}, "currency": {"type": "string"}}}}}}}}}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/account/upgrade": {"post": {"summary": "A checkout link for a paid plan (scope ponds:write)", "description": "The person opens the link and pays in their browser; the plan applies when the payment goes through. An account that already pays, or has a subscription suspended after a failed payment, gets 'change_plan' and the billing page instead. Errors: already_free (asked for Free), invalid_plan (no plan name), unknown_plan, invalid_billing, invalid_body, managed; report billing_error and billing_unavailable to the person rather than retrying.", "operationId": "upgrade", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["plan"], "properties": {"plan": {"type": "string", "description": "A paid plan name, e.g. Lake"}, "billing": {"type": "string", "enum": ["monthly", "yearly"]}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"action": {"type": "string", "enum": ["checkout", "change_plan"]}, "url": {"type": "string"}, "plan": {"type": "string"}, "billing": {"type": "string"}, "amount": {"type": "number"}, "currency": {"type": "string"}, "message": {"type": "string"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "An upload is being published to the pond, the domain is already in use, or the pond is off", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds": {"get": {"summary": "List ponds (scope ponds:read)", "operationId": "listPonds", "parameters": [{"name": "tag", "in": "query", "schema": {"type": "string"}, "description": "Only ponds with this tag (its name, any case), e.g. Acme"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"ponds": {"type": "array", "items": {"$ref": "#/components/schemas/Pond"}}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"summary": "Create a pond (scope ponds:write; counts against the plan)", "operationId": "createPond", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"prefix": {"type": "string", "description": "Address: \"my-site\" -> my-site.pond.domains. 6-63 letters, numbers, hyphens. Leave out for a random available name (e.g. \"calm-silver-heron\")."}, "type": {"type": "string", "enum": ["web", "doc"], "default": "web"}, "title": {"type": "string"}, "description": {"type": "string"}, "tags": {"type": "array", "items": {"type": "string"}, "description": "Names of your existing tags to put the pond in (tags are made in the dashboard); an unknown name is refused with tag_not_found."}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "properties": {"pond": {"$ref": "#/components/schemas/Pond"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}": {"get": {"summary": "Get one pond (scope ponds:read)", "operationId": "getPond", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"pond": {"$ref": "#/components/schemas/Pond"}}}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "patch": {"summary": "Turn the pond on or off, or password-protect it (scope ponds:write)", "description": "Send either or both. An \"off\" pond keeps its files but its site stops being served. \"password\" (4 to 128 characters) protects the pond; null removes the protection. Password protection needs a plan that includes it (403 plan_feature otherwise).", "operationId": "setPondEnabled", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"enabled": {"type": "boolean"}, "password": {"type": ["string", "null"], "minLength": 4, "maxLength": 128}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"pond": {"$ref": "#/components/schemas/Pond"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/deploy": {"post": {"summary": "Publish a website from a zip (scope sites:publish)", "description": "index.html at the zip root. mode=replace (default) replaces the whole site; mode=merge adds and overwrites files only. Website ponds only.", "operationId": "deploySite", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "mode", "in": "query", "schema": {"type": "string", "enum": ["replace", "merge"], "default": "replace"}}], "requestBody": {"required": true, "content": {"application/zip": {"schema": {"type": "string", "format": "binary"}}, "application/octet-stream": {"schema": {"type": "string", "format": "binary"}}, "multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"type": "string", "format": "binary"}}}}}}, "responses": {"202": {"description": "Accepted: poll the job", "content": {"application/json": {"schema": {"type": "object", "properties": {"job": {"$ref": "#/components/schemas/Job"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/versions": {"get": {"summary": "A website's versions (scope ponds:read): every \"replace site\" upload makes a new one; the live one and the earlier ones the account keeps, newest first", "operationId": "listVersions", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}], "responses": {"200": {"description": "Versions (error code: not_a_website for a document pond)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Versions"}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/versions/{version}/restore": {"post": {"summary": "Serve an earlier version again (scope sites:publish). No files are copied: visitors see it within seconds, and the current version is kept so it can be restored back.", "operationId": "restoreVersion", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "version", "in": "path", "required": true, "schema": {"type": "string"}, "description": "A version id from GET /ponds/{folder}/versions"}], "responses": {"200": {"description": "Restored (error codes: version_not_found, not_a_website, pond_busy while an upload is being published: try again shortly, maintenance)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Versions"}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "An upload is being published to the pond, the domain is already in use, or the pond is off", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/domains": {"get": {"summary": "The pond's custom domains, each with its status and DNS records (scope ponds:read)", "operationId": "listDomains", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"domains": {"type": "array", "items": {"$ref": "#/components/schemas/Domain"}}}}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"summary": "Add a custom domain (scope domains:write). A bare domain (example.com) also adds www and redirects to it unless serve_bare. The reply lists the DNS records to add at the provider. A plan without custom domains gets 403 plan_feature.", "operationId": "addDomain", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["domain"], "properties": {"domain": {"type": "string", "description": "e.g. www.example.com"}, "serve_bare": {"type": "boolean", "description": "Serve a bare domain itself (needs CNAME flattening or ALIAS at the DNS provider) instead of redirecting it to www"}}}}}}, "responses": {"201": {"description": "Added (error codes: invalid_domain, domain_taken, custom_domains_paused)", "content": {"application/json": {"schema": {"type": "object", "properties": {"domains": {"type": "array", "items": {"$ref": "#/components/schemas/Domain"}}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "An upload is being published to the pond, the domain is already in use, or the pond is off", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/domains/{domain}": {"get": {"summary": "One custom domain (scope ponds:read)", "operationId": "getDomain", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "domain", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The custom domain, e.g. www.example.com"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"$ref": "#/components/schemas/Domain"}}}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "patch": {"summary": "Make it the main address with {\"primary\": true} (scope domains:write): the other addresses redirect to it. A redirect-only bare domain cannot be (apex_not_primary).", "operationId": "setPrimaryDomain", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "domain", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The custom domain, e.g. www.example.com"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"primary": {"type": "boolean"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"$ref": "#/components/schemas/Domain"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "delete": {"summary": "Remove the domain (scope domains:write); the site stays on its pond.domains address", "operationId": "removeDomain", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "domain", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The custom domain, e.g. www.example.com"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/domains/{domain}/check": {"post": {"summary": "Check DNS now and finish setup if the records are in place (scope domains:write). Spaced out per domain (retry_too_soon); the pond must be on (pond_disabled).", "operationId": "checkDomain", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "domain", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The custom domain, e.g. www.example.com"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"$ref": "#/components/schemas/Domain"}}}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "An upload is being published to the pond, the domain is already in use, or the pond is off", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/files": {"get": {"summary": "List the files in a pond (scope ponds:read)", "operationId": "listFiles", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "under", "in": "query", "schema": {"type": "string"}, "description": "Only this folder"}, {"name": "search", "in": "query", "schema": {"type": "string"}, "description": "File name contains"}, {"name": "offset", "in": "query", "schema": {"type": "integer", "default": 0}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 200, "maximum": 500}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"total": {"type": "integer"}, "more": {"type": "boolean"}, "files": {"type": "array", "items": {"type": "object", "properties": {"path": {"type": "string"}, "size_bytes": {"type": "integer"}, "modified": {"type": ["string", "null"], "format": "date-time"}}}}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "delete": {"summary": "Delete one file from the live pond (scope sites:publish)", "operationId": "deleteFile", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "path", "in": "query", "required": true, "schema": {"type": "string"}, "description": "The file in the pond, e.g. about/index.html"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"deleted": {"type": "boolean"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "An upload is being published to the pond, the domain is already in use, or the pond is off", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"summary": "Add or replace one file (scope sites:publish)", "operationId": "uploadFile", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "path", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Where to put it, e.g. docs/report.pdf"}], "requestBody": {"required": true, "content": {"application/zip": {"schema": {"type": "string", "format": "binary"}}, "application/octet-stream": {"schema": {"type": "string", "format": "binary"}}, "multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"type": "string", "format": "binary"}}}}}}, "responses": {"202": {"description": "Accepted: poll the job", "content": {"application/json": {"schema": {"type": "object", "properties": {"job": {"$ref": "#/components/schemas/Job"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/upload-link": {"post": {"summary": "Get a 30-minute upload link for this pond (scope sites:publish)", "description": "For code that has the files but should not hold an API token, such as the code workspace of an AI app: POST files to the returned upload_url (see uploadWithLink). Any number of files while it is valid; only this pond. Revoking the token that made it stops the link.", "operationId": "createUploadLink", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"upload_url": {"type": "string"}, "pond": {"type": "string"}, "expires_at": {"type": "string", "format": "date-time"}, "how": {"type": "string"}}}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/upload/{link}": {"post": {"summary": "Add or replace one file through an upload link (no token)", "description": "The same as uploadFile, authorised by the link instead of a token. Path in ?path= or a multipart \"path\" field. 410 once the link has expired.", "operationId": "uploadWithLink", "security": [], "parameters": [{"name": "link", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "path", "in": "query", "schema": {"type": "string"}, "description": "Where to put it, e.g. images/page-01.jpg"}], "requestBody": {"required": true, "content": {"application/zip": {"schema": {"type": "string", "format": "binary"}}, "application/octet-stream": {"schema": {"type": "string", "format": "binary"}}, "multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"type": "string", "format": "binary"}}}}}}, "responses": {"202": {"description": "Accepted", "content": {"application/json": {"schema": {"type": "object", "properties": {"job": {"$ref": "#/components/schemas/Job"}, "path": {"type": "string"}, "url": {"type": "string"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "410": {"description": "The upload link has expired: ask for a new one", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/ponds/{folder}/files/content": {"get": {"summary": "A text file's content, to edit it (scope ponds:read)", "description": "Pages, styles, scripts and other text up to 512 KB, as JSON {\"path\", \"content\"}.", "operationId": "readFile", "parameters": [{"name": "folder", "in": "path", "required": true, "schema": {"type": "string"}, "description": "From GET /ponds"}, {"name": "path", "in": "query", "required": true, "schema": {"type": "string"}, "description": "The file in the pond, e.g. about/index.html"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}}}}}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "File too large to read here (over 512 KB)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Not a text file", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Uploads or new custom domains are paused by Pond, maintenance, or storage is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/jobs/{id}": {"get": {"summary": "Upload job status (scope ponds:read)", "operationId": "getJob", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"job": {"$ref": "#/components/schemas/Job"}}}}}}, "401": {"description": "Missing, invalid, revoked or expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Missing scope, pond limit or pond-restricted token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not found (or not visible to this token)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (120 requests a minute per token), or a domain was checked moments ago", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}}}