raw.pub API 文档

创建文本、网址或引用已有文件

请求字段

请求示例

curl --request POST 'https://api.raw.pub/api/v1/links' \
 --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' \
 --data '{"origin":"hello raw.pub","kind":"text"}'

响应

201 Created，返回完整 Link。内容重复仍创建新 code。

{"code":"AbCd2345","kind":"text","value":"hello raw.pub","version":1,"contentReused":true,"link":"https://raw.pub/{user}/AbCd2345"}

小文件上传

请求字段

请求示例

curl --request POST 'https://api.raw.pub/api/v1/links' --header 'Authorization: Bearer {token}' --form 'file=@./report.pdf'

响应

201 Created，返回 file Link。

{"code":"BcDe3456","kind":"file","fileName":"report.pdf","sizeBytes":12345,"version":1,"contentReused":false}

申请上传地址

请求字段

请求示例

curl --request POST 'https://api.raw.pub/api/v1/uploads' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"fileName":"video.mp4","contentType":"video/mp4","sizeBytes":123456,"contentHash":"{md5}{sha256}","contentMD5":"{base64}"}'

响应字段

响应示例

{"intentId":"{intentId}","upload":{"method":"PUT","url":"{signedUrl}","headers":{"Content-MD5":"{base64}"}},"completeUrl":"/api/v1/uploads/{intentId}/complete"}

确认上传完成

请求字段

路径 intentId 必填，请求体为空，使用申请时相同令牌。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/uploads/{intentId}/complete' --header 'Authorization: Bearer {token}'

响应

200 OK，校验大小、摘要和媒体信息后返回 file Link。

{"code":"CdEf4567","kind":"file","fileName":"video.mp4","storage":"oss","contentReused":false,"version":1}

创建完整目录树

请求字段

请求示例

curl --request POST 'https://api.raw.pub/api/v1/directories' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"directoryName":"project","children":[{"name":"src","children":[{"name":"main.go","code":"AbCd2345"}]},{"name":"shared","code":"DirEf678"}]}'

响应

201 Created。普通子目录没有 code；引用目录是实时挂载，目标更新后会在这里同步显示。递归或重复挂载返回 409。

{"code":"DeFg5678","kind":"directory","version":1,"tree":{"name":"project","children":[{"name":"src","kind":"directory","code":"","children":[{"name":"main.go","kind":"file","code":"AbCd2345"}]},{"name":"shared","kind":"directory","code":"DirEf678","mounted":true}]}}

更新目录或目录切面

请求字段

directoryName、children 是当前 code 可见的完整树；version 是读取到的版本。

请求示例

curl --request PUT 'https://api.raw.pub/api/v1/directories/{code}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"directoryName":"src-new","version":3,"children":[{"name":"main.go","code":"AbCd2345"}]}'

响应

200 OK；根和共享 Head 的切面同步变化，版本冲突返回 409。

{"code":"{code}","kind":"directory","version":4,"tree":{"name":"src-new","children":[{"name":"main.go","code":"AbCd2345"}]}}

为子目录生成切面链接

请求字段

请求示例

curl --request POST 'https://api.raw.pub/api/v1/links/{code}/slices' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"path":"/src"}'

响应

201 Created；同一 Head 的同一路径只能创建一次。

{"code":"EfGh6789","kind":"directory","fileName":"src","version":3,"link":"https://raw.pub/{user}/EfGh6789"}

一行上传本地目录

请求字段

请求示例

curl -fsSL 'https://api.raw.pub/upd' | bash -s -- '{目录}' '{token}' '{有效期}'

响应

脚本按文件顺序上传，1KB 以下的文本走服务器，其余文件直传存储；随后提交完整目录树。标准输出仅返回最终目录链接，进度写入标准错误。

https://raw.pub/{user}/{code}

滚动加载链接列表

请求字段

请求示例

curl 'https://api.raw.pub/api/v1/links?page=1&size=20&status=active&tag=normal' --header 'Authorization: Bearer {token}'

响应字段

响应示例

{"list":[{"code":"DeFg5678","kind":"directory","tags":["normal"],"version":2,"tree":{"name":"project","children":[]}}],"total":1,"page":1,"size":20,"hasMore":false}

按内容摘要检查是否存在

请求字段

请求示例

curl 'https://api.raw.pub/api/v1/links?hash={hash}' --header 'Authorization: Bearer {token}'

响应字段

响应示例

{"exists":true,"sameSpace":true,"link":"https://raw.pub/{user}/{code}"}

替换文本、网址或文件内容

请求字段

请求示例

curl --request PUT 'https://api.raw.pub/api/v1/links/{code}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"kind":"text","origin":"new text","version":2}'

响应

200 OK，code 不变、version 增加。

{"code":"{code}","kind":"text","value":"new text","version":3,"contentReused":false}

修改别名或有效期

请求字段

请求示例

curl --request PATCH 'https://api.raw.pub/api/v1/links/{code}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"alias":"report","deadline":null}'

响应

200 OK。

{"code":"{code}","alias":"report","deadline":null,"link":"https://raw.pub/{user}/report"}

另存为独立链接

请求字段

可选 alias、deadline、expiry，允许内容完全不变。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/links/{code}/save-as' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{}'

响应

201 Created，新 code 使用独立 Head，初始共享 Content。

{"code":"FgHi789A","kind":"text","version":1,"contentReused":true}

删除链接

请求字段

路径 code 必填，无请求体，必须使用所属用户令牌。

请求示例

curl --request DELETE 'https://api.raw.pub/api/v1/links/{code}' --header 'Authorization: Bearer {token}'

响应

204 No Content，响应体为空。仍被其他 code 或目录引用的 Content 不会删除。

HTTP/1.1 204 No Content

读取元数据

请求字段

路径 code 或 alias 必填，无请求体。

请求示例

curl 'https://api.raw.pub/api/v1/links/{code}/meta'

响应字段与示例

返回 type、contentType、contentLength、fileName、value、code、link、version；目录增加 tree，远端文件增加 rawUrl。

{"type":"file","contentType":"image/png","contentLength":1234,"fileName":"image.png","code":"{code}","link":"https://raw.pub/{user}/{code}","version":1,"rawUrl":"https://1.raw.pub/{contentId}"}

读取原始内容

请求字段

路径 code 必填，无请求体。

请求示例

curl 'https://api.raw.pub/api/v1/links/{code}/raw'

响应

text/file 返回原始字节；远端文件返回 307；directory 返回当前切面 manifest；url 返回 400。

HTTP/1.1 200 OK · Content-Type: text/plain; charset=utf-8 · hello raw.pub

触发下载

请求字段

路径 code 必填，无请求体。

请求示例

curl --remote-header-name --remote-name 'https://api.raw.pub/api/v1/links/{code}/download'

响应

本地内容返回 200 和 attachment；远端文件返回 307 到带下载文件名的短期地址。

HTTP/1.1 307 Temporary Redirect · Location: {downloadUrl}