Platform Overview

Disk.Top Open Platform

Build integrations with Disk.Top's cloud storage using OAuth 2.0 and REST APIs.

#Quick Links

• OAuth 2.0 Overview — Authorization Code, Device Code, Refresh Token grants
• Authorization Code Flow — Web & Wap apps
• Device Code Flow — CLI, TV, mobile QR
• Scopes — Permission model (sandbox vs full-disk)
• User API — Profile, quota
• Files API — Upload, list, search, download, stream
• Share API — Public share resolution, transfer

#Getting Started in 4 Steps

1. Create an app at /console — get client_id + client_secret

2. Redirect users to authorize:

   GET https://openapi.disk.top/oauth/authorize?client_id=YOUR_ID&redirect_uri=YOUR_CALLBACK&response_type=code&scope=user.read+files.app_data&state=xyz

3. Exchange code for access_token:

   POST https://openapi.disk.top/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=...&client_id=...&client_secret=...&redirect_uri=...

4. Call APIs with Bearer token:

   curl -H "Authorization: Bearer ACCESS_TOKEN" https://openapi.disk.top/v1/user/info

#Sandbox Model

By default (files.app_data scope), your app gets a dedicated directory under the user's cloud: /我的应用数据/<YourAppName>/. All file operations are confined to this sandbox.

For full-disk access, request files.read_all / files.write_all scopes — users will see explicit warnings on the consent page.

OAuth 2.0 Overview

OAuth 2.0 Overview

Disk.Top supports three OAuth 2.0 grant types.

#1. Authorization Code Grant (Web)

Standard server-side flow with redirect_uri. Use for web/wap apps.

See Authorization Code Flow for details.

#2. Device Code Grant (CLI / TV)

For devices without a browser (CLI tools, Android TV, IoT). The device shows a user_code and verification_uri; user visits the URL on their phone, enters the code, and approves.

See Device Code Flow.

#3. Refresh Token

Standard grant_type=refresh_token — exchange a refresh_token for a new access_token. Refresh tokens rotate on each use.

POST https://openapi.disk.top/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=...&client_id=...&client_secret=...

#PKCE Support

All grants support PKCE (code_challenge / code_verifier). Recommended for mobile apps and SPAs where client_secret cannot be stored securely.

# Generate
code_verifier = base64url(random(32))
code_challenge = base64url(SHA256(code_verifier))

# In /oauth/authorize URL
&code_challenge=...&code_challenge_method=S256

# In /oauth/token request
&code_verifier=...

Authorization Code Flow

Authorization Code Flow

Applies to all 5 application types: Web, Mobile_web, Android, iOS, Desktop.

#Common Flow

#Step 1: Redirect user to /oauth/authorize

GET https://openapi.disk.top/oauth/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_CALLBACK
  &response_type=code
  &scope=user.read+files.app_data
  &state=RANDOM_STATE
  &code_challenge=...           # optional PKCE (recommended; mandatory for mobile/desktop)
  &code_challenge_method=S256

If the user is not logged in to Disk.Top, the platform first redirects them to the login page (cp.disk.top/#/auth/login?next=...) and then returns to the authorize URL after login.

#Step 2: User consents

The user sees the consent page (with requested scopes). On Allow, the platform 302s to the redirect_uri:

{redirect_uri}?code=AUTH_CODE&state=RANDOM_STATE

On Deny:

{redirect_uri}?error=access_denied&state=RANDOM_STATE

#Step 3: Exchange code for access_token

POST https://openapi.disk.top/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET   # required for web/server; mobile/desktop must use PKCE instead
&redirect_uri=YOUR_CALLBACK
&code_verifier=...                  # if using PKCE

Response:

{
  "access_token": "Pc0yjnIrGqKr39YQY85i...",
  "refresh_token": "T_roVaOwg7X_NrSCm...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "user.read files.app_data"
}

#Step 4: Use access_token to call APIs

curl -H "Authorization: Bearer Pc0yjnIrGq..." \
  https://openapi.disk.top/v1/user/info

#Error Responses

#Integration by Application Type

Different application_type values differ in redirect_uri format and client_secret usage.

#1. Web App

• application_type=web
• redirect_uri must be https:// (localhost exception: http://localhost)
• Backend holds client_secret; code → token exchange uses secret
• PKCE not required (but recommended for defense in depth)

redirect_uri = https://yourapp.com/oauth/callback

Integration steps:

1. Register the app in Console with type web, supply callback URL
2. Backend implements the callback route to receive code, calls /oauth/token with client_secret to exchange tokens
3. Store tokens in database (refresh valid 30 days)

#2. Mobile Web (mobile_web)

• application_type=mobile_web
• Same https:// requirement as web
• Typically for PWA / SPA frontends
• PKCE recommended to avoid frontend client_secret leakage

redirect_uri = https://m.yourapp.com/oauth/callback

#3. Android Native

• application_type=android
• redirect_uri must be a custom scheme (reverse-domain + :// path)
• PKCE is mandatory (cannot keep client_secret secret on device)

redirect_uri = com.yourcompany.yourapp:/oauth/callback

Android implementation:

1. Register intent-filter in AndroidManifest.xml:

<activity android:name=".OAuthCallbackActivity">
  <intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="com.yourcompany.yourapp" android:host="oauth"/>
  </intent-filter>
</activity>

2. Generate PKCE pair:

val codeVerifier = base64Url(SecureRandom().nextBytes(32))
val codeChallenge = base64Url(SHA256(codeVerifier))

3. Open the authorize URL via the system browser (Custom Tabs recommended)
4. Receive callback intent, extract code, POST /oauth/token with code_verifier

#4. iOS Native

• application_type=ios
• redirect_uri must be a custom scheme or an https Universal Link
• PKCE is mandatory

# Custom scheme
redirect_uri = com.yourcompany.yourapp:/oauth/callback

# Or Universal Link
redirect_uri = https://yourapp.com/applinks/oauth

iOS implementation:

1. Register URL Type in Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array><string>com.yourcompany.yourapp</string></array>
  </dict>
</array>

2. Open the authorize URL via ASWebAuthenticationSession (iOS 12+)
3. Receive callback, extract code, call /oauth/token with code_verifier

#5. Desktop App

• application_type=desktop
• redirect_uri must be a loopback IP: http://127.0.0.1[:port] or http://localhost[:port]
• PKCE is mandatory

redirect_uri = http://127.0.0.1:51729/oauth/callback

Desktop implementation:

1. Start a local HTTP server on a random port listening at /oauth/callback
2. Generate PKCE pair
3. Open the authorize URL via the system default browser (do not embed a WebView)
4. Receive the callback HTTP request, extract code, close the local server
5. Exchange code for tokens via /oauth/token, store tokens in the OS keychain (macOS Keychain / Windows DPAPI / Linux libsecret)

#PKCE (recommended for all non-web types)

PKCE = Proof Key for Code Exchange (RFC 7636). Prevents code replay if intercepted during redirect.

Generate:

code_verifier  = random 43-128 chars (A-Z a-z 0-9 - . _ ~)
code_challenge = base64url(sha256(code_verifier))     # method=S256

Include code_challenge + code_challenge_method=S256 on the authorize request; include code_verifier on the token request. The server verifies sha256(code_verifier) == code_challenge.

#refresh_token

When an access_token expires, refresh:

POST /oauth/token
grant_type=refresh_token
&refresh_token=T_roVaOwg7X_NrSCm...
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET   # required for web/server types

refresh_token is valid for 30 days.

#Device Code Flow

For TVs, IoT, and other no-browser devices, see oauth-device-code.

Device Code Flow (CLI / TV)

Device Code Flow

For headless devices (CLI tools, Android TV, IoT) where a full browser-based OAuth flow is impractical.

#Step 1: Request a device code

POST https://openapi.disk.top/oauth/device-code
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&scope=user.read+files.app_data

Response:

{
  "device_code": "sHxGyZ9rEd73E6PYg2yEdWWps9evt_oTDOqzFcxQJRxsZEUk",
  "user_code": "8KXH-Y8R",
  "verification_uri": "https://openapi.disk.top/oauth/device",
  "verification_uri_complete": "https://openapi.disk.top/oauth/device?user_code=8KXH-Y8R",
  "qr_url": "https://api.qrserver.com/v1/create-qr-code/?size=240x240&data=...",
  "expires_in": 600,
  "interval": 5
}

#Step 2: Display to user

Show the user_code AND/OR QR code on your device. User visits verification_uri on their phone, enters the code, and approves.

#Step 3: Poll for token

POST https://openapi.disk.top/oauth/device-token
Content-Type: application/x-www-form-urlencoded

device_code=sHxG...&client_id=YOUR_CLIENT_ID

Possible responses:

• {"error":"authorization_pending"} — keep polling (respect interval)
• {"error":"access_denied"} — user denied; stop polling
• {"error":"expired_token"} — device_code expired; restart
• {"access_token": "...", "refresh_token": "...", ...} — success!

Scopes

Scopes

Permissions your app requests at authorization time. Users see the exact list on the consent page.

#Default (Sandbox Model)

• user.read — Read user profile (uid, username, email, avatar, VIP status)
• files.app_data — Default sandbox. Read/write files within a dedicated directory /我的应用数据/<YourAppName>/ in the user's cloud. Cannot access user's other files.

#Sensitive (Explicit Consent Required)

These scopes give your app broader access. Users see warnings on the consent page.

• files.read_all — Read all user files (across all directories)
• files.write_all — Write/delete any user file
• share.read — List all the user's shares
• share.create — Create new shares on behalf of the user

#Best Practices

1. Request the minimum scopes you need. Users abandon apps that ask too much.
2. Use sandbox (files.app_data) unless you really need full-disk access.
3. New apps default to sandbox-only — broader scopes require admin review.
4. Users can revoke any time at disk.top/user/apps.

User API

User API

Endpoints to read the OAuth user's profile / quota and toggle share creation.

#User Profile

Returns the authenticated user (uid, nickname, avatar, VIP, granted scopes).

#Endpoint

https://openapi.disk.top/v1/user/info

#Method

GET

#Request Parameters

#Example Request

curl "https://openapi.disk.top/v1/user/info" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

#Response Fields

#Example Response

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "uid": 17,
    "username": "dwtonline",
    "nickname": "jam",
    "email": "[email protected]",
    "avatar_url": "https://disk.top/uploads/upload/avatar/17_xxx.jpg",
    "is_vip": false,
    "vip_group": 3,
    "vip_expire_ts": 0,
    "storage_quota_bytes": 1610612736000,
    "created_at_ts": 1636115986,
    "oauth": {
      "client_id": "your_client_id",
      "scopes": ["user.read","files.app_data"]
    }
  }
}

#Quota

Returns the user's total / used / free storage and percentage. Use this to render a storage progress bar.

#Endpoint

https://openapi.disk.top/v1/user/quota

#Method

GET

#Request Parameters

#Example Request

curl "https://openapi.disk.top/v1/user/quota" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

#Response Fields

#Example Response

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "total_bytes": 1610612736000,
    "used_bytes": 33691310918,
    "free_bytes": 1576921425082,
    "used_pct": 2.09
  }
}

#Enable Share Capability

Activate share-link creation for the authenticated user (call once per integration). After enabling, the /v1/share/* create endpoints become available.

#Endpoint

https://openapi.disk.top/v1/user/share-enable

#Method

POST

#Request Parameters

#Example Request

curl -X POST "https://openapi.disk.top/v1/user/share-enable" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

#Response Fields

#Example Response

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "enabled": true,
    "note": "Share endpoints are now active."
  }
}

Files API

Files API

OAuth apps read and write user files. The default scope files.app_data constrains operations to the app's sandbox folder /{Localized My App Data}/{AppName}/; files.write_all grants full-disk access (requires explicit user consent).

Upload protocol: precreate (get upload_id + endpoint) → upload chunks → complete. Client does not need to know how the backend stores files.

#List Directory

List sub-folders + files at a path (sandbox or full disk).

#Endpoint

https://openapi.disk.top/v1/files

#Method

GET

#Request Parameters

#Example Request

curl -G "https://openapi.disk.top/v1/files" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "path=/" --data-urlencode "limit=20"

#Response Fields

#Example Response

{
  "errno":0,"errmsg":"ok",
  "data":{
    "path":"/","folders":[{"id":5911,"name":"GPTGet"}],
    "files":[{"id":7280,"name":"chat-1.md","size":1024,"md5":"abc..."}],
    "total":2
  }
}

#Search Files

Search by name / extension within sandbox (or full disk with files.read_all).

#Endpoint

https://openapi.disk.top/v1/files/search

#Method

GET

#Request Parameters

#Example Request

curl -G "https://openapi.disk.top/v1/files/search" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "q=chat"

#Example Response

{"errno":0,"data":{"files":[{"id":7280,"name":"chat-573.md","size":1024,"md5":"abc..."}],"total":1}}

#File Metadata

Get file details by id (path / md5 / size / upload time / mime).

#Endpoint

https://openapi.disk.top/v1/files/{id}

#Method

GET

#Request Parameters

#Example Response

{
  "errno":0,
  "data":{
    "id":7280,"name":"chat-573.md","size":1024,
    "md5":"abc...","ext":"md","mime":"text/markdown",
    "path":"/My App Data/GPTGet/chat-573.md",
    "parent_folder":5911,
    "create_time":1779051234
  }
}

#File Download

Get a signed download URL (valid 10 minutes, supports Range / resume).

#Endpoint

https://openapi.disk.top/v1/files/{id}/download

#Method

GET

#Request Parameters

#Response Fields

#Example Response

{
  "errno":0,
  "data":{
    "url":"https://dl.disk.top/abc/file.mp4?sig=...&exp=...",
    "expires_in":600,
    "name":"demo.mp4","size":8388608,"md5":"abc..."
  }
}

#Video Streaming

For video files, returns HLS / DASH playlist URL for in-browser playback.

#Endpoint

https://openapi.disk.top/v1/files/{id}/stream

#Method

GET

#Example Response

{
  "errno":0,
  "data":{
    "stream_url":"https://dl.disk.top/hls/abc/master.m3u8?sig=...",
    "duration":1800,
    "qualities":[{"name":"1080p","url":"..."}],
    "expires_in":600
  }
}

#Create Folder

Create a new folder under a parent path.

#Endpoint

https://openapi.disk.top/v1/files/folder

#Method

POST

#Request Parameters

#Example Request

curl -X POST "https://openapi.disk.top/v1/files/folder" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "parent_path=/&name=Photos"

#Example Response

{"errno":0,"data":{"folder_id":5920,"name":"Photos","path":"/My App Data/GPTGet/Photos"}}

#Rename / Move / Copy / Delete

Batch operations (one request can affect multiple files / folders).

#Endpoint

https://openapi.disk.top/v1/files/manage

#Method

POST

#Request Parameters

#Example Requests

# Delete
curl -X POST "https://openapi.disk.top/v1/files/manage" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "action=delete&file_ids[]=7280&file_ids[]=7281"

# Rename
curl -X POST "https://openapi.disk.top/v1/files/manage" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "action=rename&file_ids[]=7280&new_name=updated.md"

#Example Response

{"errno":0,"data":{"affected":2}}

#Upload: precreate (dedup check + open upload session)

Step 1 of upload. Submit md5 + size; if dedup hits, returns file_id directly; otherwise returns upload_id and chunk parameters.

#Endpoint

https://openapi.disk.top/v1/files/upload/precreate

#Method

POST

#Request Parameters

#Example Request

curl -X POST "https://openapi.disk.top/v1/files/upload/precreate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "parent_path=/&name=movie.mp4&size=104857600&md5=5eb63bbbe01eeed093cb22bb8f5acdc3"

#Response Fields

#Example Response

{
  "errno":0,
  "data":{
    "instant_upload":false,
    "upload_id":"a747204b5517044b304fe07b649c6bdc",
    "endpoint":"https://openapi-upload.disk.top",
    "chunk_size":5242880,
    "total_parts":20,
    "expires_in":86400
  }
}

Dedup hit:

{"errno":0,"data":{"instant_upload":true,"file_id":7266,"path":"/My App Data/GPTGet/movie.mp4","size":104857600}}

#Upload: chunk (upload a single chunk)

Slice by precreate's chunk_size, call this endpoint once per chunk (POST directly to endpoint).

#Endpoint

{endpoint}/u?upload_id={upload_id}&part_seq={N}

{endpoint} is from precreate response. {N} starts from 1.

#Method

POST

#Request Parameters

#Example Request

# Chunk 1
dd if=movie.mp4 bs=5242880 count=1 skip=0 | \
  curl -X POST "https://openapi-upload.disk.top/u?upload_id=a747...&part_seq=1" \
    -H "Content-Type: application/octet-stream" --data-binary @-

# Repeat for N chunks

#Response Fields

#Example Response

{"errno":0,"data":{"part_seq":1,"etag":"abc123...","size":5242880,"received_parts":1,"total_parts":20}}

#Upload: query progress / received chunks (for resume)

Query which chunks have been received; client can skip them and resume.

#Endpoint

{endpoint}/u/{upload_id}/parts

#Method

GET

#Response Fields

#Example Response

{
  "errno":0,
  "data":{
    "upload_id":"a747...",
    "total_parts":20,
    "received_parts":[1,2,3,5,6,7],
    "progress":35.0,
    "parts":{"1":{"part_number":1,"etag":"abc","size":5242880},"...":{}}
  }
}

#Upload: complete (merge + finalize)

After all chunks are uploaded, call this endpoint. Server merges chunks and finalizes; returns file_id.

#Endpoint

{endpoint}/u/{upload_id}/complete

#Method

POST

#Response Fields

#Example Response

{
  "errno":0,
  "data":{
    "file_id":7280,
    "path":"/My App Data/GPTGet/movie.mp4",
    "size":104857600,
    "md5":"5eb63bbbe01eeed093cb22bb8f5acdc3"
  }
}

Errors:

• 425 incomplete: N/M — Some chunks missing; query /parts to find which ones to retry
• 502 complete failed — Server-side error; retry or check status

#Upload: abort (cancel + cleanup)

Actively cancel the upload; server releases the chunk resources.

#Endpoint

{endpoint}/u/{upload_id}/abort

#Method

POST

#Example Response

{"errno":0,"data":{"ok":true}}

Share API

Share API

Operate on Disk.Top public shares (the /s/{surl} short links). All endpoints require Authorization: Bearer {access_token}, scope share.read or share.create (transfer also requires files.app_data or files.write_all).

{surl} is the share short-link code (e.g. 8d2f3a), not the database share_id.

#Verify Share Password

If the share is password-protected, call this first to swap password for a session (subsequent calls then skip pwd).

#Endpoint

https://openapi.disk.top/v1/share/{surl}/verify-pwd

#Method

POST

#Request Parameters

#Example Request

curl -X POST "https://openapi.disk.top/v1/share/8d2f3a/verify-pwd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "pwd=1234"

#Response Fields

#Example Response

{"errno":0,"errmsg":"ok","data":{"verified":true}}

#Share Info

Get share metadata (type, password required, expiry, file count, etc.).

#Endpoint

https://openapi.disk.top/v1/share/{surl}/info

#Method

GET

#Request Parameters

#Example Request

curl "https://openapi.disk.top/v1/share/8d2f3a/info" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

#Response Fields

#Example Response

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "surl": "8d2f3a",
    "type": 1,
    "need_pwd": false,
    "expire_time": 0,
    "source_count": 5,
    "premium": false
  }
}

#List Share Files

List files / sub-folders in the share. Folder shares: browse by path. File shares: returns the single file directly.

#Endpoint

https://openapi.disk.top/v1/share/{surl}/files

#Method

GET

#Request Parameters

#Example Request

curl -G "https://openapi.disk.top/v1/share/8d2f3a/files" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "path=/" --data-urlencode "pwd=1234"

#Response Fields

#Example Response

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "files": [
      {"id": 12345, "name": "demo.mp4", "size": 8388608, "ext": "mp4", "is_dir": false},
      {"id": 12346, "name": "docs", "size": 0, "ext": "", "is_dir": true}
    ]
  }
}

#Transfer Share File to Sandbox

Copy shared files into the OAuth user's sandbox directory.

#Endpoint

https://openapi.disk.top/v1/share/{surl}/transfer

#Method

POST

#Request Parameters

#Example Request

curl -X POST "https://openapi.disk.top/v1/share/8d2f3a/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "file_ids[]=12345&dest_path=/Saved&pwd=1234"

#Response Fields

#Example Response

{"errno":0,"errmsg":"ok","data":{"transferred":1,"file_ids":[7890]}}

#Share Video Streaming

Returns HLS / direct-stream URL for a shared video file (valid 10 minutes).

#Endpoint

https://openapi.disk.top/v1/share/{surl}/stream

#Method

GET

#Request Parameters

#Response Fields

#Example Response

{
  "errno":0,
  "data":{
    "stream_url":"https://dl.disk.top/hls/abc/master.m3u8?sig=...",
    "duration":1800,
    "qualities":[{"name":"1080p","url":"..."}],
    "expires_in":600
  }
}

#Share Video Metadata

Returns video metadata (duration, resolution, codec, cover) — for player init / thumbnails.

#Endpoint

https://openapi.disk.top/v1/share/{surl}/video-meta

#Method

GET

#Request Parameters

#Example Response

{
  "errno":0,
  "data":{
    "duration":1800,
    "width":1920,
    "height":1080,
    "codec":"h264",
    "bitrate":2500000,
    "cover_url":"https://s3.disk.top/.../cover.jpg"
  }
}

#Share File Download

Get a signed temporary download URL for a shared file (valid 10 minutes, login-free).

#Endpoint

https://openapi.disk.top/v1/share/{surl}/download

#Method

GET

#Request Parameters

#Example Request

curl -G "https://openapi.disk.top/v1/share/8d2f3a/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "fid=12345" \
  --data-urlencode "pwd=1234"

#Response Fields

#Example Response

{
  "errno":0,
  "data":{
    "file_id":12345,
    "name":"demo.mp4",
    "size":8388608,
    "url":"https://api.disk.top/v1/internal/openapi/share-download/8d2f3a/12345?ts=1779051234&sig=ab12c3...",
    "expires_in":600
  }
}

#Error Codes