Files
FileCodeBox/docs/en/api/index.md
Marrrrrrrrry 6e7580b8dc docs: refresh API reference - real version, snake_case fields, EN presign page
API version 2.1.0 -> 2.5.6; response examples use the single message
field; dashboard/list examples and params match current snake_case
contract; drop stale save_path from presign init response; add English
presign-upload page and sidebar entry; uploadSize -> upload_size.
2026-09-11 03:37:24 +08:00

6.2 KiB

FileCodeBox API Documentation

API Version: 2.5.6

Table of Contents

Authentication

Some APIs require Authorization header for authentication:

Authorization: Bearer <token>

Get Token

When guest upload is disabled in admin panel (openUpload=0), you need to login first:

curl -X POST "http://localhost:12345/admin/login" \
  -H "Content-Type: application/json" \
  -d '{"password": "<admin-password-set-during-setup>"}'

Response Example:

{
  "code": 200,
  "message": "success",
  "detail": {
    "token": "xxx.xxx.xxx",
    "token_type": "Bearer"
  }
}

Share API

Share Text

POST /share/text/

Share text content and get a share code.

Parameters:

Parameter Type Required Default Description
text string Yes - Text content to share
expire_value integer No 1 Expiration time value
expire_style string No "day" Expiration time unit(day/hour/minute/count/forever)

cURL Example:

# Guest upload (when openUpload=1)
curl -X POST "http://localhost:12345/share/text/" \
  -F "text=This is the text content to share" \
  -F "expire_value=1" \
  -F "expire_style=day"

# When authentication required (openUpload=0)
curl -X POST "http://localhost:12345/share/text/" \
  -H "Authorization: Bearer xxx.xxx.xxx" \
  -F "text=This is the text content to share"

Response Example:

{
  "code": 200,
  "message": "success",
  "detail": {
    "code": "abc123"
  }
}

Share File

POST /share/file/

Upload and share a file, get a share code.

Parameters:

Parameter Type Required Default Description
file file Yes - File to upload
expire_value integer No 1 Expiration time value
expire_style string No "day" Expiration time unit(day/hour/minute/count/forever)

cURL Example:

# Upload file (default 1 day expiration)
curl -X POST "http://localhost:12345/share/file/" \
  -F "file=@/path/to/file.txt"

# Upload file (7 days expiration)
curl -X POST "http://localhost:12345/share/file/" \
  -F "file=@/path/to/file.txt" \
  -F "expire_value=7" \
  -F "expire_style=day"

# Upload file (10 downloads limit)
curl -X POST "http://localhost:12345/share/file/" \
  -F "file=@/path/to/file.txt" \
  -F "expire_value=10" \
  -F "expire_style=count"

# When authentication required
curl -X POST "http://localhost:12345/share/file/" \
  -H "Authorization: Bearer xxx.xxx.xxx" \
  -F "file=@/path/to/file.txt"

Response Example:

{
  "code": 200,
  "message": "success",
  "detail": {
    "code": "abc123",
    "name": "example.txt"
  }
}

Get File Info

GET /share/select/

Get file information by share code (direct file download).

Parameters:

Parameter Type Required Description
code string Yes File share code

cURL Example:

# Download file by extraction code
curl -L "http://localhost:12345/share/select/?code=abc123" -o downloaded_file

Response Example:

{
  "code": 200,
  "message": "success",
  "detail": {
    "code": "abc123",
    "name": "example.txt",
    "size": 1024,
    "text": "File content or download link"
  }
}

Select File

POST /share/select/

Select file by share code.

Parameters:

Parameter Type Required Description
code string Yes File share code

Response Example:

{
  "code": 200,
  "message": "success",
  "detail": {
    "code": "abc123",
    "name": "example.txt",
    "size": 1024,
    "text": "File content or download link"
  }
}

Download File

GET /share/download

Download shared file.

Parameters:

Parameter Type Required Description
key string Yes Download key
code string Yes File share code

Admin API

Admin Login

POST /admin/login

Admin login to get token.

Parameters:

Parameter Type Required Description
password string Yes Admin password

Dashboard Data

GET /admin/dashboard

Get system dashboard data.

Response Example:

{
  "code": 200,
  "message": "success",
  "detail": {
    "total_files": 100,
    "storage_used": "1610612736",
    "sys_uptime": 1725489600.0,
    "yesterday_count": 50,
    "yesterday_size": "524288000",
    "today_count": 30,
    "today_size": "314572800",
  }
}

File List

GET /admin/file/list

Get system file list.

Parameters:

Parameter Type Required Default Description
page integer No 1 Current page
size integer No 10 Page size
keyword string No "" Search keyword
sort_by string No "created_at" Sort field(created_at/expired_at/name/size/used_count/code)
sort_order string No "desc" Sort direction(asc/desc)

Response Example:

{
  "code": 200,
  "message": "success",
  "detail": {
    "page": 1,
    "size": 10,
    "total": 100,
    "data": [
      {
        "id": 1,
        "name": "example.txt",
        "size": 1024,
        "created_at": "2024-01-01 12:00:00"
      }
    ]
  }
}

Delete File

DELETE /admin/file/delete

Delete file from system.

Parameters:

Parameter Type Required Description
id integer Yes File ID

Get Config

GET /admin/config/get

Get system configuration.

Update Config

PATCH /admin/config/update

Update system configuration.

Error Response

When an error occurs, the API will return corresponding error message:

{
  "code": 422,
  "detail": [
    {
      "loc": ["body", "password"],
      "msg": "Password cannot be empty",
      "type": "value_error"
    }
  ]
}

Status Codes

  • 200: Success
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 422: Validation Error
  • 500: Internal Server Error