{"openapi":"3.1.0","info":{"title":"Kofra API","version":"1.0.0","description":"Publish files, folders and sites to live URLs. Authenticate with a scoped bearer API key. REST, MCP and CLI metadata are generated from the operation registry. Errors include a stable code and remediation hint.","license":{"name":"MIT","url":"https://github.com/TogetherWeOwn/kofra/blob/main/LICENSE"}},"servers":[{"url":"https://kofra.app"}],"externalDocs":{"description":"Agent reference","url":"https://kofra.app/llms.txt"},"security":[{"bearer":[]}],"tags":[{"name":"core","description":"core operations"},{"name":"sites","description":"sites operations"},{"name":"versions","description":"versions operations"},{"name":"keys","description":"keys operations"},{"name":"members","description":"members operations"},{"name":"folders","description":"folders operations"},{"name":"agents","description":"agents operations"},{"name":"setup","description":"setup operations"},{"name":"publish","description":"publish operations"},{"name":"files","description":"files operations"},{"name":"transfers","description":"transfers operations"},{"name":"discovery","description":"discovery operations"},{"name":"pages","description":"pages operations"}],"paths":{"/t/{slug}":{"get":{"operationId":"transfer_page_get","summary":"Open a file delivery","description":"Open a file delivery","tags":["pages"],"security":[],"x-mcp-exclude":"browser page; use get_transfer for sender state","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Plain-text message and download links on the app origin."},"303":{"description":"Unlocked; redirect with a digest-bound cookie."},"403":{"description":"Password required."},"404":{"description":"Page or resource not found."},"410":{"description":"Delivery closed."},"451":{"description":"Delivery unavailable."}}},"head":{"operationId":"transfer_page_head","summary":"Open a file delivery","description":"Open a file delivery","tags":["pages"],"security":[],"x-mcp-exclude":"browser page; use get_transfer for sender state","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Plain-text message and download links on the app origin."},"303":{"description":"Unlocked; redirect with a digest-bound cookie."},"403":{"description":"Password required."},"404":{"description":"Page or resource not found."},"410":{"description":"Delivery closed."},"451":{"description":"Delivery unavailable."}}},"post":{"operationId":"transfer_page_post","summary":"Unlock a file delivery","description":"Unlock a file delivery","tags":["pages"],"security":[],"x-mcp-exclude":"browser page; use get_transfer for sender state","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"password":{"type":"string"}},"required":["password"]}}}},"responses":{"200":{"description":"Plain-text message and download links on the app origin."},"303":{"description":"Unlocked; redirect with a digest-bound cookie."},"403":{"description":"Password required."},"404":{"description":"Page or resource not found."},"410":{"description":"Delivery closed."},"451":{"description":"Delivery unavailable."}}}},"/mcp":{"post":{"operationId":"mcp","summary":"Remote MCP server (Streamable HTTP, stateless)","description":"JSON-RPC over Streamable HTTP (MCP 2026-07-28, and 2025-era clients through the stateless lane). Same API keys as REST. Narrow the tool list with ?toolsets=core,sites,versions,keys,members,folders,transfers and ?read_only=1. Example: claude mcp add --transport http kofra <origin>/mcp --header \"Authorization: Bearer dw_...\"","tags":["agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 request."}}}},"x-mcp-exclude":"this is the MCP endpoint itself","responses":{"200":{"description":"JSON-RPC response (application/json or text/event-stream)."},"401":{"description":"Missing or invalid API key (WWW-Authenticate: Bearer)."},"404":{"description":"Page or resource not found."}}}},"/":{"get":{"operationId":"landing","summary":"Landing page (HTML)","description":"Landing page (HTML)","tags":["agents"],"security":[],"x-mcp-exclude":"browser page","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/docs/errors":{"get":{"operationId":"error_catalog_page","summary":"Built-in error codes and remediation (HTML)","description":"Built-in error codes and remediation (HTML)","tags":["agents"],"security":[],"x-mcp-exclude":"documentation page","responses":{"200":{"description":"HTML error catalog","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/docs/errors.md":{"get":{"operationId":"error_catalog_markdown","summary":"Generated built-in error catalog (Markdown)","description":"Generated built-in error catalog (Markdown)","tags":["agents"],"security":[],"x-mcp-exclude":"documentation document","responses":{"200":{"description":"Markdown error catalog","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/health":{"get":{"operationId":"health","summary":"Health check","description":"Health check","tags":["agents"],"security":[],"x-mcp-exclude":"monitoring","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"}}}}}},"404":{"description":"Page or resource not found."}}}},"/claim":{"get":{"operationId":"claim_page","summary":"Claim page for anonymous sites (token in the URL fragment)","description":"Claim page for anonymous sites (token in the URL fragment)","tags":["agents"],"security":[],"x-mcp-exclude":"browser page; use claim_site","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/__dropway/encrypted/{slug}":{"get":{"operationId":"encrypted_page","summary":"Decrypt a CLI-encrypted site locally (key only in URL fragment)","description":"Decrypt a CLI-encrypted site locally (key only in URL fragment)","tags":["pages"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug."}],"security":[],"x-mcp-exclude":"browser-only WebCrypto; never send the share key to an API or MCP tool","responses":{"200":{"description":"First-party decryptor HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/__dropway/encrypted-loader.js":{"get":{"operationId":"encrypted_script","summary":"First-party encrypted-site decryptor","description":"First-party encrypted-site decryptor","tags":["pages"],"security":[],"x-mcp-exclude":"static browser asset","responses":{"200":{"description":"JavaScript","content":{"text/javascript":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/__dropway/encrypted-frame":{"get":{"operationId":"encrypted_frame","summary":"Opaque sandbox for authenticated decrypted content","description":"Opaque sandbox for authenticated decrypted content","tags":["pages"],"security":[],"x-mcp-exclude":"browser-only sandbox bootstrap","responses":{"200":{"description":"Isolated content runtime","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/login":{"get":{"operationId":"login_page","summary":"Sign-in page (API key; first-run setup)","description":"Sign-in page (API key; first-run setup)","tags":["pages"],"security":[],"x-mcp-exclude":"browser page","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}},"post":{"operationId":"login_form_fallback","summary":"Where the sign-in forms post before the page script has loaded: redirects back to /login and ignores the body","description":"Where the sign-in forms post before the page script has loaded: redirects back to /login and ignores the body","tags":["pages"],"security":[],"x-mcp-exclude":"browser page","responses":{"303":{"description":"Redirect to /login?retry=1"},"404":{"description":"Page or resource not found."}}}},"/dashboard":{"get":{"operationId":"dashboard_page","summary":"Dashboard: sites list","description":"Dashboard: sites list","tags":["pages"],"security":[],"x-mcp-exclude":"browser page; use list_sites","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/dashboard/":{"get":{"operationId":"dashboard_page_slash","summary":"Redirects to /dashboard","description":"Redirects to /dashboard","tags":["pages"],"security":[],"x-mcp-exclude":"redirect","responses":{"301":{"description":"Redirect"},"404":{"description":"Page or resource not found."}}}},"/dashboard/sites/{slug}":{"get":{"operationId":"dashboard_site_page","summary":"Dashboard: one site (versions, files, settings)","description":"Dashboard: one site (versions, files, settings)","tags":["pages"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug, e.g. bright-otter-x7k2 (routes marked as such also accept a site id)."}],"security":[],"x-mcp-exclude":"browser page; use get_site","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/dashboard/publish":{"get":{"operationId":"dashboard_publish_page","summary":"Dashboard: drag-and-drop publish","description":"Dashboard: drag-and-drop publish","tags":["pages"],"security":[],"x-mcp-exclude":"browser page; use publish_site","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/dashboard/keys":{"get":{"operationId":"dashboard_keys_page","summary":"Dashboard: API keys and members","description":"Dashboard: API keys and members","tags":["pages"],"security":[],"x-mcp-exclude":"browser page; use list_api_keys","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/dashboard/settings":{"get":{"operationId":"dashboard_settings_page","summary":"Dashboard: instance settings","description":"Dashboard: instance settings","tags":["pages"],"security":[],"x-mcp-exclude":"browser page","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/v/{slug}":{"get":{"operationId":"file_browser_root","summary":"Redirects to /v/{slug}/","description":"Redirects to /v/{slug}/","tags":["pages"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug, e.g. bright-otter-x7k2 (routes marked as such also accept a site id)."}],"security":[],"x-mcp-exclude":"redirect","responses":{"301":{"description":"Redirect"},"404":{"description":"Page or resource not found."}}}},"/v/{slug}/{path}":{"get":{"operationId":"file_browser_page","summary":"File browser: file tree plus a rendered, source or raw view of one file (rendered in a sandboxed frame on the sites origin)","description":"File browser: file tree plus a rendered, source or raw view of one file (rendered in a sandboxed frame on the sites origin)","tags":["pages"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug, e.g. bright-otter-x7k2 (routes marked as such also accept a site id)."},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"File path inside the site (may be empty or contain slashes)"}],"security":[],"x-mcp-exclude":"browser page; use read_file","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/view/{slug}/{path}":{"get":{"operationId":"file_browser_legacy","summary":"Redirects to /v/{slug}/{path}","description":"Redirects to /v/{slug}/{path}","tags":["pages"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Site slug, e.g. bright-otter-x7k2 (routes marked as such also accept a site id)."},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"File path"}],"security":[],"x-mcp-exclude":"redirect","responses":{"301":{"description":"Redirect"},"404":{"description":"Page or resource not found."}}}},"/__dropway/ui/{file}":{"get":{"operationId":"dashboard_script","summary":"Dashboard script (content-hashed name, cached immutable)","description":"Dashboard script (content-hashed name, cached immutable)","tags":["pages"],"parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string"},"description":"Script file name"}],"security":[],"x-mcp-exclude":"static asset","responses":{"200":{"description":"JavaScript","content":{"text/javascript":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/openapi.json":{"get":{"operationId":"openapi","summary":"This document","description":"This document","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Page or resource not found."}}}},"/llms.txt":{"get":{"operationId":"llms_txt","summary":"Agent quick reference (llms.txt)","description":"Agent quick reference (llms.txt)","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/llms-full.txt":{"get":{"operationId":"llms_full_txt","summary":"Full agent reference: every endpoint, MCP tool and error code","description":"Full agent reference: every endpoint, MCP tool and error code","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/skill.md":{"get":{"operationId":"skill","summary":"Agent Skill (SKILL.md) for this instance","description":"Agent Skill (SKILL.md) for this instance","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/connect":{"get":{"operationId":"connect_page","summary":"Copy-paste agent setup per client (HTML)","description":"Copy-paste agent setup per client (HTML)","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/connect.md":{"get":{"operationId":"connect_markdown","summary":"Copy-paste agent setup per client (Markdown)","description":"Copy-paste agent setup per client (Markdown)","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/robots.txt":{"get":{"operationId":"robots_txt","summary":"App crawler policy","description":"App crawler policy","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"Plain text","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/.well-known/api-catalog":{"get":{"operationId":"api_catalog","summary":"RFC 9727 linkset to this instance's OpenAPI, docs and MCP endpoint","description":"RFC 9727 linkset to this instance's OpenAPI, docs and MCP endpoint","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"OK","content":{"application/linkset+json":{"schema":{"type":"object"}}}},"404":{"description":"Page or resource not found."}}}},"/.well-known/agent-skills/index.json":{"get":{"operationId":"agent_skills_index","summary":"Agent Skills discovery index (v0.2.0) for `npx skills add <origin>`","description":"Agent Skills discovery index (v0.2.0) for `npx skills add <origin>`","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Page or resource not found."}}}},"/.well-known/agent-skills/{name}/SKILL.md":{"get":{"operationId":"agent_skill_file","summary":"A skill listed in the discovery index","description":"A skill listed in the discovery index","tags":["agents"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"Skill name (kofra)"}],"security":[],"x-mcp-exclude":"discovery document","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/.well-known/skills/index.json":{"get":{"operationId":"agent_skills_index_legacy","summary":"Legacy skills discovery index (v0.1.0)","description":"Legacy skills discovery index (v0.1.0)","tags":["agents"],"security":[],"deprecated":true,"x-mcp-exclude":"discovery document","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Page or resource not found."}}}},"/.well-known/skills/{name}/SKILL.md":{"get":{"operationId":"agent_skill_file_legacy","summary":"A skill listed in the legacy index","description":"A skill listed in the legacy index","tags":["agents"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"Skill name (kofra)"}],"security":[],"deprecated":true,"x-mcp-exclude":"discovery document","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Page or resource not found."}}}},"/api/v1/me":{"get":{"operationId":"whoami","summary":"Who am I","description":"Describe this Kofra instance, your credential and permissions, URLs, capabilities (including missing bindings), size/resource limits and usage. Call first when unsure what you may do.","tags":["core"],"security":[],"x-mcp-tool":"whoami","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"principal":{"type":"string"},"tenant":{"type":"object","properties":{},"additionalProperties":{}},"member":{"type":"object","properties":{},"additionalProperties":{}},"keyId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"siteRestriction":{"type":["string","null"]},"capabilities":{"type":"object","properties":{},"additionalProperties":{}},"limits":{"type":"object","properties":{},"additionalProperties":{}},"usage":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"example":{"principal":"member","tenant":{"id":"ten_example"},"member":{"id":"mem_example","email":"person@example.com","name":"Example","role":"member"},"keyId":"key_example","scopes":["sites:read"],"siteRestriction":null}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/publish-sources":{"post":{"operationId":"publish_site","summary":"Publish a site","description":"Publish files to a live URL in one call. Without `site` a new site with a generated name is created; with `site` set to a slug you own, ALL its files are replaced by `files` (a new immutable version); with a new slug, a site of that name is created. Each file needs a path plus one source: content (text, or base64 for small binaries), url (the server downloads a public https URL), sha256+size (bytes already stored or uploaded afterwards), copyFrom, or a chat attachment (download_url+file_name). Instead of files, pass archiveUrl alone: a public https .zip the server downloads and unpacks. Returns status (live, unchanged or awaiting_upload), the live `url`, version and next steps. Share `url` exactly as returned. Use update_site_files for partial edits. A root index.html, index.md or README.md opens as the site's page.","tags":["core"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"minItems":1,"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"description":"Path in the site, e.g. \"index.html\", \"assets/app.js\". Omit for attachments."},"download_url":{"type":"string","description":"Attachment URL (public https, like url); pair with file_name."},"file_name":{"type":"string","description":"Attachment name; becomes the path."},"content":{"type":"string","description":"Inline: \"utf8\" up to 1 MB, \"base64\" up to 256 KB; prefer url/sha256 when bigger or binary."},"encoding":{"type":"string","enum":["utf8","base64"],"description":"Content encoding. Default \"utf8\"."},"url":{"type":"string","description":"Public https URL (URL_FETCH_MAX_BYTES default 100 MiB; 30 s, 3 redirects; other caps)."},"headers":{"type":"object","properties":{},"additionalProperties":{"type":"string"},"description":"Headers for the url download; used once, never stored."},"sha256":{"type":"string","pattern":"^[a-fA-F0-9]{64}$","description":"Hex SHA-256. Stored bytes are reused; otherwise an upload link is returned (PUT, then finalize_version)."},"size":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Bytes; required with an unstored sha256."},"copyFrom":{"type":"object","properties":{"site":{"type":"string","minLength":1,"description":"Site slug, site_... id or URL."},"version":{"type":"string","minLength":1,"description":"\"live\", \"v3\"/\"3\", or a ver_... id."},"path":{"type":"string"}},"additionalProperties":false,"description":"Copy a published file: site you can read (default: this site), version (default: live), path (default: same)."},"contentType":{"type":"string","description":"MIME type; default from extension."}},"additionalProperties":false,"description":"One file: path + one source, or download_url + file_name."},"description":"Every file of the site. Omit when archiveUrl is given."},"archiveUrl":{"type":"string","description":"Public https .zip to unpack, instead of files (never both)."},"site":{"type":"string","description":"Optional. Slug, id or URL of your existing site to replace, or a new slug (3-56 chars: a-z, 0-9, single hyphens)."},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Title shown in lists."},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"One or two sentences about the site."},"spa":{"type":"boolean","description":"Unknown paths serve index.html."},"renderMarkdown":{"type":"boolean","description":"Render .md as pages (default true)."},"crossOriginIsolation":{"type":"boolean","description":"Send COOP/COEP headers."},"noindex":{"type":"boolean","description":"Skip search indexing."},"viewers":{"type":"boolean","description":"false serves all files raw."},"ttlSeconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Keyed-site expiry seconds; null clears."},"password":{"type":"string","minLength":4,"maxLength":200,"description":"Optional visitor password (see set_site_access)."},"message":{"type":"string","maxLength":200,"description":"Short note about this version, like a commit message."},"baseVersionId":{"type":"string","description":"Fail with version_conflict if the live version is no longer this one (protects someone else's newer publish)."}},"additionalProperties":false,"required":[]},"example":{"files":[{"path":"index.html","content":"Hello"}]}}}},"x-mcp-tool":"publish_site","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["live","unchanged","awaiting_upload"]},"url":{"type":"string","description":"Live URL. Share it exactly as returned."},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"24 h signed preview; bearer capability."},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"},"currentVersionId":{"type":["string","null"]}},"required":["slug","url"],"additionalProperties":{}},"version":{"anyOf":[{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}]},"files":{"type":"object","properties":{},"additionalProperties":{}},"upload":{"type":"object","properties":{},"additionalProperties":{},"description":"Only for awaiting_upload: items to PUT, then finalize."},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"next":{"type":"array","items":{}}},"required":["status","url","slug"],"additionalProperties":{}},"example":{"status":"live","url":"https://dropway.example/s/bright-otter-x7k2/","slug":"bright-otter-x7k2"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/files":{"patch":{"operationId":"update_site_files","summary":"Change some files","description":"Add, replace, delete or move some files of an existing site; every other file carries over unchanged (nothing is re-sent). `files` uses the same sources as publish_site; `delete` takes paths (a trailing / deletes a folder); `move` takes {from, to}. Pass baseVersionId (the version id from your last result) so a newer publish by someone else fails with version_conflict instead of being overwritten; on conflict, read the live files and retry with the new id. Returns the same result as publish_site plus `changes`.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"download_url":{"type":"string","format":"uri","description":"Chat attachment URL fetched like url; pair with file_name."},"file_name":{"type":"string","description":"Chat attachment file name; becomes the path."},"content":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"]},"url":{"type":"string","format":"uri","description":"Public https URL the server downloads."},"headers":{"type":"object","properties":{},"additionalProperties":{"type":"string"}},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"size":{"type":"integer","minimum":0,"maximum":9007199254740991},"copyFrom":{"type":"object","properties":{"site":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"}},"additionalProperties":{}},"contentType":{"type":"string"}},"additionalProperties":{},"description":"A path plus exactly one source: content (+encoding), url (+headers), sha256 (+size) or copyFrom; or an attachment (download_url + file_name, no path)."}},"delete":{"type":"array","items":{"type":"string"}},"move":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":{}}},"baseVersionId":{"type":"string","description":"\"live\", \"v3\", \"3\" or a version id."},"message":{"type":"string","maxLength":200}},"required":[],"additionalProperties":{}},"example":{"files":[{"path":"index.html","content":"Hello"}]}}}},"x-mcp-tool":"update_site_files","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["live","unchanged","awaiting_upload"]},"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"24 h signed preview; bearer capability."},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"files":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fetched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":{}},"upload":{"type":"object","properties":{"versionId":{"type":"string"},"expiresAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"finalize":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"changes":{"type":"object","properties":{},"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"next":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"additionalProperties":{},"description":"Result of MCP publish_site / update_site_files and REST PATCH .../files."},"example":{"status":"live","url":"https://dropway.example/s/bright-otter-x7k2/","slug":"bright-otter-x7k2"}}}},"202":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["live","unchanged","awaiting_upload"]},"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"24 h signed preview; bearer capability."},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"files":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fetched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":{}},"upload":{"type":"object","properties":{"versionId":{"type":"string"},"expiresAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"finalize":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"changes":{"type":"object","properties":{},"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"next":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"additionalProperties":{},"description":"Result of MCP publish_site / update_site_files and REST PATCH .../files."},"example":{"status":"live","url":"https://dropway.example/s/bright-otter-x7k2/","slug":"bright-otter-x7k2"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"get":{"operationId":"list_files","summary":"List files","description":"List the files of a site version (default: live): path, size, sha256, content type, viewer kind, the public `url` of each file and its `rawUrl` in the API. Filter with prefix; pages of up to 1000 (pass nextCursor back as cursor).","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"type":"string"}}],"x-mcp-tool":"list_files","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"files":[{"path":"index.html","size":5,"sha256":"0000000000000000000000000000000000000000000000000000000000000000","contentType":"text/html"}]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/versions/{id}/finalize":{"post":{"operationId":"finalize_version","summary":"Make an uploaded version live","description":"Make a pending version live after you uploaded its missing files (publish_site or update_site_files returned status awaiting_upload with upload.items). Safe to call again. If bytes are still missing, the error lists fresh upload items.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":{}},"example":{}}}},"x-mcp-tool":"finalize_version","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"url":"https://dropway.example/s/bright-otter-x7k2/","live":true,"replayed":false,"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"},"warnings":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/deploys/{id}/finalize":{"post":{"operationId":"finalize_version_alias_1","summary":"Make an uploaded version live","description":"Make a pending version live after you uploaded its missing files (publish_site or update_site_files returned status awaiting_upload with upload.items). Safe to call again. If bytes are still missing, the error lists fresh upload items.","tags":["core"],"deprecated":true,"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":{}},"example":{}}}},"x-mcp-tool":"finalize_version","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"url":"https://dropway.example/s/bright-otter-x7k2/","live":true,"replayed":false,"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"},"warnings":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}":{"get":{"operationId":"get_site","summary":"Get a site","description":"Show one site: live URL, title, settings, access mode, expiry, and the live version (number, file count, size, who published it and when).","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"x-mcp-tool":"get_site","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"additionalProperties":{}},"example":{"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"patch":{"operationId":"update_site_settings","summary":"Change site settings","description":"Change a site's title, description, spa, renderMarkdown, crossOriginIsolation, noindex, viewers or ttlSeconds. Only passed fields change. Passwords: set_site_access.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"spa":{"type":"boolean","description":"Serve index.html for unknown paths (single-page apps)."},"renderMarkdown":{"type":"boolean","description":"Render .md files as HTML pages for browsers (default true)."},"crossOriginIsolation":{"type":"boolean","description":"Send COOP/COEP headers (needed for SharedArrayBuffer, threaded WASM)."},"noindex":{"type":"boolean","description":"Ask crawlers not to index this site (X-Robots-Tag: noindex, generated robots.txt)."},"viewers":{"type":"boolean","description":"false serves every file raw and skips viewers."},"ttlSeconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Keyed-site expiry in seconds, renewed at each publish; null clears it."},"password":{"description":"Visitor password; null removes it. Needs an API key.","type":["string","null"]}},"required":[],"additionalProperties":{}},"example":{"title":"My page"}}}},"x-mcp-tool":"update_site_settings","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"additionalProperties":{}},"example":{"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"delete":{"operationId":"delete_site","summary":"Delete a site","description":"Delete a site and all its versions. Its URL stops working at once and the name is held for your tenant: only you may reclaim it before the hold ends. Set confirm to the site's slug.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"x-mcp-tool":"delete_site","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"deleted":true,"slug":"bright-otter-x7k2"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites":{"get":{"operationId":"list_sites","summary":"List sites","description":"List your sites, newest first, with their live URLs and live versions. Pages of up to 200; pass nextCursor back as cursor for the next page.","tags":["core"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"x-mcp-tool":"list_sites","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"additionalProperties":{}},"example":{"sites":[{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"}],"nextCursor":null}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"post":{"operationId":"create_site","summary":"Create an empty site","description":"Reserve a site (optionally with a chosen slug and settings) without publishing files yet. Usually you do not need this: publish_site creates the site and publishes in one call.","tags":["sites"],"security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"integer","minimum":0,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"contentType":{"type":"string"}},"required":["path","size","sha256"],"additionalProperties":{}}},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"spa":{"type":"boolean","description":"Serve index.html for unknown paths (single-page apps)."},"renderMarkdown":{"type":"boolean","description":"Render .md files as HTML pages for browsers (default true)."},"crossOriginIsolation":{"type":"boolean","description":"Send COOP/COEP headers (needed for SharedArrayBuffer, threaded WASM)."},"noindex":{"type":"boolean","description":"Ask crawlers not to index this site (X-Robots-Tag: noindex, generated robots.txt)."},"viewers":{"type":"boolean","description":"false serves every file raw and skips viewers."},"ttlSeconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Keyed-site expiry in seconds, renewed at each publish; null clears it."},"password":{"description":"Visitor password; null removes it. Needs an API key.","type":["string","null"]}},"additionalProperties":{},"required":[]},"example":{"slug":"bright-otter-x7k2"}}}},"x-mcp-tool":"create_site","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"url":{"type":"string"},"claimToken":{"type":"string"},"deploy":{"type":"object","properties":{"unchanged":{"type":"boolean"},"deploy":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"missing":{"type":"array","items":{"type":"string"}},"uploads":{"type":"array","items":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paths":{"type":"array","items":{"type":"string"}},"method":{"type":"string","const":"PUT"},"url":{"type":"string"},"headers":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"finalizeUrl":{"type":["string","null"]},"next":{"type":"string","description":"Plain-English next step."}},"additionalProperties":{}}},"additionalProperties":{}},"example":{"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"},"url":"https://dropway.example/s/bright-otter-x7k2/"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/read-file":{"get":{"operationId":"read_file","summary":"Read a file","description":"Read back one published file. Text types return UTF-8 text; images and other binaries return base64 (force either with encoding). Reads 64 KB by default (max 1 MB per call); text page boundaries may adjust by up to 3 bytes to preserve UTF-8 characters. When truncated, call again with offset = nextOffset. Use it to check what you published.","tags":["core"],"parameters":[{"name":"site","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Site slug, site_... id or URL."}},{"name":"path","in":"query","required":true,"schema":{"type":"string","description":"File path, e.g. \"index.html\"."}},{"name":"version","in":"query","required":false,"schema":{"type":"string","minLength":1,"description":"\"live\", \"v3\"/\"3\", or a ver_... id."}},{"name":"encoding","in":"query","required":false,"schema":{"type":"string","enum":["auto","text","base64"],"description":"Default \"auto\"."}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Byte offset to start at. Default 0."}},{"name":"length","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1048576,"description":"Bytes to read. Default 65536."}}],"x-mcp-tool":"read_file","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"versionId":{"type":"string"},"contentType":{"type":"string"},"kind":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sha256":{"type":"string"},"encoding":{"type":"string"},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"length":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"truncated":{"type":"boolean"},"nextOffset":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"content":{"type":"string"},"url":{"type":"string"},"rawUrl":{"type":"string"}},"required":["path","size","encoding","content"],"additionalProperties":{}},"example":{"path":"index.html","content":"Hello","encoding":"text","size":5}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/versions":{"get":{"operationId":"list_versions","summary":"List versions","description":"List the immutable versions of a site, newest first: number, live flag, file count, size, source, client and message. Restore any of them with restore_version.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"x-mcp-tool":"list_versions","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"currentVersionId":"ver_example","versions":[{"id":"ver_example","number":1,"status":"ready","live":true}]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"post":{"operationId":"create_version","summary":"Start a version from a file manifest (upload only what is missing)","description":"Send every file's path, size and sha256. The response lists only the files the server does not have yet (`uploads`). PUT each, then finalize.","tags":["versions"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"integer","minimum":0,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"contentType":{"type":"string"}},"required":["path","size","sha256"],"additionalProperties":{}}},"message":{"type":"string"},"baseVersionId":{"type":"string","description":"Fail with 409 version_conflict if the live version is no longer this one."},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"spa":{"type":"boolean","description":"Serve index.html for unknown paths (single-page apps)."},"renderMarkdown":{"type":"boolean","description":"Render .md files as HTML pages for browsers (default true)."},"crossOriginIsolation":{"type":"boolean","description":"Send COOP/COEP headers (needed for SharedArrayBuffer, threaded WASM)."},"viewers":{"type":"boolean","description":"false serves every file raw and skips viewers."},"ttlSeconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Keyed-site expiry in seconds, renewed at each publish; null clears it."},"password":{"description":"Visitor password; null removes it. Needs an API key.","type":["string","null"]}},"required":["files"],"additionalProperties":{}},"example":{"files":[{"path":"index.html","size":5,"sha256":"0000000000000000000000000000000000000000000000000000000000000000"}]}}}},"x-mcp-exclude":"MCP publish_site covers it (sha256 sources return upload links)","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"unchanged":{"type":"boolean"},"deploy":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"missing":{"type":"array","items":{"type":"string"}},"uploads":{"type":"array","items":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paths":{"type":"array","items":{"type":"string"}},"method":{"type":"string","const":"PUT"},"url":{"type":"string"},"headers":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"finalizeUrl":{"type":["string","null"]},"next":{"type":"string","description":"Plain-English next step."}},"additionalProperties":{}},"example":{"unchanged":false,"deploy":{"id":"ver_example","number":1,"status":"pending","live":false},"missing":["0000000000000000000000000000000000000000000000000000000000000000"],"uploads":[],"finalizeUrl":"https://dropway.example/api/v1/sites/bright-otter-x7k2/versions/ver_example/finalize"}}}},"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"unchanged":{"type":"boolean"},"deploy":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"missing":{"type":"array","items":{"type":"string"}},"uploads":{"type":"array","items":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paths":{"type":"array","items":{"type":"string"}},"method":{"type":"string","const":"PUT"},"url":{"type":"string"},"headers":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"finalizeUrl":{"type":["string","null"]},"next":{"type":"string","description":"Plain-English next step."}},"additionalProperties":{}},"example":{"unchanged":false,"deploy":{"id":"ver_example","number":1,"status":"pending","live":false},"missing":["0000000000000000000000000000000000000000000000000000000000000000"],"uploads":[],"finalizeUrl":"https://dropway.example/api/v1/sites/bright-otter-x7k2/versions/ver_example/finalize"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/versions/{id}/restore":{"post":{"operationId":"restore_version","summary":"Restore version","description":"Make an older version live again (instant rollback; nothing is copied). version accepts \"v3\", \"3\" or a version id. Restoring the version that is already live is a harmless no-op.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":{}},"example":{}}}},"x-mcp-tool":"restore_version","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"restored":true,"version":{"id":"ver_example","number":1,"status":"ready","live":true},"url":"https://dropway.example/s/bright-otter-x7k2/"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/access":{"put":{"operationId":"set_site_access","summary":"Set who can open a site","description":"Set a site's access mode. \"public\": anyone with the link. \"password\": visitors must enter the password (stored hashed; changing it signs everyone out). Modes \"restricted\" and \"private\" are not available on this edition yet and return feature_unavailable.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["public","password","restricted","private"]},"password":{"type":"string","minLength":4,"maxLength":200}},"required":["mode"],"additionalProperties":{}},"example":{"mode":"public"}}}},"x-mcp-tool":"set_site_access","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"access":{"type":"object","properties":{"mode":{"type":"string"}},"additionalProperties":{}}},"additionalProperties":{}},"example":{"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"},"access":{"mode":"public"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/claim":{"post":{"operationId":"claim_site","summary":"Claim an anonymous site","description":"Move an anonymous site (published without a key, so it expires) into your account using the claimToken from its publish response. It stops expiring and the claim token stops working.","tags":["core"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"claimToken":{"type":"string"}},"required":["claimToken"],"additionalProperties":{}},"example":{"claimToken":"dwc_example"}}}},"x-mcp-exclude":"The claim_site MCP tool is unavailable while anonymous publishing is disabled on this instance.","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"claimed":true,"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/rename":{"post":{"operationId":"rename_site","summary":"Rename a site","description":"Give a site a new slug, which changes its URL. An ordinary site's old URL answers 308 to the new URL (path and query kept) until redirectUntil. Transfers keep permanent sender reservations without a redirect (redirectUntil is null).","tags":["sites"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newSlug":{"type":"string"}},"required":["newSlug"],"additionalProperties":{}},"example":{"newSlug":"renamed-page"}}}},"x-mcp-tool":"rename_site","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"renamed":{"type":"boolean"},"oldSlug":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"},"redirectUntil":{"type":["string","null"]},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"additionalProperties":{}},"example":{"renamed":true,"oldSlug":"bright-otter-x7k2","slug":"renamed-page","url":"https://dropway.example/s/renamed-page/","redirectUntil":"2027-10-24T00:00:00.000Z","site":{"slug":"renamed-page","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{site}/duplicate":{"post":{"operationId":"duplicate_site","summary":"Duplicate a site's live version into a new slug","description":"Copy a site's live version into a brand-new slug, live at once: the copy's first version has exactly the source manifest (no bytes move; the source is untouched). Only SPA mode is carried over. The password and access gate, title, description and every other setting reset to the instance default: re-apply a password on the copy when the source was gated. The new slug is validated exactly like create_site (409 slug_taken on collision); an unknown or foreign source answers 404 site_not_found; a source with no live version answers 409.","tags":["sites"],"parameters":[{"name":"site","in":"path","required":true,"description":"Site slug, site_... id or URL.","schema":{"type":"string","minLength":1,"description":"Site slug, site_... id or URL."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newSlug":{"type":"string","description":"3-56 chars: a-z, 0-9, single hyphens."},"message":{"type":"string","maxLength":500,"description":"Version message for the copy's first version."}},"required":["newSlug"],"additionalProperties":false},"example":{"newSlug":"bright-otter-staging"}}}},"x-mcp-tool":"duplicate_site","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"url":{"type":"string"},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"},"currentVersionId":{"type":["string","null"]}},"required":["slug","url"],"additionalProperties":{}},"versionId":{"type":"string"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"note":{"type":"string"}},"required":["slug","url","versionId","fileCount","totalBytes"],"additionalProperties":{}},"example":{"slug":"bright-otter-staging","url":"https://dropway.example/s/bright-otter-staging/","site":{"slug":"bright-otter-staging","url":"https://dropway.example/s/bright-otter-staging/","currentVersionId":"ver_example"},"versionId":"ver_example","version":{"id":"ver_example","number":1,"status":"ready","live":true,"fileCount":3,"totalBytes":1234,"message":null},"fileCount":3,"totalBytes":1234,"note":"Only SPA mode was carried over. Re-apply a password on the copy when the source was gated."}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/slugs/release":{"post":{"operationId":"release_slug","summary":"Release a held site name early","description":"Release your tenant's freed site name before its hold ends, using an unrestricted admin key and a required reason kept as the audit record. The name becomes free at once. Set confirm to the slug. Cross-tenant disputes and ownerless holds require the instance operator's audited database procedure; tenant admin keys cannot release them.","tags":["sites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"reason":{"type":"string"},"confirm":{"type":"string"}},"required":["slug","reason","confirm"],"additionalProperties":{}},"example":{"slug":"held-name","reason":"Trademark dispute #42","confirm":"held-name"}}}},"x-mcp-tool":"release_slug","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"released":{"type":"boolean"},"slug":{"type":"string"},"redirectsReleased":{"type":"number"},"holdsReleased":{"type":"number"},"reason":{"type":"string"}},"additionalProperties":{}},"example":{"released":true,"slug":"held-name","redirectsReleased":0,"holdsReleased":1,"reason":"Trademark dispute #42"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/versions/{id}":{"get":{"operationId":"get_version","summary":"Get a version","description":"Show one version (\"live\", \"v3\", \"3\" or an id): status, number, counts, source, client, message. Pending: `missing` sha256 list, plus fresh upload items for write keys.","tags":["versions"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"x-mcp-tool":"get_version","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"string"},"version":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"missing":{"type":"array","items":{"type":"string"}},"upload":{"type":"object","properties":{"versionId":{"type":"string"},"expiresAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}},"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"method":{"type":"string","const":"PUT"},"url":{"type":"string"},"headers":{"type":"object","properties":{},"additionalProperties":{"type":"string"}},"curl":{"type":"string"}},"additionalProperties":{}}}},"additionalProperties":{}},"uploads":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}},"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"method":{"type":"string","const":"PUT"},"url":{"type":"string"},"headers":{"type":"object","properties":{},"additionalProperties":{"type":"string"}},"curl":{"type":"string"}},"additionalProperties":{}}}},"additionalProperties":{}},"example":{"site":"bright-otter-x7k2","version":{"id":"ver_example","number":1,"status":"ready","live":true},"missing":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"delete":{"operationId":"delete_version","summary":"Delete version","description":"Permanently delete one version that is not live (for example one that leaked a secret). The live version cannot be deleted: restore or publish another first. Set confirm to the site's slug. REST accepts an optional Idempotency-Key header (1-255 printable ASCII characters without spaces) to replay the original receipt for the same request and current authorization within 24 hours. Changed input returns 422; pending or unknown outcomes return 409 without another mutation.","tags":["versions"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","description":"Must equal the site's slug (destructive confirmation)."}},"required":["confirm"],"additionalProperties":{}},"example":{"confirm":"bright-otter-x7k2"}}}},"x-mcp-tool":"delete_version","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"deleted":true,"id":"ver_old"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/versions/{version}/export":{"get":{"operationId":"export_version","summary":"Download a version as a ZIP","description":"Stream one version (\"live\", \"v3\", \"3\" or an id) as a deterministic ZIP of exactly its served manifest bytes: entries stored uncompressed and sorted by path, one fixed timestamp, no data descriptors. Answers 413 when the version exceeds the effective file-count or byte caps. Binary payload: download it over REST (for example curl).","tags":["versions"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"version","in":"path","required":true,"description":"The version identifying this resource.","schema":{"type":"string"}}],"x-mcp-exclude":"Binary ZIP bytes never pass through the model; download the export over REST (GET /api/v1/sites/{slug}/versions/{version}/export), for example with curl.","responses":{"200":{"description":"Successful operation result","content":{"application/zip":{"schema":{"type":"string","format":"binary"},"example":"Hello from Kofra"}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/uploads":{"post":{"operationId":"create_multipart_upload","summary":"Start or resume a multipart upload","description":"Start or resume the one unfinished session for a pending version's file: pass versionId and sha256. An existing session keeps its partSize and acknowledgements. New partSize is 10-95 MiB (default 50 MiB); every part but the last holds exactly partSize bytes. The credential must control that pending version (an owner's API key, a claim token or the version's own dwu_ upload token).","tags":["versions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versionId":{"type":"string","minLength":1,"description":"Pending version id returned with status awaiting_upload."},"sha256":{"type":"string","pattern":"^[a-fA-F0-9]{64}$","description":"SHA-256 of the whole file, as listed in the pending manifest."},"partSize":{"type":"integer","minimum":10485760,"maximum":99614720,"description":"Part size in bytes, 10485760-99614720; default 52428800."}},"required":["versionId","sha256"],"additionalProperties":false},"example":{"versionId":"ver_example","sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}},"x-mcp-exclude":"REST/CLI resumable-upload protocol; part bytes never pass through the model","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"versionId":{"type":"string"},"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"partSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parts":{"type":"array","items":{"type":"object","properties":{"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"etag":{"type":"string"}},"required":["partNumber","size","etag"],"additionalProperties":{}}},"status":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","sha256","size","partSize","parts"],"additionalProperties":{}},"example":{"id":"upl_example","versionId":"ver_example","sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","size":157286400,"partSize":52428800,"parts":[],"status":"active","expiresAt":"2026-10-27T00:00:00.000Z"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/uploads/{id}":{"get":{"operationId":"get_multipart_upload","summary":"Show a resumable upload's acknowledged parts","description":"List the parts this upload session has acknowledged (partNumber, size, etag) so an interrupted upload resumes by sending only the missing parts. The credential must control the session's pending version.","tags":["versions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Upload session id from POST /api/v1/uploads.","schema":{"type":"string","minLength":1,"description":"Upload session id from POST /api/v1/uploads."}}],"x-mcp-exclude":"REST/CLI resumable-upload protocol; part bytes never pass through the model","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"versionId":{"type":"string"},"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"partSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"parts":{"type":"array","items":{"type":"object","properties":{"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"etag":{"type":"string"}},"required":["partNumber","size","etag"],"additionalProperties":{}}},"status":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","sha256","size","partSize","parts"],"additionalProperties":{}},"example":{"id":"upl_example","versionId":"ver_example","sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","size":157286400,"partSize":52428800,"parts":[{"partNumber":1,"size":52428800,"etag":"etag-example"}],"status":"active","expiresAt":"2026-10-27T00:00:00.000Z"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/uploads/{id}/parts/{partNumber}":{"put":{"operationId":"upload_multipart_part","summary":"Upload one part's raw bytes","description":"Body = exactly this part's bytes, with Content-Length (a one-based partNumber; every part but the last holds partSize bytes). Acknowledged only when the length matches. Acknowledged identical bytes replay without another storage write; all in-flight contenders get retryable 409 part_busy. Concurrent part buffers share a 96 MiB isolate budget (retryable 503 upload_busy when full); different acknowledged bytes are refused.","tags":["versions"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string","minLength":1}},{"name":"partNumber","in":"path","required":true,"description":"One-based part number.","schema":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"One-based part number."}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"Hello from Kofra"}}},"x-mcp-exclude":"raw bytes never pass through the model; PUT them from a shell or the CLI","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"partNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"etag":{"type":"string"}},"required":["partNumber","size","etag"],"additionalProperties":{}},"example":{"partNumber":1,"size":52428800,"etag":"etag-example"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/uploads/{id}/complete":{"post":{"operationId":"complete_multipart_upload","summary":"Complete and verify a resumable upload","description":"Assemble the acknowledged parts, stream-hash the result, and only then store it as blobs/<sha256> for the caller's pending version to finalize. Client-supplied part lists are ignored; the acknowledged parts decide. Safe to repeat.","tags":["versions"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"parts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}},"description":"Ignored; the server uses its acknowledged parts."}},"required":[],"additionalProperties":false},"example":{}}}},"x-mcp-exclude":"REST/CLI resumable-upload protocol; part bytes never pass through the model","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stored":{"type":"boolean"}},"required":["sha256","size"],"additionalProperties":{}},"example":{"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","size":157286400,"stored":true}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/keys":{"get":{"operationId":"list_api_keys","summary":"List API keys","description":"List active API keys (never the secrets): id, name, prefix, scopes, site restriction, expiry, last use. all=true lists every member's keys (needs members:write).","tags":["keys"],"parameters":[{"name":"all","in":"query","required":false,"schema":{"type":"string","enum":["1","true"]}}],"x-mcp-tool":"list_api_keys","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"keys":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"post":{"operationId":"create_api_key","summary":"Create an API key","description":"Create a key with a subset of your scopes, optionally restricted to one site. See scopes' enum for all supported permissions; deletion needs sites:delete, not sites:write. Store the secret `key`: it is shown ONCE and replay returns key: null.","tags":["keys"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sites:read","sites:write","sites:delete","keys:write","members:write","data:write","secrets:write","admin"]}},{"type":"string","description":"\"*\" or space-separated scopes"}]},"expiresInDays":{"type":"number"},"memberId":{"type":"string"},"site":{"type":"string"}},"additionalProperties":{},"required":[]},"example":{"name":"reader","scopes":["sites:read"]}}}},"x-mcp-tool":"create_api_key","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"id":"key_example","key":"dw_example","scopes":["sites:read"],"siteId":null}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/keys/{id}":{"delete":{"operationId":"revoke_api_key","summary":"Revoke an API key","description":"Revoke an API key by id (from list_api_keys). It stops working at once. You can revoke your own keys, or anyone's with members:write.","tags":["keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"x-mcp-tool":"revoke_api_key","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"revoked":true,"id":"key_example"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/members":{"get":{"operationId":"list_members","summary":"List members","description":"List the members of this instance: id, email, name, role (owner, admin, member).","tags":["members"],"x-mcp-tool":"list_members","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"members":[{"id":"mem_example","email":"person@example.com","name":"Example","role":"member"}]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"post":{"operationId":"add_member","summary":"Add a member","description":"Add a person or agent as a member (role member or admin; owners need an owner key). Returns their first API key, shown ONCE: hand it to them.","tags":["members"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member"]},"scopes":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sites:read","sites:write","sites:delete","keys:write","members:write","data:write","secrets:write","admin"]}},{"type":"string","description":"\"*\" or space-separated scopes"}]}},"additionalProperties":{},"required":[]},"example":{"email":"person@example.com","name":"Example"}}}},"x-mcp-tool":"add_member","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"member":{"id":"mem_example","email":"person@example.com","name":"Example","role":"member"},"apiKey":{"id":"key_example","key":"dw_example"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/members/{id}":{"patch":{"operationId":"update_member","summary":"Change a member","description":"Change a member's name or role. Only owners can grant or remove the owner role, and an instance always keeps one owner.","tags":["members"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":{}},"example":{}}}},"x-mcp-tool":"update_member","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"member":{"id":"mem_example","email":"person@example.com","name":"Updated name","role":"member"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"delete":{"operationId":"remove_member","summary":"Remove a member","description":"Remove a member and revoke all their API keys. Their sites stay. Set confirm to the member's email (or id when they have no email).","tags":["members"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"x-mcp-tool":"remove_member","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"removed":true,"id":"mem_example"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/folders/{folder}":{"delete":{"operationId":"delete_folder","summary":"Delete a folder","description":"Delete an empty or populated organizer folder. Its sites are kept and become unfiled. Set confirm to the folder's exact name.","tags":["folders"],"parameters":[{"name":"folder","in":"path","required":true,"description":"The folder identifying this resource.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","minLength":1}},"required":["confirm"]},"example":{"confirm":"Projects"}}}},"x-mcp-tool":"delete_folder","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"],"additionalProperties":false},"example":{"deleted":true,"id":"folder_example"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1":{"get":{"operationId":"api_index","summary":"API index with links to the docs","description":"API index with links to the docs. Use this REST compatibility endpoint for its documented wire format.","tags":["agents"],"security":[],"x-mcp-exclude":"discovery document; use whoami","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"name":"Kofra API","version":"v1","openapi":"https://dropway.example/openapi.json"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/setup":{"post":{"summary":"Operators: create a hosted account with the bootstrap key","tags":["account"],"operationId":"admin_create_account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"platformAdmin":{"type":"boolean"}},"required":["email"]}}}},"description":"Hosted replacement for the open-source first-run setup. Returns an owner API key and a one-time browser sign-in URL.","x-mcp-exclude":"operators only: it needs the bootstrap key, which is never given to agents","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/accounts":{"post":{"operationId":"setup_instance_alias_1","summary":"First run: create the owner (bootstrap key only)","description":"Authorization: Bearer <ADMIN_BOOTSTRAP_KEY>. Creates the tenant, its owner and a full-scope owner API key. Works once on a single-tenant instance.","tags":["setup"],"deprecated":true,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"tenantName":{"type":"string"}},"additionalProperties":{},"required":[]},"example":{"email":"owner@example.com","name":"Owner"}}}},"x-mcp-exclude":"needs the bootstrap key, which MCP never accepts","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"tenant":{"id":"ten_example"},"member":{"id":"mem_example","email":"person@example.com","name":"Example","role":"owner"},"apiKey":{"id":"key_example","key":"dw_example"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/setup/recover":{"post":{"operationId":"recover_owner_key","summary":"Mint a new owner key (bootstrap key only)","description":"Mint a new owner key (bootstrap key only). Use this REST compatibility endpoint for its documented wire format.","tags":["setup"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{},"required":[]},"example":{}}}},"x-mcp-exclude":"needs the bootstrap key","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"member":{"id":"mem_example","email":"person@example.com","name":"Example","role":"owner"},"apiKey":{"id":"key_example","key":"dw_example"}}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/publish":{"post":{"operationId":"publish_upload","summary":"Publish files in one call and get a live URL","description":"Accepts multipart/form-data (field name = file path, e.g. -F \"assets/app.js=@dist/assets/app.js\"; or field `files[]` with filenames; a single .zip is unpacked), application/json ({\"files\":[{\"path\",\"content\",\"encoding?\":\"base64\"}]}), a .zip body, or one raw file body named by ?path= or X-Kofra-Path. Settings and `slug` may be sent as form fields, JSON fields or query parameters. With an existing `slug` you own, publishes a new version of it. Byte-identical content returns unchanged:true. JSON uses the same flat content, url, sha256+size, copyFrom and chat-attachment (download_url+file_name) sources as MCP publish_site, or archiveUrl alone for a public https .zip, and returns PublishResult with versionUrl, counters and upload capabilities. Idempotency-Key replays JSON requests. Multipart, ZIP and raw bodies retain their original response shape.","tags":["publish"],"security":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":{"type":"string","format":"binary"}},"example":{"index.html":"Hello from Kofra"}},"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","description":"Legacy alias for site."},"site":{"type":"string","description":"Existing site ref or new slug."},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"download_url":{"type":"string","format":"uri","description":"Chat attachment URL fetched like url; pair with file_name."},"file_name":{"type":"string","description":"Chat attachment file name; becomes the path."},"content":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"]},"url":{"type":"string","format":"uri","description":"Public https URL the server downloads."},"headers":{"type":"object","properties":{},"additionalProperties":{"type":"string"}},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"size":{"type":"integer","minimum":0,"maximum":9007199254740991},"copyFrom":{"type":"object","properties":{"site":{"type":"string"},"version":{"type":"string"},"path":{"type":"string"}},"additionalProperties":{}},"contentType":{"type":"string"}},"additionalProperties":{},"description":"A path plus exactly one source: content (+encoding), url (+headers), sha256 (+size) or copyFrom; or an attachment (download_url + file_name, no path)."}},"archiveUrl":{"type":"string","description":"JSON only: public https .zip URL to publish instead of files."},"message":{"type":"string"},"baseVersionId":{"type":"string"},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"spa":{"type":"boolean","description":"Serve index.html for unknown paths (single-page apps)."},"renderMarkdown":{"type":"boolean","description":"Render .md files as HTML pages for browsers (default true)."},"crossOriginIsolation":{"type":"boolean","description":"Send COOP/COEP headers (needed for SharedArrayBuffer, threaded WASM)."},"viewers":{"type":"boolean","description":"false serves every file raw and skips viewers."},"ttlSeconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Keyed-site expiry in seconds, renewed at each publish; null clears it."},"password":{"description":"Visitor password; null removes it. Needs an API key.","type":["string","null"]},"path":{"type":"string"}},"additionalProperties":{},"required":[]},"example":{"files":[{"path":"index.html","content":"Hello"}]}},"application/zip":{"schema":{"type":"string","format":"binary"},"example":"Hello from Kofra"},"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"Hello from Kofra"}}},"x-mcp-exclude":"Multipart, zip and raw publishing; models use publish_site with file sources.","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["live","unchanged","awaiting_upload"]},"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"24 h signed preview; bearer capability."},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"files":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fetched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":{}},"upload":{"type":"object","properties":{"versionId":{"type":"string"},"expiresAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"finalize":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"changes":{"type":"object","properties":{},"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"next":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"additionalProperties":{},"description":"Result of MCP publish_site / update_site_files and REST PATCH .../files."},{"type":"object","properties":{"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"Signed exact-version preview link, valid for 24 hours."},"created":{"type":"boolean"},"unchanged":{"type":"boolean"},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"files":{"type":"array","items":{"type":"string"}},"uploaded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"claimToken":{"type":"string","description":"Anonymous publishes only; shown once."},"expiresAt":{"type":["string","null"]}},"additionalProperties":{}}]},"example":{"url":"https://dropway.example/s/bright-otter-x7k2/","slug":"bright-otter-x7k2","created":true,"unchanged":false,"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"},"version":{"id":"ver_example","number":1,"status":"ready","live":true},"files":["index.html"],"uploaded":1,"reused":0,"warnings":[]}}}},"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["live","unchanged","awaiting_upload"]},"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"24 h signed preview; bearer capability."},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"files":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fetched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":{}},"upload":{"type":"object","properties":{"versionId":{"type":"string"},"expiresAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"finalize":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"changes":{"type":"object","properties":{},"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"next":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"additionalProperties":{},"description":"Result of MCP publish_site / update_site_files and REST PATCH .../files."},{"type":"object","properties":{"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"Signed exact-version preview link, valid for 24 hours."},"created":{"type":"boolean"},"unchanged":{"type":"boolean"},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"files":{"type":"array","items":{"type":"string"}},"uploaded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"claimToken":{"type":"string","description":"Anonymous publishes only; shown once."},"expiresAt":{"type":["string","null"]}},"additionalProperties":{}}]},"example":{"url":"https://dropway.example/s/bright-otter-x7k2/","slug":"bright-otter-x7k2","created":true,"unchanged":false,"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"},"version":{"id":"ver_example","number":1,"status":"ready","live":true},"files":["index.html"],"uploaded":1,"reused":0,"warnings":[]}}}},"202":{"description":"Successful operation result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["live","unchanged","awaiting_upload"]},"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"24 h signed preview; bearer capability."},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"files":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stored":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fetched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":{}},"upload":{"type":"object","properties":{"versionId":{"type":"string"},"expiresAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"finalize":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"changes":{"type":"object","properties":{},"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"next":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"additionalProperties":{},"description":"Result of MCP publish_site / update_site_files and REST PATCH .../files."},{"type":"object","properties":{"url":{"type":"string"},"slug":{"type":"string"},"versionUrl":{"type":"string","description":"Signed exact-version preview link, valid for 24 hours."},"created":{"type":"boolean"},"unchanged":{"type":"boolean"},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Share this URL as returned; never construct it."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"anonymous":{"type":"boolean"},"expiresAt":{"type":["string","null"]},"settings":{"type":"object","properties":{},"additionalProperties":{}},"currentVersionId":{"type":["string","null"]},"currentVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}},"version":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"files":{"type":"array","items":{"type":"string"}},"uploaded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reused":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fix":{"type":"string"}},"additionalProperties":{}}},"claimToken":{"type":"string","description":"Anonymous publishes only; shown once."},"expiresAt":{"type":["string","null"]}},"additionalProperties":{}}]},"example":{"url":"https://dropway.example/s/bright-otter-x7k2/","slug":"bright-otter-x7k2","created":true,"unchanged":false,"site":{"slug":"bright-otter-x7k2","url":"https://dropway.example/s/bright-otter-x7k2/","currentVersionId":"ver_example"},"version":{"id":"ver_example","number":1,"status":"ready","live":true},"files":["index.html"],"uploaded":1,"reused":0,"warnings":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/deploys":{"post":{"operationId":"create_version_alias_1","summary":"Start a version from a file manifest (upload only what is missing)","description":"Send every file's path, size and sha256. The response lists only the files the server does not have yet (`uploads`). PUT each, then finalize.","tags":["versions"],"deprecated":true,"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"integer","minimum":0,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"contentType":{"type":"string"}},"required":["path","size","sha256"],"additionalProperties":{}}},"message":{"type":"string"},"baseVersionId":{"type":"string","description":"Fail with 409 version_conflict if the live version is no longer this one."},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"spa":{"type":"boolean","description":"Serve index.html for unknown paths (single-page apps)."},"renderMarkdown":{"type":"boolean","description":"Render .md files as HTML pages for browsers (default true)."},"crossOriginIsolation":{"type":"boolean","description":"Send COOP/COEP headers (needed for SharedArrayBuffer, threaded WASM)."},"viewers":{"type":"boolean","description":"false serves every file raw and skips viewers."},"ttlSeconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Keyed-site expiry in seconds, renewed at each publish; null clears it."},"password":{"description":"Visitor password; null removes it. Needs an API key.","type":["string","null"]}},"required":["files"],"additionalProperties":{}},"example":{"files":[{"path":"index.html","size":5,"sha256":"0000000000000000000000000000000000000000000000000000000000000000"}]}}}},"x-mcp-exclude":"MCP publish_site covers it (sha256 sources return upload links)","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"unchanged":{"type":"boolean"},"deploy":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"missing":{"type":"array","items":{"type":"string"}},"uploads":{"type":"array","items":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paths":{"type":"array","items":{"type":"string"}},"method":{"type":"string","const":"PUT"},"url":{"type":"string"},"headers":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"finalizeUrl":{"type":["string","null"]},"next":{"type":"string","description":"Plain-English next step."}},"additionalProperties":{}},"example":{"unchanged":false,"deploy":{"id":"ver_example","number":1,"status":"pending","live":false},"missing":["0000000000000000000000000000000000000000000000000000000000000000"],"uploads":[],"finalizeUrl":"https://dropway.example/api/v1/sites/bright-otter-x7k2/versions/ver_example/finalize"}}}},"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"unchanged":{"type":"boolean"},"deploy":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","ready"]},"live":{"type":"boolean"},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string"},"client":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string"},"finalizedAt":{"type":["string","null"]}},"additionalProperties":{}},"missing":{"type":"array","items":{"type":"string"}},"uploads":{"type":"array","items":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paths":{"type":"array","items":{"type":"string"}},"method":{"type":"string","const":"PUT"},"url":{"type":"string"},"headers":{"type":"object","properties":{},"additionalProperties":{}}},"additionalProperties":{}}},"finalizeUrl":{"type":["string","null"]},"next":{"type":"string","description":"Plain-English next step."}},"additionalProperties":{}},"example":{"unchanged":false,"deploy":{"id":"ver_example","number":1,"status":"pending","live":false},"missing":["0000000000000000000000000000000000000000000000000000000000000000"],"uploads":[],"finalizeUrl":"https://dropway.example/api/v1/sites/bright-otter-x7k2/versions/ver_example/finalize"}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/deploys/{id}":{"get":{"operationId":"get_deploy","summary":"Pending version status (missing files)","description":"Pending version status (missing files). Use this REST compatibility endpoint for its documented wire format.","tags":["versions"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"The id identifying this resource.","schema":{"type":"string"}}],"x-mcp-exclude":"Legacy response shape; models use get_version.","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"deploy":{"id":"ver_example","number":1,"status":"ready","live":true},"missing":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/blobs/{sha256}":{"put":{"operationId":"upload_blob","summary":"Upload one file's raw bytes","description":"Body = the exact file bytes, with Content-Length. The SHA-256 is verified. Only files listed as missing by a pending version you control are accepted.","tags":["versions"],"parameters":[{"name":"sha256","in":"path","required":true,"description":"The sha256 identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"Hello from Kofra"}}},"x-mcp-exclude":"raw bytes never pass through the model; PUT them from a shell (curl lines are in upload.items)","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"existed":false,"sha256":"0000000000000000000000000000000000000000000000000000000000000000","size":5}}}},"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"existed":false,"sha256":"0000000000000000000000000000000000000000000000000000000000000000","size":5}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"post":{"operationId":"upload_blob_alias_1","summary":"Upload one file's raw bytes","description":"Body = the exact file bytes, with Content-Length. The SHA-256 is verified. Only files listed as missing by a pending version you control are accepted.","tags":["versions"],"deprecated":true,"parameters":[{"name":"sha256","in":"path","required":true,"description":"The sha256 identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"Hello from Kofra"}}},"x-mcp-exclude":"raw bytes never pass through the model; PUT them from a shell (curl lines are in upload.items)","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"existed":false,"sha256":"0000000000000000000000000000000000000000000000000000000000000000","size":5}}}},"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"example":{"existed":false,"sha256":"0000000000000000000000000000000000000000000000000000000000000000","size":5}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/sites/{slug}/files/{path}":{"get":{"operationId":"get_file_bytes","summary":"Read one file's raw bytes (ETag = sha256)","description":"The MCP tool read_file returns text or base64 in JSON and pages with offset/length.","tags":["files"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug identifying this resource.","schema":{"type":"string"}},{"name":"path","in":"path","required":true,"description":"The path identifying this resource.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"type":"string"}}],"x-mcp-exclude":"Raw file bytes and HTTP headers; models use read_file for paged JSON.","responses":{"200":{"description":"Successful operation result","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"Hello from Kofra"}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/transfers":{"post":{"operationId":"create_transfer","summary":"Create a file delivery","description":"Create an expiring, optionally password-protected delivery. Files are immutable downloads on the separate sites host. Returns one general link and one per recipient. No email is sent by this operation.","tags":["transfers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"files":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"recipients":{"description":"Up to 50 normalized distinct email addresses; links are returned, not mailed.","type":"array","items":{"type":"string"}},"message":{"description":"Plain text, at most 10,000 characters.","type":["string","null"]},"password":{"description":"8-1,024 characters without NUL; empty or null clears protection.","type":["string","null"]},"expiresAt":{"description":"Unix milliseconds, from one hour to the instance's transfer expiry ceiling.","type":"number"},"downloadLimit":{"description":"1-10,000 counted downloads across all files and links; null means unlimited.","type":["number","null"]}},"required":["files"]},"example":{"files":[{"path":"note.txt","content":"Hello"}]}}}},"x-mcp-tool":"create_transfer","responses":{"201":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"mode":{"type":"string","const":"transfer"},"url":{"type":"string"},"expiresAt":{"type":"number"}},"required":["id","slug","mode","url","expiresAt"],"additionalProperties":{}},"example":{"id":"site_delivery","slug":"delivery-sample","mode":"transfer","url":"https://dropway.example/t/delivery-sample","message":null,"expiresAt":1988150400000,"downloadLimit":null,"downloads":0,"revision":0,"revokedAt":null,"expiredAt":null,"purgedAt":null,"recipients":[],"files":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/transfers/{transfer}":{"get":{"operationId":"get_transfer","summary":"Read your file delivery","description":"Read sender-visible delivery state, links, files and per-file and recipient download counts. Closed deliveries remain readable. A foreign or absent delivery returns the same 404.","tags":["transfers"],"parameters":[{"name":"transfer","in":"path","required":true,"description":"The transfer identifying this resource.","schema":{"type":"string"}}],"x-mcp-tool":"get_transfer","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"mode":{"type":"string","const":"transfer"},"url":{"type":"string"},"expiresAt":{"type":"number"}},"required":["id","slug","mode","url","expiresAt"],"additionalProperties":{}},"example":{"id":"site_delivery","slug":"delivery-sample","mode":"transfer","url":"https://dropway.example/t/delivery-sample","message":null,"expiresAt":1988150400000,"downloadLimit":null,"downloads":0,"revision":0,"revokedAt":null,"expiredAt":null,"purgedAt":null,"recipients":[],"files":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}},"patch":{"operationId":"update_transfer","summary":"Edit an unnotified live delivery","description":"Change message, expiry, recipients, download limit or password while live and unnotified. A set password needs currentPassword in this call to change or clear it. Concurrent changes conflict; semantic no-ops emit no event.","tags":["transfers"],"parameters":[{"name":"transfer","in":"path","required":true,"description":"The transfer identifying this resource.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recipients":{"description":"Up to 50 normalized distinct email addresses; links are returned, not mailed.","type":"array","items":{"type":"string"}},"message":{"description":"Plain text, at most 10,000 characters.","type":["string","null"]},"password":{"description":"8-1,024 characters without NUL; empty or null clears protection.","type":["string","null"]},"expiresAt":{"description":"Unix milliseconds, from one hour to the instance's transfer expiry ceiling.","type":"number"},"downloadLimit":{"description":"1-10,000 counted downloads across all files and links; null means unlimited.","type":["number","null"]},"currentPassword":{"type":"string"}},"required":[]},"example":{"message":"Updated note"}}}},"x-mcp-tool":"update_transfer","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"mode":{"type":"string","const":"transfer"},"url":{"type":"string"},"expiresAt":{"type":"number"}},"required":["id","slug","mode","url","expiresAt"],"additionalProperties":{}},"example":{"id":"site_delivery","slug":"delivery-sample","mode":"transfer","url":"https://dropway.example/t/delivery-sample","message":"Updated note","expiresAt":1988150400000,"downloadLimit":null,"downloads":0,"revision":1,"revokedAt":null,"expiredAt":null,"purgedAt":null,"recipients":[],"files":[]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/transfers/revoke":{"post":{"operationId":"revoke_transfers","summary":"Revoke file deliveries","description":"Immediately stop downloads for named deliveries or all live deliveries owned by the caller. Returns the changed count. Bytes and storage accounting remain until the retention purge; owner reads still work.","tags":["transfers"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"allLive":{"type":"boolean"}},"required":[]},"example":{"ids":["site_delivery"]}}}},"x-mcp-tool":"revoke_transfers","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"],"additionalProperties":false},"example":{"count":1}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/operations":{"get":{"operationId":"list_operations","summary":"List API operations and CLI commands","description":"Discover this instance's operation ids, methods, paths, required scopes, JSON input schemas and CLI paths. Public metadata only; this does not grant permission to execute an operation.","tags":["discovery"],"security":[],"x-mcp-exclude":"Discovery table; tools/list exposes the model tool schemas.","responses":{"200":{"description":"Successful operation result","content":{"application/json":{"schema":{"type":"object","properties":{"operations":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["operations"],"additionalProperties":false},"example":{"operations":[{"id":"whoami","method":"GET","path":"/api/v1/me","scopes":[],"inputSchema":{"type":"object","properties":{}},"cli":{"command":["whoami"]}}]}}}},"400":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}},"default":{"description":"Error with a stable code and remediation hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Invalid request.","hint":"Correct the input and retry.","retryable":false,"retryAfterSeconds":null,"docs":"https://kofra.app/docs/errors#invalid_request","next":[]},"requestId":"request-example"}}}}}}},"/api/v1/auth/email/start":{"post":{"summary":"Sign up or sign in: email a one-time link","tags":["account"],"operationId":"start_email_sign_in","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"next":{"type":"string"}},"required":["email"]}}}},"description":"Same answer whether or not the person exists. Rate limited per email and per IP.","x-mcp-exclude":"it runs before an MCP client has a credential (the result is an API key to configure the client with); call it over REST, or sign in at /signin","security":[],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/auth/email/verify":{"post":{"summary":"Exchange the token from the link for an API key","tags":["account"],"operationId":"verify_email_sign_in","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"dwm_... from the link"},"keyName":{"type":"string"}},"required":["token"]}}}},"description":"Creates the person and their personal account on first use (sign-up).","x-mcp-exclude":"it runs before an MCP client has a credential (the result is an API key to configure the client with); call it over REST, or sign in at /signin","security":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account":{"get":{"summary":"The account this credential acts for","tags":["account"],"operationId":"get_account","x-mcp-tool":"get_account","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workspaces":{"get":{"summary":"Accounts (personal and workspaces) of the person behind this credential","tags":["account"],"operationId":"list_workspaces","x-mcp-tool":"list_workspaces","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a workspace","tags":["account"],"operationId":"create_workspace","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"handle":{"type":"string"}},"required":["name"]}}}},"x-mcp-tool":"create_workspace","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workspaces/{handle}/invites":{"post":{"summary":"Create a one-use invite link (7 days)","tags":["account"],"operationId":"create_invite","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace handle or id (MCP argument: workspace)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["member","admin"]}}}}}},"x-mcp-tool":"create_invite","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/invites/accept":{"post":{"summary":"Accept an invite","tags":["account"],"operationId":"accept_invite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}}}},"x-mcp-tool":"accept_invite","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/exports":{"post":{"summary":"Build a zip of every live file plus a manifest (7 days to download)","tags":["account"],"operationId":"export_account","description":"The build runs in the background: poll GET /api/v1/account/exports/{id} until status is ready.","x-mcp-tool":"export_account","responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List this account's exports","tags":["account"],"operationId":"list_account_exports","x-mcp-exclude":"agents request with export_account and poll the returned id; the list is a dashboard convenience over REST","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/exports/{id}":{"get":{"summary":"Poll one export","tags":["account"],"operationId":"get_account_export","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Export id (MCP argument: exportId)"}],"x-mcp-tool":"export_account","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/exports/{id}/download":{"get":{"summary":"Download the finished zip","tags":["account"],"operationId":"download_account_export","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-mcp-exclude":"a binary zip payload; the export_account result carries the download URL for REST","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/deletion":{"get":{"summary":"Is this account deleted, and when does it purge?","tags":["account"],"operationId":"get_account_deletion","x-mcp-exclude":"deletion status for the dashboard; deletion itself needs a human typing the handle","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/deletion/confirm":{"post":{"summary":"Delete this account (owners type the handle)","tags":["account"],"operationId":"confirm_account_deletion","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","description":"The account handle, typed out"}},"required":["confirm"]}}}},"description":"Soft-deletes at once (credentials refused, sites not served); cloud rows purge 30 days later.","x-mcp-exclude":"destructive: only a human typing the account handle may delete an account, over REST or in the dashboard","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage":{"get":{"summary":"Plan limits, current use and 30 days of counters","tags":["billing"],"operationId":"get_usage","x-mcp-tool":"get_usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/plans":{"get":{"summary":"Plans, prices (USD cents) and limits","tags":["billing"],"operationId":"list_plans","x-mcp-tool":"list_plans","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/plan":{"get":{"summary":"This account's plan, status and entitlements","tags":["billing"],"operationId":"get_plan","x-mcp-tool":"get_plan","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/checkout":{"post":{"summary":"Start an upgrade: returns a URL for a human to pay or approve","tags":["billing"],"operationId":"start_checkout","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["pro","team"]},"interval":{"type":"string","enum":["month","year"]},"currency":{"type":"string","enum":["usd"]},"acknowledgedPriceCents":{"type":"integer","minimum":1,"description":"The exact price shown to the user, in USD cents, for the chosen interval (yearly is the full yearly price)."},"sharedPaymentToken":{"type":"string","description":"Optional Stripe shared payment token (spt_...). Held sealed until a human approves; never returned."}},"required":["plan","currency","acknowledgedPriceCents"]}}}},"description":"Owners and admins only. Without sharedPaymentToken the URL is a Stripe Checkout page. With one, the URL is an approval page where a signed-in owner or admin must approve before anything is charged. While paid plans are not open the request is recorded (202).","x-mcp-tool":"start_checkout","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/portal":{"post":{"summary":"Billing portal URL for a human","tags":["billing"],"operationId":"open_billing_portal","x-mcp-tool":"open_billing_portal","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/invoices":{"get":{"summary":"Invoices of this account","tags":["billing"],"operationId":"list_invoices","x-mcp-tool":"list_invoices","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error: { error: { code, message, hint?, details? }, requestId }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key, scoped claim token, or the bootstrap key for setup only."}},"schemas":{"Error":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message","retryable","retryAfterSeconds","docs","next"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"retryable":{"type":"boolean"},"retryAfterSeconds":{"type":["integer","null"],"minimum":0},"docs":{"type":"string","format":"uri"},"next":{"type":"array","items":{"type":"object","required":["tool","args","why"],"properties":{"tool":{"type":"string"},"args":{"type":"object","additionalProperties":true},"why":{"type":"string"}}}},"details":{"type":"object","additionalProperties":true}}},"requestId":{"type":"string"}}}}}}