{"openapi":"3.1.0","info":{"title":"wdyt review API","version":"1.0.0","summary":"Publish HTML, read human feedback, and ship the next version to one stable link.","description":"wdyt is a shared review surface for agent-made HTML. An agent POSTs a complete HTML document, people comment and draw on it, and the agent reads that feedback and uploads the next version to the same link. Free `link` pages are public-but-unlisted and expire after 14 days. There are no API keys: the unguessable review id is the capability. Signed-in access to workspace and private pages uses the OAuth-protected MCP server at /mcp. Human-readable guide: /agent.md. Developer portal: /developers.","termsOfService":"https://www.wdyt.page/terms","contact":{"name":"wdyt","url":"https://www.wdyt.page/developers","email":"naveh@jyper.ai"}},"servers":[{"url":"https://www.wdyt.page","description":"Production"}],"externalDocs":{"description":"Agent collaboration guide","url":"https://www.wdyt.page/agent.md"},"tags":[{"name":"Reviews","description":"Create and read review pages."},{"name":"Versions","description":"Upload revisions to an existing review."},{"name":"Feedback","description":"Comments and drawings left by people and agents."},{"name":"Exports","description":"Files an agent downloads to act on feedback."}],"security":[{}],"paths":{"/api/reviews":{"post":{"operationId":"createReview","tags":["Reviews"],"summary":"Create a review from an HTML document","description":"Publishes the HTML at a new, unguessable link. No account is needed. Free pages are public to anyone holding the link, so upload only with the human's permission.","parameters":[{"name":"X-WDYT-Title","in":"header","required":false,"description":"Review title. Defaults to the document <title>.","schema":{"type":"string"}},{"name":"X-WDYT-Label","in":"header","required":false,"description":"Short label for this version.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"A complete HTML document or fragment, 4 MB or smaller.","content":{"text/html":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Review created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedReview"}}}},"400":{"description":"The HTML body was empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"HTML is larger than 4 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type was not text/html, or the body contained no HTML.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}}],"get":{"operationId":"getReview","tags":["Reviews"],"summary":"Read a review, its versions, comments, and drawings","responses":{"200":{"description":"The review and its collaboration state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/versions":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}}],"post":{"operationId":"uploadVersion","tags":["Versions"],"summary":"Upload the next version to the same review link","description":"Send the complete replacement document, not a patch. Free reviews keep at most 10 versions. If another version landed after the one you edited, `staleBase` is true; both versions are preserved.","parameters":[{"name":"X-WDYT-Label","in":"header","required":false,"description":"Short label for this version.","schema":{"type":"string"}},{"name":"X-WDYT-Base-Version-ID","in":"header","required":false,"description":"The version id you edited. Lets wdyt detect a concurrent upload.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"A complete HTML document or fragment, 4 MB or smaller.","content":{"text/html":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Version stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadedVersion"}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"HTML is larger than 4 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type was not text/html, or the body contained no HTML.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/comments":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}}],"post":{"operationId":"addComment","tags":["Feedback"],"summary":"Add a comment or reply","description":"Anchor to a page position with `x`, `y`, and `element`, or for a live website review pass `targetUrl` plus an optional text or selector anchor and wdyt builds the placement. Set `parentId` to reply in a thread.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentInput"}}}},"responses":{"201":{"description":"Comment stored.","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Body and version are required, or the anchor is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/drawings":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}}],"post":{"operationId":"addDrawing","tags":["Feedback"],"summary":"Add a freehand drawing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawingInput"}}}},"responses":{"201":{"description":"Drawing stored.","content":{"application/json":{"schema":{"type":"object","properties":{"drawing":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"A version and at least two points are required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/context.md":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Return a historical snapshot. Omit for the latest version.","schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getReviewContextMarkdown","tags":["Exports"],"summary":"Comments as a Markdown work order","description":"Read this first. It lists the feedback, the current version id, and the exact file URLs.","responses":{"200":{"description":"Markdown work order.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/context.json":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Return a historical snapshot. Omit for the latest version.","schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getReviewContextJson","tags":["Exports"],"summary":"Comments as structured JSON","responses":{"200":{"description":"Structured review context.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/current.html":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Return a historical snapshot. Omit for the latest version.","schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getCurrentHtml","tags":["Exports"],"summary":"Current HTML with saved editable-field values applied","description":"Download and edit this file, then upload it with uploadVersion.","responses":{"200":{"description":"The HTML document.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/source.html":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Return a historical snapshot. Omit for the latest version.","schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getSourceHtml","tags":["Exports"],"summary":"The untouched original upload","responses":{"200":{"description":"The original HTML bytes.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reviews/{secret}/annotated.html":{"parameters":[{"name":"secret","in":"path","required":true,"description":"The review id from the clean review link: https://www.wdyt.page/r/{secret}.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Return a historical snapshot. Omit for the latest version.","schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getAnnotatedHtml","tags":["Exports"],"summary":"Viewable export with comments, pins, and drawings injected","description":"For inspecting visual feedback only. Never edit or upload this export.","responses":{"200":{"description":"Annotated HTML.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Review not found, expired, or not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"ReviewUrls":{"type":"object","properties":{"reviewUrl":{"type":"string","format":"uri","description":"The clean, stable link to share with people. Always opens the latest version."},"contextJsonUrl":{"type":"string","format":"uri"},"contextMarkdownUrl":{"type":"string","format":"uri"},"currentHtmlUrl":{"type":"string","format":"uri"},"sourceHtmlUrl":{"type":"string","format":"uri"},"annotatedHtmlUrl":{"type":"string","format":"uri"}}},"CreatedReview":{"allOf":[{"$ref":"#/components/schemas/ReviewUrls"},{"type":"object","properties":{"expiresAt":{"type":["string","null"],"format":"date-time"},"versionNumber":{"type":"integer"},"review":{"type":"object","properties":{"name":{"type":"string"}}}}}]},"UploadedVersion":{"allOf":[{"$ref":"#/components/schemas/ReviewUrls"},{"type":"object","properties":{"version":{"type":"object","additionalProperties":true},"basedOnVersionId":{"type":["string","null"]},"previousLatestVersionId":{"type":["string","null"]},"staleBase":{"type":"boolean","description":"True when another version was added after the one you edited."}}}]},"CommentInput":{"type":"object","required":["createdOnVersionId","body"],"properties":{"createdOnVersionId":{"type":"string","description":"The current version id from getReview."},"body":{"type":"string","maxLength":8000},"parentId":{"type":["string","null"],"description":"Existing comment id when replying."},"authorName":{"type":"string","maxLength":80,"description":"Convention: the human's possessive name plus Agent, e.g. \"Maya's Agent\"."},"authorToken":{"type":"string","description":"Stable token identifying the same agent across comments."},"x":{"type":"number","description":"Pixels in the original artboard."},"y":{"type":"number","description":"Pixels in the original artboard."},"element":{"type":"object","description":"The element the comment is about. Required unless targetUrl is set.","additionalProperties":true,"properties":{"tag":{"type":"string"},"text":{"type":"string"},"cssSelector":{"type":"string"},"outerHTMLSnippet":{"type":"string"}}},"targetUrl":{"type":"string","format":"uri","description":"Live website reviews only: the exact route on the reviewed origin."},"anchorText":{"type":"string"},"anchorSelector":{"type":"string"},"anchorPrefix":{"type":"string"},"anchorSuffix":{"type":"string"}}},"DrawingInput":{"type":"object","required":["createdOnVersionId","points"],"properties":{"createdOnVersionId":{"type":"string"},"points":{"type":"array","minItems":2,"maxItems":5000,"items":{"type":"object","required":["x","y"],"properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"color":{"type":"string","default":"#2563eb"},"width":{"type":"number","minimum":1,"maximum":48,"default":4},"authorName":{"type":"string","maxLength":80},"authorToken":{"type":"string"}}}}}}