{"openapi":"3.1.0","info":{"title":"PageDrop API","version":"1.0.0","description":"PageDrop REST API for programmatic upload, share creation, and content validation. All endpoints under `/v1` are authenticated via `Authorization: Bearer pd_...` tokens issued from /developers/tokens.","contact":{"name":"PageDrop","url":"https://pagedrop.space"}},"servers":[{"url":"https://pagedrop.space/v1","description":"production"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pd_<prefix>_<secret>"}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"人类可读错误说明（中文）"},"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NOT_FOUND","VALIDATION","RATE_LIMITED","OVER_QUOTA","INFECTED","SLUG_TAKEN","DUPLICATE","CONFLICT","INTERNAL"]}}},"FileKind":{"type":"string","enum":["HTML","MARKDOWN","TEXT"]},"ScanStatus":{"type":"string","enum":["PENDING","CLEAN","INFECTED","SCAN_ERROR"]},"File":{"type":"object","required":["id","name","kind","sizeBytes","createdAt","scanStatus"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"$ref":"#/components/schemas/FileKind"},"sizeBytes":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"folderId":{"type":["string","null"]},"shareCount":{"type":"integer"},"scanStatus":{"$ref":"#/components/schemas/ScanStatus"},"scanResult":{"type":["string","null"],"description":"INFECTED 时为病毒签名"}}},"Share":{"type":"object","required":["id","token","hasPassword","oneTime","visitCount","uniqueVisitCount"],"properties":{"id":{"type":"string"},"token":{"type":"string"},"ownerSegment":{"type":"string","description":"分享拥有者的公开 URL 段，分享链接形如 /s/{ownerSegment}/{token}。"},"fileId":{"type":"string"},"fileName":{"type":"string"},"fileKind":{"$ref":"#/components/schemas/FileKind"},"hasPassword":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time"},"maxVisits":{"type":["integer","null"]},"perVisitorMaxVisits":{"type":["integer","null"],"description":"每个独立访客可成功访问该分享的次数上限。"},"perLoginUserMaxVisits":{"type":["integer","null"],"description":"每个登录用户账号可成功访问该分享的次数上限。设置后访客必须登录。"},"visitCount":{"type":"integer","description":"累计访问量：成功渲染一次主页面计 1 次，不去重。"},"uniqueVisitCount":{"type":"integer","description":"独立访问量：按访客标识去重后的成功渲染访客数。"},"oneTime":{"type":"boolean"},"requireLogin":{"type":"boolean","description":"为 true 时访客必须登录 PageDrop 后才能查看。"},"watermarkEnabled":{"type":"boolean","description":"为 true 时分享渲染页会叠加自定义水印。"},"watermarkText":{"type":["string","null"],"maxLength":80},"copyProtectionEnabled":{"type":"boolean","description":"为 true 时分享渲染页会阻止复制、选中和右键。"},"burnAfterReadEnabled":{"type":"boolean","description":"为 true 时已滚过内容会在当前浏览器中持久隐藏，刷新后从未读位置继续。"},"revokedAt":{"type":["string","null"],"format":"date-time"},"consumedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ShareInput":{"type":"object","properties":{"expiresInDays":{"type":["integer","null"],"minimum":1,"maximum":3650},"password":{"type":["string","null"],"minLength":4,"maxLength":32},"maxVisits":{"type":["integer","null"],"minimum":1,"maximum":9999},"perVisitorMaxVisits":{"type":["integer","null"],"minimum":1,"maximum":9999},"perLoginUserMaxVisits":{"type":["integer","null"],"minimum":1,"maximum":9999},"oneTime":{"type":"boolean"},"requireLogin":{"type":"boolean"},"watermarkEnabled":{"type":"boolean"},"watermarkText":{"type":["string","null"],"maxLength":80},"copyProtectionEnabled":{"type":"boolean"},"burnAfterReadEnabled":{"type":"boolean"},"slug":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{3,32}$"}}},"ValidateRequest":{"type":"object","required":["content","kind"],"properties":{"content":{"type":"string","maxLength":1048576},"kind":{"$ref":"#/components/schemas/FileKind"}}},"ValidateResult":{"type":"object","required":["kind","ok","normalized","issues"],"properties":{"kind":{"$ref":"#/components/schemas/FileKind"},"ok":{"type":"boolean"},"normalized":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string"},"line":{"type":"integer"},"col":{"type":"integer"}}}}}}}},"security":[{"BearerAuth":[]}],"paths":{"/me":{"get":{"summary":"当前用户信息","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"未鉴权","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files":{"get":{"summary":"列出文件","parameters":[{"name":"folderId","in":"query","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}}}}}},"post":{"summary":"上传文件，可选同时创建分享","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"folderId":{"type":"string"},"share":{"type":"string","description":"JSON 编码的 ShareInput，可选"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/File"},"share":{"$ref":"#/components/schemas/Share"},"url":{"type":"string","format":"uri"}}}}}},"400":{"description":"请求无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"同名 / 文件已被隔离","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"超过文件 / 配额上限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"查看单个文件","responses":{"200":{"description":"OK"},"404":{"description":"不存在"}}},"delete":{"summary":"软删除文件（移到回收站，撤销其全部分享）","responses":{"200":{"description":"OK"},"404":{"description":"不存在"}}}},"/shares":{"get":{"summary":"列出分享","parameters":[{"name":"fileId","in":"query","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"创建分享","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ShareInput"},{"type":"object","required":["fileId"],"properties":{"fileId":{"type":"string"}}}]}}}},"responses":{"200":{"description":"OK"},"404":{"description":"文件不存在"},"409":{"description":"文件已隔离 / slug 已被占用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shares/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"查看单个分享","responses":{"200":{"description":"OK"}}},"delete":{"summary":"吊销分享","responses":{"200":{"description":"OK"}}}},"/validate":{"post":{"summary":"校验 + 规范化 HTML / Markdown / Text","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResult"}}}}}}}}}