API Developer Documentation - Archive Cloud Storage

1. Overview & Conventions

The Archive Cloud Storage Open Platform is built on a standard RESTful architecture and the OAuth 2.0 authorization protocol. All APIs are served securely over HTTPS and return JSON responses (except the binary file download endpoint).

Base URL

https://2zip.app/api

Get credentials: Before integrating, request the Client ID and Client Secret for your application via partner@2zip.app.

2. OAuth 2.0 Authorization Flow

The platform uses the industry-standard Authorization Code Grant, in three stages: directing the user to authorize, obtaining an Access Token, and calling APIs with the token.

1 Step 1: Direct the user to authorize

In your app (web / mobile / desktop), have the user open the authorization link in a browser:

GET https://2zip.app/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&response_type=code&state=RANDOM_STATE

After the user clicks [Authorize], we redirect to your callback URL:https://your-app.com/callback?code=AUTH_CODE&state=RANDOM_STATE

2 Step 2: Exchange the Authorization Code for an Access Token

Your backend sends a POST request to exchange the code for a token:

POST https://2zip.app/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&code=AUTH_CODE

Success response

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1QiLC...",
  "refresh_token": "def502008..."
}

3 Step 3: Call APIs with the Access Token

Add the following headers when calling any protected API:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

GET /api/user

Get the basic profile and storage usage of the currently authorized user.

cURL example

curl -X GET "https://2zip.app/api/user" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "developer",
    "nickname": "782910",
    "points": 100,
    "space": 1048576,
    "space_used": 2048,
    "created_at": "2025-01-01T00:00:00.000000Z"
  }
}

GET /api/files

List the files and folders in the user's drive (supports directory levels, keyword search and pagination).

Query Parameters

Parameter	Type	Required	Description
folder_id	integer/string	No	Parent folder ID (pass root or 0 for the root directory)
search	string	No	Fuzzy search by file name
is_folder	boolean	No	Query only folders (true) or only files (false)
per_page	integer	No	Page size (default 20, max 100)

Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 12,
        "name": "工作文档",
        "is_folder": 1,
        "folder_id": null,
        "size": 0,
        "created_at": "2025-01-10T08:30:00.000000Z"
      },
      {
        "id": 15,
        "name": "report_2025.pdf",
        "is_folder": 0,
        "folder_id": null,
        "size": 1024,
        "created_at": "2025-01-10T09:15:00.000000Z"
      }
    ],
    "total": 2,
    "current_page": 1,
    "last_page": 1,
    "per_page": 20
  }
}

POST /api/folders

Create a new folder in the specified directory.

Request Body (JSON)

{
  "name": "项目资料备份",
  "folder_id": null
}

POST /api/files/upload

Upload and sync a file to the specified directory (submitted as multipart/form-data; the server automatically deduplicates via MD5 hash verification).

cURL upload example

curl -X POST "https://2zip.app/api/files/upload" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/local/backup.zip" \
  -F "folder_id=12"

Success response (200 OK)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 88,
    "user_id": 1,
    "document_id": 25,
    "name": "backup.zip",
    "size": 5120,
    "folder_id": 12,
    "is_folder": false,
    "created_at": "2025-01-10T10:00:00.000000Z"
  }
}

GET /api/files/{id}/download

Download the specified file (returns the binary file stream directly).

curl -X GET "https://2zip.app/api/files/88/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --output downloaded_backup.zip

POST /api/files/{id}/move

Move a file or folder to a target folder.

POST https://2zip.app/api/files/88/move
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "folder_id": 15
}

DELETE /api/files/{id}

Delete a file or folder (automatically moved to the recycle bin and the used quota is released).

curl -X DELETE "https://2zip.app/api/files/88" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sync Drive APIs (bound folder, flat files)

The following endpoints target desktop / CLI sync clients. A sync drive is a bound folder (folder_id) with files laid out flat — the filename IS the path. MD5 is used for content verification and instant-dedup.

Note: every item returned by GET /api/files includes a hash field (content MD5). Recommended sync flow: walk local directory → stat by folder_id + name → skip if hash matches, otherwise overwrite-upload; optionally pre-check batches via /api/sync/exists before uploading.

GET /api/sync/stat?folder_id=12&name=1.txt

Check whether a file exists in the sync folder by name (flat layout, filename is the path) and return version info (hash / size / updated_at) so clients can compare local md5. folder_id defaults to the drive root.

curl -X GET "https://2zip.app/api/sync/stat?folder_id=12&name=1.txt" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response example

{
  "code": 0,
  "data": {
    "exists": true,
    "id": 150,
    "name": "1.txt",
    "size": 50,
    "hash": "d41d8cd98f00b204e9800998ecf8427e",
    "updated_at": "2026-08-29T03:37:50.000000Z"
  }
}

PUT /api/sync/upload?folder_id=12&name=1.txt

Upsert upload: folder_id targets the sync folder (defaults to root), name defaults to the original filename. When the name already exists the file is updated in place (no duplicates); otherwise it is created. Returns 404 if the folder is missing.

curl -X PUT "https://2zip.app/api/sync/upload?folder_id=12&name=1.txt" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/local/1.txt"

POST /api/sync/exists

Batch-verify whether content MD5s already exist (physical content lookup for instant-dedup pre-check). Returns { md5: true/false }; upload only the missing ones.

POST https://2zip.app/api/sync/exists
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "md5s": ["d41d8cd98f00b204e9800998ecf8427e", "e99a18c428cb38d5f260853678922e03"]
}

POST /api/files/{id}/rename

Rename a file or folder (duplicate names in the same folder are rejected; names cannot contain path separators).

POST https://2zip.app/api/files/88/rename
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "new_name": "renamed.txt"
}

POST /api/sync/delete

Batch delete (moved to recycle bin, quota released); child entries are deduplicated when both a folder and its children are passed.

POST https://2zip.app/api/sync/delete
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "ids": [88, 89, 90]
}

GET /api/folders/{id}/download

Download an entire folder (including all descendants) as a zip stream — ideal for initial full sync. No points are deducted for sync downloads.

curl -X GET "https://2zip.app/api/folders/12/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --output docs.zip

3. Status Codes & Error Handling

HTTP Status	Description	How to Handle
200 / 201	Request succeeded	Parse the returned data field normally
400	Business logic error (e.g. insufficient storage, cannot move into itself)	Read the returned message and show it to the user
401	Unauthorized or Access Token expired	Refresh with the Refresh Token or re-authorize the user
404	Target file or directory not found	Verify the file ID belongs to the authorized user
422	Validation failed	Check the request parameter format and types