↗raw.pub返回首页

V3 接口参考

raw.pub API 文档

接口固定使用 https://api.raw.pub。令牌直接确定用户，路径中不填写用户名。

账号验证

用户名是账号身份，同一邮箱可以绑定多个用户名。验证码挑战互相隔离，找回密码必须同时匹配用户名和邮箱。

开始邮箱注册

POSThttps://api.raw.pub/api/v1/auth/register

请求字段

username用户名，必填且全站唯一。
email接收验证码的邮箱，可绑定多个用户名。
password非空密码。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/auth/register' --header 'Content-Type: application/json' --data '{"username":"alice","email":"shared@example.com","password":"{password}"}'

响应

202 Accepted，返回后续验证所需的挑战 ID。

{"message":"verification code sent","email":"shared@example.com","challengeId":"{challengeId}"}

开始找回或重发验证码

POSThttps://api.raw.pub/api/v1/auth/email-codes

请求字段

username/email开始找回密码时必填。
purposeregister 或 reset。
challengeId重发已有挑战时必填。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/auth/email-codes' --header 'Content-Type: application/json' --data '{"username":"alice","email":"shared@example.com","purpose":"reset"}'

响应

202 Accepted。用户名与邮箱不匹配时也返回相同结构，但不会发信。

{"message":"if the request is valid, a verification code has been sent","challengeId":"{challengeId}"}

完成邮箱注册

POSThttps://api.raw.pub/api/v1/auth/verify

请求字段

challengeId注册响应返回的挑战 ID。
code6 位邮箱验证码。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/auth/verify' --header 'Content-Type: application/json' --data '{"challengeId":"{challengeId}","code":"{code}"}'

响应

201 Created，返回已创建用户。

{"username":"alice","email":"shared@example.com","active":true,"createdAt":"{time}"}

完成密码重置

POSThttps://api.raw.pub/api/v1/auth/password

请求字段

challengeId找回响应返回的挑战 ID。
code6 位邮箱验证码。
password新的非空密码。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/auth/password' --header 'Content-Type: application/json' --data '{"challengeId":"{challengeId}","code":"{code}","password":"{password}"}'

响应

200 OK，只重置挑战绑定的用户名，并撤销该用户全部 Session 和 API 令牌。

{"message":"password reset"}

规则

项目说明
个人空间发送 Authorization: Bearer {token}，服务端通过令牌反查用户。
公共空间不发送 Authorization；不支持别名，有效期仅支持 10m、1h、1d、3d、7d，默认 1d。创建响应中的 manageKey 可用于修改口令和有效期或删除该公共链接。
别名仅个人空间可用；只允许字母、数字和 ._~-。完整分享地址最多 2048 个字符，可用长度会随用户名长度变化。
口令passcode 为空或 1-8 位 URL 安全字符（字母、数字、._~-）；访问时使用 ?p={passcode}。
code只代表链接身份。相同内容可以创建多个 code，各自独立管理。
Content相同内容只保存一份；contentReused 表示内容复用，不表示 code 复用。
编辑传读取到的 version；并发版本冲突返回 409。

Link 字段

字段类型说明
idnumber记录 ID。
ownerstring个人用户名；公共空间为空。
code/aliasstring链接 code 和个人别名。
passcodestring当前访问口令；空字符串表示未设置。
kindstringtext、url、file、directory。
valuestring内容摘要。
fileName/contentTypestring文件名和媒体类型。
sizeBytesnumber内容字节数。
hashstring内容摘要。
tagsstring[]normal、attachment，可同时存在。
versionnumber可编辑 Head 版本。
deadlinestring|nullRFC 3339 失效时间；null 为长期。
createTime/modifyTimestringRFC 3339 时间。
linkstring分享地址；有别名时使用别名。
contentReusedboolean是否复用了已有 Content。
expired/recoverableboolean失效和 30 天恢复期状态。

创建

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

POSThttps://api.raw.pub/api/v1/links

请求字段

字段类型必填说明
originstring文本/网址必填文本或 HTTP/HTTPS 网址。
kindstring否text、url、file。
fileCodestringfile 必填引用同空间已有文件。
fileNamestring否引用文件的新名称。
aliasstring否个人别名。
deadlinestring否RFC 3339。
passcodestring否访问口令；为空表示不设口令。地址类型不支持口令。

请求示例

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。公共空间另外返回只在创建响应可见的 manageKey，用于以后修改口令和有效期或删除链接。

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

小文件上传

POSThttps://api.raw.pub/api/v1/links

请求字段

filebinary，必填。
alias个人别名。
expiry/deadline有效时长或 RFC 3339 截止时间。
passcode可选访问口令。
tagnormal 或 attachment。

请求示例

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}

大文件直传

申请上传地址

POSThttps://api.raw.pub/api/v1/uploads

请求字段

fileName/contentType文件名和媒体类型，必填。
sizeBytes字节数，必填。
contentHashMD5 十六进制拼 SHA-256 十六进制，必填。
contentMD5MD5 Base64，必填。
tagnormal 或 attachment。

请求示例

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任务 ID。
upload.method/url/headers直接上传参数。
completeUrl完成确认接口。
link内容已存在时直接返回新 Link。

响应示例

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

确认上传完成

POSThttps://api.raw.pub/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}

目录

创建完整目录树

POSThttps://api.raw.pub/api/v1/directories

请求字段

directoryName根名；/ 表示虚拟根。
children完整有序树。
children[].name同级不可重名。
children[].code引用文件或已有目录时填写；网址也可以只截取最后的 code 或 alias。
children[].children普通子目录填写；与 code 二选一。

请求示例

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}]}}

更新目录或目录切面

PUThttps://api.raw.pub/api/v1/directories/{code}

请求字段

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"}]}}

为子目录生成切面链接

POSThttps://api.raw.pub/api/v1/links/{code}/slices

请求字段

path子目录路径，必填。
alias可选个人别名。

请求示例

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"}

一行上传本地目录

GEThttps://api.raw.pub/upd

请求字段

{目录}本地目录路径，必填。
{token}个人 API 令牌；省略则上传到公共空间。
{有效期}可选，例如 7d。

请求示例

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

响应

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

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

链接管理

滚动加载链接列表

GEThttps://api.raw.pub/api/v1/links

请求字段

page/size页码和数量，size 最大 100。
statusactive、expired、all。
tagnormal、attachment、all；默认 all。

请求示例

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

响应字段

listLink[]；directory 额外包含 tree。
total/page/size/hasMore滚动加载状态。

响应示例

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

按内容摘要检查是否存在

GEThttps://api.raw.pub/api/v1/links?hash={hash}

请求字段

hash内容摘要，必填。

请求示例

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

响应字段

exists是否存在可用 Content。
sameSpace是否已有当前空间 Link。
linksameSpace 为 true 时返回已有链接。

响应示例

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

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

PUThttps://api.raw.pub/api/v1/links/{code}

请求字段

kindtext、url、file。
origintext/url 内容。
fileCodefile 来源 code。
fileName/contentType可选文件元数据。
version当前版本。

请求示例

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}

修改别名、有效期或口令

PATCHhttps://api.raw.pub/api/v1/links/{code}

请求字段

aliasstring|null；空值清除，仅个人空间。
deadlineRFC 3339|null；个人空间的 null 表示长期；公共空间必须是未来 7 天内的时间。
passcodestring|null；空值清除，地址类型只能清除。个人空间使用 Bearer 令牌；公共空间修改口令或有效期时，使用创建响应中的 manageKey 作为 X-RawPub-Manage-Key。

请求示例

curl --request PATCH 'https://api.raw.pub/api/v1/links/{code}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"passcode":"Ab_1"}'

curl --request PATCH 'https://api.raw.pub/api/v1/links/{code}' --header 'X-RawPub-Manage-Key: {manageKey}' --header 'Content-Type: application/json' --data '{"deadline":"2026-09-25T12:00:00Z"}'

响应

200 OK。

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

另存为独立链接

POSThttps://api.raw.pub/api/v1/links/{code}/save-as

请求字段

可选 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}

删除链接

DELETEhttps://api.raw.pub/api/v1/links/{code}

请求字段

路径 code 必填，无请求体。个人链接必须使用所属用户令牌；公共链接必须使用创建响应中的 manageKey。

请求示例

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

curl --request DELETE 'https://api.raw.pub/api/v1/links/{code}' --header 'X-RawPub-Manage-Key: {manageKey}'

响应

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

HTTP/1.1 204 No Content

读取

读取元数据

GEThttps://api.raw.pub/api/v1/links/{code}/meta

请求字段

路径 code 或 alias 必填；受保护链接增加查询参数 p。

请求示例

curl 'https://api.raw.pub/api/v1/links/{code}/meta?p={passcode}'

响应字段与示例

返回 type、contentType、contentLength、fileName、value、code、alias、link、version；value 是 url 和隧道的目标地址，其余类型为 null；目录增加 tree，远端文件增加 rawUrl。

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

读取原始内容

GEThttps://api.raw.pub/api/v1/links/{code}/raw

请求字段

路径 code 必填；受保护链接增加查询参数 p。

请求示例

curl 'https://api.raw.pub/api/v1/links/{code}/raw?p={passcode}'

响应

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

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

触发下载

GEThttps://api.raw.pub/api/v1/links/{code}/download

请求字段

路径 code 必填；受保护链接增加查询参数 p。

请求示例

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

响应

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

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

SSH 隧道

隧道客户端属于账号，代表 raw.pub 与一台机器的连接。一个客户端只需运行一次命令，就能服务这台机器上的多个本地端口；每条链接用自己的 target 决定访问哪个本机地址和路径。

命令形如 curl -fsSL https://api.raw.pub/t/{token}.sh | sh。客户端在入口建立反向 SOCKS 监听，raw.pub 再按每条链接的本机 target 拨号。复制命令不会写服务端状态；第一次下载脚本时才准备监听端口和钥匙。断开按 Ctrl+C。

列出隧道客户端

GEThttps://api.raw.pub/api/v1/tunnels

请求字段

无。令牌自动决定账号。

请求示例

curl 'https://api.raw.pub/api/v1/tunnels' --header 'Authorization: Bearer {token}'

响应字段与示例

id、name、online、scriptCommand、scriptWindowsCommand。

{"list":[{"id":1,"name":"macbook","online":true,"scriptCommand":"curl -fsSL https://api.raw.pub/t/{token}.sh | sh","scriptWindowsCommand":"irm https://api.raw.pub/t/{token}.ps1 | iex"}],"total":1}

创建隧道客户端

POSThttps://api.raw.pub/api/v1/tunnels

请求字段

name必填，账号内唯一的客户端名称。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/tunnels' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"name":"macbook"}'

响应字段与示例

201 Created，返回客户端及其两条连接命令。

{"id":1,"name":"macbook","online":false,"scriptCommand":"curl -fsSL https://api.raw.pub/t/{token}.sh | sh","scriptWindowsCommand":"irm https://api.raw.pub/t/{token}.ps1 | iex"}

修改隧道客户端

PATCHhttps://api.raw.pub/api/v1/tunnels/{id}

请求字段

id路径必填，来自客户端列表。
name必填，新名称。

请求示例

curl --request PATCH 'https://api.raw.pub/api/v1/tunnels/{clientId}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"name":"office-mac"}'

响应字段与示例

200 OK，返回修改后的客户端和最新命令。

{"id":1,"name":"office-mac","online":false,"scriptCommand":"curl -fsSL https://api.raw.pub/t/{token}.sh | sh","scriptWindowsCommand":"irm https://api.raw.pub/t/{token}.ps1 | iex"}

删除隧道客户端

DELETEhttps://api.raw.pub/api/v1/tunnels/{id}

请求字段

路径 id 必填。使用它的链接会保留，但隧道选择会被清空。

请求示例

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

响应

204 No Content，没有响应体。

(无响应体)

断开隧道客户端连接

DELETEhttps://api.raw.pub/api/v1/tunnels/{id}/connection

请求字段

路径 id 必填。只清除当前连接准备，保留客户端和链接的隧道选择；需要重新运行时再执行一次命令。

请求示例

curl --request DELETE 'https://api.raw.pub/api/v1/tunnels/{clientId}/connection' --header 'Authorization: Bearer {token}'

响应

204 No Content，没有响应体。

(无响应体)

为链接选择隧道客户端

PATCHhttps://api.raw.pub/api/v1/callbacks/{code}

请求字段

tunnelClientId隧道客户端 id；0 表示不使用隧道。省略时保留原选择。
status在线之前或默认返回的状态码。
params默认返回的参数对象。
headers默认返回的响应头数组。
body默认返回正文。
queueSeconds离线保存队列时长，0 表示不保存。

请求示例

curl --request PATCH 'https://api.raw.pub/api/v1/callbacks/{code}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"status":503,"params":{},"headers":[],"body":"{\"error\":\"offline\"}","queueSeconds":3600,"tunnelClientId":1}'

响应字段与示例

200 OK，返回保存后的地址配置。

{"status":503,"params":{},"headers":[],"body":"{\"error\":\"offline\"}","queueSeconds":3600,"tunnelClientId":1,"useSubdomain":false}

列出隧道公钥

GEThttps://api.raw.pub/api/v1/ssh-keys

请求字段

无账号由 Authorization 令牌决定。

请求示例

curl --request GET 'https://api.raw.pub/api/v1/ssh-keys' --header 'Authorization: Bearer {token}'

响应

200 OK，返回该账号登记的全部公钥。

{"list":[{"id":"{keyId}","name":"macbook","publicKey":"ssh-ed25519 AAAAC3Nza...","fingerprint":"SHA256:AbCdEf...","createdAt":"{time}"}],"total":1}

登记隧道公钥

POSThttps://api.raw.pub/api/v1/ssh-keys

请求字段

publicKey必填，一行公钥，例如 ssh-ed25519 AAAA... 。私钥永远留在你自己机器上。
name可选备注；不填时用指纹。

请求示例

curl --request POST 'https://api.raw.pub/api/v1/ssh-keys' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{"name":"macbook","publicKey":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@mac"}'

响应

201 Created。同一把公钥不能登记到两个账号。

{"id":"{keyId}","name":"macbook","publicKey":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...","fingerprint":"SHA256:AbCdEf...","createdAt":"{time}"}

删除隧道公钥

DELETEhttps://api.raw.pub/api/v1/ssh-keys/{id}

请求字段

{id}路径里的公钥 ID，来自列表响应。删除后正在使用它的隧道会在下一次认证时失效。

请求示例

curl --request DELETE 'https://api.raw.pub/api/v1/ssh-keys/{keyId}' --header 'Authorization: Bearer {token}'

响应

204 No Content，没有响应体。

(无响应体)

错误响应

{"status":409,"error":"link changed since it was loaded"}
状态说明
400字段、内容、目录树或摘要无效。
401令牌无效，或链接缺少口令。
403空间无权限，或链接口令错误。
404链接、切面或上传任务不存在。
409别名、切面或版本冲突。
413超过大小上限。
503远端存储不可用。