PlainApp
API 参考

HTTP 路由

HTTP 接口用于 GraphQL 请求、文件传输和设备连接。各接口的请求格式与认证要求见下方示例。

类型定义

text
# HTTP
https://<device-host>:<https-port>

POST /graphql
POST /guest_graphql
POST /peer_graphql
GET /fs?id=<resource-id>&action=PREVIEW&size=SM
GET /zip/dir?id=<directory-resource-id>
GET /zip/files?id=<selection-archive-id>
POST /upload
POST /upload_chunk
POST /init
GET /health
POST /nearby
ANY /proxy/:peer/*path

# DLNA
GET/HEAD /dlna/description.xml
GET/HEAD /dlna/av-transport/scpd.xml
GET/HEAD /dlna/rendering-control/scpd.xml
POST /dlna/av-transport/control
POST /dlna/rendering-control/control
SUBSCRIBE/UNSUBSCRIBE /dlna/av-transport/event
SUBSCRIBE/UNSUBSCRIBE /dlna/rendering-control/event
GET/HEAD /dlna/media/:id
NOTIFY /dlna/callback

# WebSocket
wss://<device-host>:<https-port>/graphql?cid=<client-id>
wss://<device-host>:<https-port>/auth?cid=<client-id>
wss://<device-host>:<https-port>/screen?cid=<client-id>
wss://<device-host>:<https-port>/status?cid=<client-id>
wss://<device-host>:<https-port>/image_editor?cid=<client-id>

操作

http

POST /graphql

主 GraphQL 入口。API Token 模式使用 c-id、Authorization: Bearer 和 JSON;登录会话模式使用加密请求体。

bash
curl 'https://<device-host>:<https-port>/graphql' \
  -H 'c-id: <client-id>' -H 'Authorization: Bearer <api-token>' \
  -H 'Content-Type: application/json' \
  --data '{"query":"{ app { deviceName capabilities access } }"}'
http

GET /fs

读取加密资源 ID:c.CLIENT_ID.PAYLOAD 用于会话,s.SHARE_ID.PAYLOAD 用于有效共享。会话链接使用调用方的 app.urlToken,而不是 GraphQL 认证令牌。请勿公开链接;撤销所属会话后链接失效。DESCRIBE 返回获准访问的元数据和目录条目;PREVIEW、DOWNLOAD、PROBE、TRANSCODE 分别返回预览、原始文件、媒体信息和转码流。PREVIEW 的 size 可为 SM 或 LG。字节范围使用 HTTP Range 请求头。

bash
curl 'https://<device-host>:<https-port>/fs?id=<resource-id>&action=PREVIEW&size=SM' -o thumbnail
curl 'https://<device-host>:<https-port>/fs?id=<resource-id>&action=DOWNLOAD' -OJ
curl 'https://<device-host>:<https-port>/fs?id=<resource-id>&action=DESCRIBE'
# describe JSON: {"entry":{"url":"/fs?id=<resource-id>&action=DOWNLOAD","name":"example.txt","isDir":false,"sizeBytes":10},"children":[]}
# action: DESCRIBE | PREVIEW | DOWNLOAD | PROBE | TRANSCODE
# size: SM | LG (PREVIEW only); v: optional cache version
# Byte ranges use the HTTP Range header.
# id: c.<client-id>.<payload> or s.<share-id>.<payload>
# Session links use app.urlToken, not the GraphQL authentication token.
# Keep resource URLs private; revoking the owning session invalidates its links.
http

GET /zip/dir

下载获准访问的目录 ZIP。使用该目录的普通 /fs 资源 ID,可以来自会话或有效共享。并发压缩任务可能返回 HTTP 429。

bash
curl 'https://<device-host>:<https-port>/zip/dir?id=<directory-resource-id>' -o directory.zip
http

GET /zip/files

使用独立、仅限会话的 ZIP_FILES ID 下载选定文件的 ZIP。不接受普通 /fs ID 或共享 ID。

bash
curl 'https://<device-host>:<https-port>/zip/files?id=<selection-archive-id>' -o selection.zip
http

GET /health

无需认证的连通性检查,返回纯文本 OK。

bash
curl 'https://<device-host>:<https-port>/health'
http

POST /init

必须提供 c-id 并开启远程访问。空请求体用于发现配置,authenticated 为 false;检查已有会话时,用认证 token 发送绑定 POST /init 的加密请求信封。响应包含 httpsPort(无 HTTPS 监听时为 0);opaquePublicKey 和 TLS 证明字段按配置返回。

bash
curl 'https://<device-host>:<https-port>/init' -X POST -H 'c-id: <client-id>'
# An empty body discovers configuration; it does not prove session authentication.
# To check a session, send an encrypted request envelope bound to POST /init.
http

POST /guest_graphql

使用独立访客契约的加密共享接口。c-id 标识有效共享;API Token 不能直接授权此请求。

bash
# Share-scoped encrypted GraphQL, not an API-token request.
# c-id: <share-id>; request bound to POST /guest_graphql.
# Contract: plain-core/schema/guest-api.graphqls
query { sharedInfo { name readOnly requiresPassword entries { name relativePath isDir size } } }
http

POST /peer_graphql

c-id:发送端客户端 ID;c-cid:聊天频道 ID。频道消息携带 c-cid,使用频道密钥;点对点请求省略此头,使用配对密钥。

bash
curl 'https://<device-host>:<https-port>/peer_graphql' \
  -H 'c-id: <sender-client-id>' \
  -H 'c-cid: <channel-id>' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @peer-request.bin \
  --output peer-response.bin