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 トークンモードでは 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 です。セッションリンクでは、GraphQL 認証トークンではなく呼び出し元の app.urlToken を使用します。リンクは非公開にしてください。セッションを失効するとリンクも無効になります。操作は PREVIEW、DOWNLOAD、PROBE、TRANSCODE、プレビューサイズは SM または LG、バイト範囲は HTTP Range です。 DESCRIBE はアクセスが許可されたファイルのメタデータとディレクトリ項目を返します。

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、または有効な共有内のディレクトリ ID を使用します。同時実行の上限に達すると HTTP 429 が返ることがあります。

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

GET /zip/files

選択したファイルを ZIP でダウンロードします。セッション専用の別の ZIP_FILES ID が必要です。通常の /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 を返します。既存セッションを確認するには、その認証トークンを使って 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 トークンはゲストリクエストを認可しません。

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