HTTP 라우트
HTTP 엔드포인트는 GraphQL 요청, 파일 전송, 기기 연결을 처리합니다. 요청 형식과 인증 요건은 아래 각 엔드포인트를 참조하세요.
타입 정의
# 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>작업
POST /graphql
주 GraphQL 엔드포인트입니다. API 토큰 모드는 c-id 및 Authorization: Bearer 헤더와 JSON을 사용하며 로그인 세션 모드는 암호화된 본문을 사용합니다.
curl 'https://<device-host>:<https-port>/graphql' \
-H 'c-id: <client-id>' -H ': Bearer <api-token>' \
-H 'Content-Type: application/json' \
--data '{"query":"{ app { deviceName capabilities access } }"}'GET /fs
암호화된 리소스 ID를 읽습니다. 세션은 c.CLIENT_ID.PAYLOAD, 활성 공유는 s.SHARE_ID.PAYLOAD입니다. 세션 링크는 GraphQL 인증 토큰이 아닌 호출자의 app.urlToken을 사용합니다. 링크를 비공개로 유지하세요. 세션을 취소하면 링크가 무효화됩니다. 작업은 PREVIEW, DOWNLOAD, PROBE, TRANSCODE이며 미리 보기 크기는 SM 또는 LG, 바이트 범위는 HTTP Range입니다. DESCRIBE는 접근이 허용된 파일 메타데이터와 디렉터리 항목을 반환합니다.
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.GET /zip/dir
접근이 허용된 디렉터리를 ZIP으로 다운로드합니다. 세션의 일반 /fs 리소스 ID 또는 활성 공유에 속한 디렉터리 ID를 사용합니다. 동시 작업 한도에 도달하면 HTTP 429가 반환될 수 있습니다.
curl 'https://<device-host>:<https-port>/zip/dir?id=<directory-resource-id>' -o directory.zipGET /zip/files
선택한 파일을 ZIP으로 다운로드합니다. 세션 전용의 별도 ZIP_FILES ID가 필요합니다. 일반 /fs ID와 공유 ID는 사용할 수 없습니다.
curl 'https://<device-host>:<https-port>/zip/files?id=<selection-archive-id>' -o selection.zipGET /health
인증 없는 연결 확인입니다. 일반 텍스트 본문 OK를 반환합니다.
curl 'https://<device-host>:<https-port>/health'POST /init
c-id와 활성화된 원격 접근이 필요합니다. 빈 본문은 설정을 검색하고 authenticated=false를 반환합니다. 기존 세션을 확인하려면 해당 인증 토큰으로 POST /init의 요청 봉투를 암호화합니다. 응답은 httpsPort(사용 가능한 HTTPS 리스너가 없으면 0)를 포함하며 opaquePublicKey와 TLS 증명 필드는 조건부입니다.
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.POST /guest_graphql
자체 게스트 계약이 있는 암호화된 공유 범위 API입니다. c-id는 활성 공유를 식별하며 API 토큰은 게스트 요청을 인가하지 않습니다.
# 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 } } }POST /peer_graphql
c-id: 발신자 클라이언트 ID. c-cid: 채팅 채널 ID. 채널 메시지는 c-cid를 포함하고 채널 키를 사용합니다. 직접 피어 요청은 이를 생략하고 페어링 키를 사용합니다.
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