{"openapi":"3.1.0","info":{"title":"PlainNerd public API","version":"1.0.0","description":"English technology publishing. Public writes enter moderation. Agents with an owner-issued token (bearerAuth) can create and edit drafts and answer review comments under /api/v1/agent; only the owner publishes. No MCP endpoint is exposed. Article reads carry ETags; revalidate with If-None-Match."},"servers":[{"url":"https://plainnerd.com"}],"paths":{"/api/v1/articles":{"get":{"summary":"List published articles","responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/api/v1/articles/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read one published article including TipTap JSON","responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/api/v1/articles/{slug}/views":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read counts: web = browser page loads, ai = AI assistants, scripts and Markdown/JSON reads","responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/api/v1/comments":{"get":{"summary":"Read approved comments for the slug query parameter","responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}},"post":{"summary":"Submit a comment for moderation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","maxLength":200,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"author":{"type":"string","minLength":2,"maxLength":100},"content":{"type":"object","properties":{"type":{"type":"string","const":"doc"},"content":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":500},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false,"description":"At least 3 non-whitespace text characters; invisible formatting characters do not count."}},"required":["slug","author","content"],"additionalProperties":false}}}},"responses":{"202":{"description":"Accepted; never publishes automatically"},"400":{"description":"Invalid JSON"},"413":{"description":"Body exceeds 64 KiB"},"422":{"description":"Schema validation failed"},"429":{"description":"Rate limited"},"503":{"description":"Storage unavailable"}}},"parameters":[{"name":"slug","in":"query","schema":{"type":"string"}}]},"/api/v1/submissions":{"post":{"summary":"Submit an article proposal for moderation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":5,"maxLength":160},"description":{"type":"string","minLength":10,"maxLength":320},"author":{"type":"string","minLength":2,"maxLength":100},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"content":{"type":"object","properties":{"type":{"type":"string","const":"doc"},"content":{"minItems":1,"maxItems":250,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"heading"},"attrs":{"type":"object","properties":{"level":{"anyOf":[{"type":"number","const":2},{"type":"number","const":3}]}},"required":["level"],"additionalProperties":false},"content":{"maxItems":30,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type","attrs"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"bulletList"},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"orderedList"},"attrs":{"type":"object","properties":{"start":{"type":"integer","minimum":1,"maximum":10000},"type":{"anyOf":[{"type":"string","enum":["1","a","A","i","I"]},{"type":"null"}]}},"required":["start"],"additionalProperties":false},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"blockquote"},"content":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"codeBlock"},"attrs":{"type":"object","properties":{"language":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9_+-]{0,30}$"},{"type":"null"}]}},"additionalProperties":false},"content":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","text"],"additionalProperties":false}}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"horizontalRule"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"agentNote"},"content":{"minItems":1,"maxItems":40,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"bulletList"},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"orderedList"},"attrs":{"type":"object","properties":{"start":{"type":"integer","minimum":1,"maximum":10000},"type":{"anyOf":[{"type":"string","enum":["1","a","A","i","I"]},{"type":"null"}]}},"required":["start"],"additionalProperties":false},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"codeBlock"},"attrs":{"type":"object","properties":{"language":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9_+-]{0,30}$"},{"type":"null"}]}},"additionalProperties":false},"content":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","text"],"additionalProperties":false}}},"required":["type"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false,"description":"A \"For agents\" block: instructions for AI agents whose human asked about this topic. Holds paragraphs, lists and code blocks."},{"type":"object","properties":{"type":{"type":"string","const":"figure"},"attrs":{"type":"object","properties":{"kind":{"type":"string","enum":["bar","stacked","dot","heatmap","flow"]},"title":{"type":"string","minLength":1,"maxLength":160},"caption":{"type":"string","minLength":1,"maxLength":400},"unit":{"type":"string","minLength":1,"maxLength":24},"max":{"type":"number","exclusiveMinimum":0,"maximum":1000000000},"scale":{"type":"string","enum":["categorical","ordinal"]},"series":{"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"rows":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":80},"values":{"maxItems":10,"type":"array","items":{"type":"number","minimum":0,"maximum":1000000000}},"note":{"type":"string","minLength":1,"maxLength":200}},"required":["label","values"],"additionalProperties":false}},"reference":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":1000000000},"label":{"type":"string","minLength":1,"maxLength":60}},"required":["value","label"],"additionalProperties":false}},"required":["kind","title","series","rows"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"attrs":{"type":"object","properties":{"src":{"type":"string","maxLength":300,"pattern":"\\.(png|jpg|jpeg|webp|gif|avif)$","description":"Path of one of this article's attached files, relative to its attachment root (e.g. results/screenshots/run.png). Raster images only; never SVG or an external URL. Served at /files/<slug>/<src> once the article is published."},"alt":{"type":"string","minLength":1,"maxLength":300,"allOf":[{"pattern":"\\S"},{"pattern":"^[^\\p{Cc}]*$"}],"description":"What the image shows, for readers who cannot see it. Required."},"caption":{"description":"Visible caption","type":"string","minLength":1,"maxLength":400,"allOf":[{"pattern":"\\S"},{"pattern":"^[^\\p{Cc}]*$"}]}},"required":["src","alt"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false,"description":"At least 30 non-whitespace text characters; invisible formatting characters do not count."}},"required":["title","description","author","email","content"],"additionalProperties":false}}}},"responses":{"202":{"description":"Accepted; never publishes automatically"},"400":{"description":"Invalid JSON"},"413":{"description":"Body exceeds 64 KiB"},"422":{"description":"Schema validation failed"},"429":{"description":"Rate limited"},"503":{"description":"Storage unavailable"}}}},"/api/v1/newsletter":{"post":{"summary":"Record an email address with explicit consent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"consent":{"type":"boolean","const":true}},"required":["email","consent"],"additionalProperties":false}}}},"responses":{"202":{"description":"Accepted; never publishes automatically"},"400":{"description":"Invalid JSON"},"413":{"description":"Body exceeds 64 KiB"},"422":{"description":"Schema validation failed"},"429":{"description":"Rate limited"},"503":{"description":"Storage unavailable"}}}},"/api/v1/schema/article":{"get":{"summary":"Versioned article JSON Schema","responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/api/v1/schema/comment":{"get":{"summary":"Versioned comment document JSON Schema","responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/content/{slug}.md":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Article Markdown with JSON-compatible YAML metadata. /articles/{slug} also returns it when Accept prefers text/markdown.","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/api/v1/profiles/{handle}":{"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"A public profile: name, short bio, about, links, photo URL and the articles it wrote. Private and hidden profiles are 404.","responses":{"200":{"description":"JSON response","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/api/v1/articles/{slug}/attachments":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Manifest of files attached to a published article","responses":{"200":{"description":"Manifest with absolute URLs","content":{"application/json":{"schema":{"type":"object","required":["article","count","totalSize","archiveUrl","files"],"properties":{"article":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"markdown":{"type":"string","format":"uri"}}},"count":{"type":"integer"},"totalSize":{"type":"integer"},"archiveUrl":{"type":"string","format":"uri"},"files":{"type":"array","items":{"type":"object","required":["path","size","contentType","sha256","url"],"properties":{"path":{"type":"string","description":"Relative path; may contain folders"},"size":{"type":"integer","description":"Bytes"},"contentType":{"type":"string"},"sha256":{"type":"string","description":"Hex SHA-256 of the bytes"},"url":{"type":"string","format":"uri","description":"Raw file URL"}}}}}}}}},"304":{"description":"Not modified (If-None-Match)"},"404":{"description":"Article not published or file not found"}}}},"/files/{slug}/{path}":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"description":"File path; each segment percent-encoded, slashes kept","schema":{"type":"string"}},{"name":"download","in":"query","description":"Any value forces Content-Disposition: attachment","schema":{"type":"string"}}],"get":{"summary":"Raw attached file. Text-like files (including HTML, SVG and scripts) are text/plain; images keep their type; SVG is always a download. Sandboxed, nosniff, ETag is the quoted SHA-256.","responses":{"200":{"description":"File bytes","content":{"text/plain":{"schema":{"type":"string"}},"image/*":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Not modified (If-None-Match)"},"404":{"description":"Article not published or file not found"}}}},"/files/{slug}.zip":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Zip archive (stored, not compressed) of every attached file under <slug>/, plus <slug>/MANIFEST.json","responses":{"200":{"description":"Zip archive","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Not modified (If-None-Match)"},"404":{"description":"Article not published or file not found"}}}},"/api/v1/agent":{"get":{"summary":"The calling token: name, prefix, scopes, expiry","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Token","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/articles":{"get":{"summary":"Drafts an agent can read and edit, newest first","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Drafts","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"revision":{"type":"integer"},"updated":{"type":"string"},"openThreads":{"type":"integer"},"reviewState":{"enum":["none","changes_requested","in_progress","ready"]},"previewUrl":{"type":"string","format":"uri"},"reviewUrl":{"type":"string","format":"uri"}}}}}}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/articles/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"get":{"summary":"Read a draft as the strict Article JSON, or as Markdown with ?format=md (round-trips through PUT)","security":[{"bearerAuth":[]}],"parameters":[{"name":"format","in":"query","schema":{"enum":["json","md"]}}],"responses":{"200":{"description":"The draft; ETag and X-Revision carry the revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No draft with this slug (published articles are not visible here)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Create or update a draft. Status is always draft; agents never publish. Markdown: front matter of `key: value` lines (JSON values or plain text): title, description, category, tags, author, illustrationKind, coverImage, attachmentsView, evidenceStatus, locale, date, translationOf; readTime and updated are computed. coverImage is the path of one of this draft's attached png, jpg, jpeg, webp, gif or avif files; it replaces the illustration as the cover, and an empty value removes it. attachmentsView is list (a short list of links) or browser (the file browser with previews) for the \"Attached files\" section, which lists only files the page does not already show and only when one of them is not a raster image; without it, up to 10 listed files get the list, and an empty value removes it. A leading # heading is the title. Supported: paragraphs, ## and ###, lists (one level), blockquotes, fenced code with a language, horizontal rules, bold, italic, inline code and absolute http(s) links. Instructions for AI agents go in a fenced ```agents block holding Markdown of its own (paragraphs, lists and code blocks; use a longer outer fence around an inner code block); the site shows it as a labelled \"For agents\" panel and stores it as an agentNote node. A fenced ```prompt block is a prompt for the reader to copy; the article page lists all of them above the text, each under its section heading with the paragraph right before it as its description, so write that paragraph to stand alone. Charts and diagrams are a fenced ```figure block holding one JSON object: kind (bar, stacked, dot, heatmap or flow), title, optional caption, unit, max and scale, series (up to 4 names) and rows (label, values with one number per series, optional note); the site draws it and adds a data table. Images are a paragraph holding only ![alt](path \"optional caption\"): path is one of this draft's attached png, jpg, jpeg, webp, gif or avif files, relative to its attachment root (a leading ./ and the article's own /files/<slug>/<path> URLs are accepted and normalized); alt text is required. Files may be uploaded after the Markdown; `missingImages` in the response lists paths not attached yet, which the preview shows as placeholders. Tables, images inside text, lists or links, external or SVG images, raw HTML, h4+, nested lists, strikethrough, task lists and relative links are refused with 422 and a line-numbered issue list.","security":[{"bearerAuth":[]}],"parameters":[{"name":"If-Match","in":"header","schema":{"type":"string"},"description":"Expected revision, e.g. \"3\"; 412 when it differs"},{"name":"If-None-Match","in":"header","schema":{"const":"*"},"description":"Create only; 412 when the draft exists"},{"name":"X-Change-Note","in":"header","schema":{"type":"string","maxLength":500},"description":"Stored in the revision log"}],"requestBody":{"required":true,"content":{"text/markdown":{"schema":{"type":"string","maxLength":524288}},"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"responses":{"200":{"description":"Saved draft","headers":{"ETag":{"schema":{"type":"string"},"description":"The new revision, e.g. \"3\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftResult"}}}},"201":{"description":"Saved draft","headers":{"ETag":{"schema":{"type":"string"},"description":"The new revision, e.g. \"3\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftResult"}}}},"400":{"description":"Malformed If-Match or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The article is published or in editorial preview, or it changed during the save","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"If-Match or If-None-Match failed; `revision` is the current one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body over 512 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send text/markdown or application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported Markdown, invalid metadata or too little text; see `issues`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/articles/{slug}/attachments":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"post":{"summary":"Upload draft files: multipart/form-data with `paths` (JSON array) and one `files` part per path; up to 100 files and 16 MiB per request, 10 MiB per file, 1,000 files and 100 MiB per article. Same rules as the editorial desk.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Stored, unchanged and the full listing","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No draft with this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Over a limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported type or contents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete one draft file ({\"path\": \"…\"}) or all ({\"all\": true})","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Listing after the delete","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/articles/{slug}/review":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"get":{"summary":"The owner's inline comments, re-anchored against the current revision; open threads first","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Review"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No draft with this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/articles/{slug}/review/start":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"post":{"summary":"Mark the requested changes as in progress. The next PUT of the draft sets the review to ready.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"in_progress","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No changes were requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/articles/{slug}/review/ready":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"post":{"summary":"Mark the review ready without pushing a new revision (for reply-only rounds)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ready","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No review in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/review/threads/{id}/messages":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reply to an open thread. Agents cannot create, reopen or delete threads.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":4000,"description":"Plain text; never rendered as HTML"}}}}}},"responses":{"201":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Thread not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Thread resolved, full, or its article is no longer a draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Empty or longer than 4,000 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/review/threads/{id}/resolve":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Mark a thread done, optionally with a message; it stays open until the owner checks the change and resolves it","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"body":{"type":"string","minLength":1,"maxLength":4000,"description":"Plain text; never rendered as HTML"}}}}}},"responses":{"200":{"description":"Marked done: `{ id, status: \"open\", addressed: true, addressedAt }`","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid, expired or revoked token (WWW-Authenticate: Bearer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Thread not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resolved by the owner, or its article is no longer a draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 60 requests per minute per token; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pn_agent_<43 base64url characters>","description":"Agent token created by the owner in /admin/tokens. Accepted only on /api/v1/agent/*; cookies are ignored there."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"revision":{"type":["integer","null"],"description":"Current revision (412 responses)"},"status":{"type":"string","description":"Article status (409 for published or editorial-preview articles)"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/MarkdownIssue"},"description":"422 for Markdown drafts"}}},"MarkdownIssue":{"type":"object","required":["line","construct","hint"],"properties":{"line":{"type":"integer","description":"1-based line in the submitted Markdown"},"construct":{"type":"string","examples":["table","image inside text","external image","raw HTML","relative link","h4","front matter description"]},"hint":{"type":"string","description":"How to rewrite it"}}},"Article":{"type":"object","properties":{"schemaVersion":{"type":"string","const":"1.0.0"},"id":{"type":"string","pattern":"^[a-z0-9-]+$"},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"title":{"type":"string","minLength":1,"maxLength":160},"description":{"type":"string","minLength":1,"maxLength":320},"category":{"type":"string","enum":["Experiments","Guides","Field notes","Digest"]},"tags":{"maxItems":8,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"updated":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"author":{"type":"string","minLength":1,"maxLength":100},"readTime":{"type":"integer","minimum":1,"maximum":90},"illustrationKind":{"type":"string","enum":["agent","database","terminal","browser","digest","workflow"]},"coverImage":{"description":"Cover image: the path of one of this article's attached raster images (e.g. cover.png). Shown on the article page and on cards in place of the illustration; without it, or while the file is not attached, the illustration is used.","type":"string","maxLength":300,"pattern":"\\.(png|jpg|jpeg|webp|gif|avif)$"},"attachmentsView":{"description":"How the \"Attached files\" section looks: a short list of links (\"list\") or the file browser with previews (\"browser\"). Without it, articles with up to 10 listed files get the list.","type":"string","enum":["list","browser"]},"status":{"type":"string","enum":["editorial-preview","published","draft"]},"evidenceStatus":{"type":"string","enum":["research-plan","reference-guide","measured-experiment"]},"locale":{"type":"string","enum":["en","pl","cs"]},"originalLocale":{"type":"string","const":"en"},"translationOf":{"type":"string"},"content":{"type":"object","properties":{"type":{"type":"string","const":"doc"},"content":{"minItems":1,"maxItems":250,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"heading"},"attrs":{"type":"object","properties":{"level":{"anyOf":[{"type":"number","const":2},{"type":"number","const":3}]}},"required":["level"],"additionalProperties":false},"content":{"maxItems":30,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type","attrs"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"bulletList"},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"orderedList"},"attrs":{"type":"object","properties":{"start":{"type":"integer","minimum":1,"maximum":10000},"type":{"anyOf":[{"type":"string","enum":["1","a","A","i","I"]},{"type":"null"}]}},"required":["start"],"additionalProperties":false},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"blockquote"},"content":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"codeBlock"},"attrs":{"type":"object","properties":{"language":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9_+-]{0,30}$"},{"type":"null"}]}},"additionalProperties":false},"content":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","text"],"additionalProperties":false}}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"horizontalRule"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"agentNote"},"content":{"minItems":1,"maxItems":40,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"bulletList"},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"orderedList"},"attrs":{"type":"object","properties":{"start":{"type":"integer","minimum":1,"maximum":10000},"type":{"anyOf":[{"type":"string","enum":["1","a","A","i","I"]},{"type":"null"}]}},"required":["start"],"additionalProperties":false},"content":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"listItem"},"content":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"content":{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000},"marks":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"bold"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"italic"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"code"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"link"},"attrs":{"type":"object","properties":{"href":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https?:\\/\\/[^\\s]+$"},"target":{"anyOf":[{"type":"string","enum":["_blank","_self"]},{"type":"null"}]},"rel":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"class":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["href"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hardBreak"}},"required":["type"],"additionalProperties":false}]}}},"required":["type"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"codeBlock"},"attrs":{"type":"object","properties":{"language":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9_+-]{0,30}$"},{"type":"null"}]}},"additionalProperties":false},"content":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","text"],"additionalProperties":false}}},"required":["type"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false,"description":"A \"For agents\" block: instructions for AI agents whose human asked about this topic. Holds paragraphs, lists and code blocks."},{"type":"object","properties":{"type":{"type":"string","const":"figure"},"attrs":{"type":"object","properties":{"kind":{"type":"string","enum":["bar","stacked","dot","heatmap","flow"]},"title":{"type":"string","minLength":1,"maxLength":160},"caption":{"type":"string","minLength":1,"maxLength":400},"unit":{"type":"string","minLength":1,"maxLength":24},"max":{"type":"number","exclusiveMinimum":0,"maximum":1000000000},"scale":{"type":"string","enum":["categorical","ordinal"]},"series":{"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"rows":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":80},"values":{"maxItems":10,"type":"array","items":{"type":"number","minimum":0,"maximum":1000000000}},"note":{"type":"string","minLength":1,"maxLength":200}},"required":["label","values"],"additionalProperties":false}},"reference":{"type":"object","properties":{"value":{"type":"number","minimum":0,"maximum":1000000000},"label":{"type":"string","minLength":1,"maxLength":60}},"required":["value","label"],"additionalProperties":false}},"required":["kind","title","series","rows"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"attrs":{"type":"object","properties":{"src":{"type":"string","maxLength":300,"pattern":"\\.(png|jpg|jpeg|webp|gif|avif)$","description":"Path of one of this article's attached files, relative to its attachment root (e.g. results/screenshots/run.png). Raster images only; never SVG or an external URL. Served at /files/<slug>/<src> once the article is published."},"alt":{"type":"string","minLength":1,"maxLength":300,"allOf":[{"pattern":"\\S"},{"pattern":"^[^\\p{Cc}]*$"}],"description":"What the image shows, for readers who cannot see it. Required."},"caption":{"description":"Visible caption","type":"string","minLength":1,"maxLength":400,"allOf":[{"pattern":"\\S"},{"pattern":"^[^\\p{Cc}]*$"}]}},"required":["src","alt"],"additionalProperties":false}},"required":["type","attrs"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false}},"required":["schemaVersion","id","slug","title","description","category","tags","date","updated","author","readTime","illustrationKind","status","evidenceStatus","locale","originalLocale","content"],"additionalProperties":false,"title":"PlainNerd article v1.0.0"},"DraftResult":{"type":"object","required":["slug","revision","status","previewUrl","reviewUrl"],"properties":{"slug":{"type":"string"},"revision":{"type":"integer"},"status":{"const":"draft"},"previewUrl":{"type":"string","format":"uri","description":"The owner's preview (admin session only)"},"reviewUrl":{"type":"string","format":"uri","description":"This draft's review endpoint"},"markdownUrl":{"type":"string","format":"uri"},"missingImages":{"type":"array","items":{"type":"string"},"description":"Image paths the draft names that are not attached yet; upload them to the attachments endpoint"}}},"ReviewThread":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["open","resolved"],"description":"Only the owner resolves a thread"},"addressedAt":{"type":["string","null"],"format":"date-time","description":"When an agent marked this open thread done; it waits for the owner to resolve it. An owner reply or reopen clears it: the thread needs work again"},"addressedBy":{"type":["object","null"],"properties":{"name":{"type":["string","null"]}}},"anchored":{"type":"boolean","description":"Whether the quote was found in the current revision; false means outdated"},"anchor":{"type":"object","description":"W3C Web Annotation style selectors over the body text (textblocks joined by \\n)","properties":{"exact":{"type":"string"},"prefix":{"type":"string","description":"Up to 32 characters before"},"suffix":{"type":"string","description":"Up to 32 characters after"},"start":{"type":"integer","description":"Position in the current revision when anchored, else the original position"},"end":{"type":"integer"},"headingId":{"type":["string","null"]}}},"context":{"type":"string","description":"Plain text of the block(s) holding the passage"},"createdRevision":{"type":"integer"},"currentRevision":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolvedBy":{"type":["object","null"],"properties":{"kind":{"enum":["user","agent"]},"name":{"type":["string","null"]}}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"object","properties":{"kind":{"enum":["user","agent"]},"name":{"type":["string","null"]}}},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"Review":{"type":"object","properties":{"slug":{"type":"string"},"revision":{"type":"integer"},"status":{"const":"draft"},"reviewState":{"enum":["none","changes_requested","in_progress","ready"]},"reviewRequestedAt":{"type":["string","null"],"format":"date-time"},"threads":{"type":"array","items":{"$ref":"#/components/schemas/ReviewThread"},"description":"Open threads first"}}}}}}