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

採用獨立訪客契約的加密分享 API。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