List API

The List API supports retrieving file lists from CloudFlare ImgBed.

Basic Information

• Endpoint: /api/manage/list
• Method: GET
• Authentication: Requires list permission
• Content Type: application/json

Request Parameters

Query Parameters

Parameter	Type	Required	Default	Description
start	number	No	0	Starting position for pagination
count	number	No	50	Number of items to return, -1 means no limit
sum	boolean	No	false	Whether to return only total count statistics (effective when count is -1)
recursive	boolean	No	false	Whether to recursively get files in subdirectories
dir	string	No	""	Specify directory path
search	string	No	""	Search keyword, supports filename search
includeTags	string	No	""	Include tags filter, multiple tags separated by comma, files must contain all specified tags
excludeTags	string	No	""	Exclude tags filter, multiple tags separated by comma, files cannot contain any specified tags
channel	string	No	""	Filter by storage channel: telegram, cfr2, s3
listType	string	No	""	Filter by review result type: None, Block, White
action	string	No	""	Special operations: rebuild, info

Feature Description

Regular File List Query

Retrieve lists of files and subdirectories in the specified directory, with support for pagination, search, and filtering.

Statistics Query

When count=-1 and sum=true, only returns total file count statistics (for the specified directory and subdirectories).

Recursive Query

When recursive=true, recursively retrieves all files in subdirectories.

Tag Filtering

Supports precise file filtering by tags:

• Include Tags (includeTags): Files must contain all specified tags to be returned
• Exclude Tags (excludeTags): Files cannot contain any of the specified tags
• Tag matching is case-insensitive and supports multilingual tags (Chinese, Japanese, Korean, etc.)
• Include and exclude tags can be used together for complex filtering

Special Operations

Rebuild Index (action=rebuild)

Asynchronously rebuild the file index to improve query performance.

Index Information (action=info)

Get basic information and status of the index.

Response Format

Regular List Response

{
  "files": [
    {
      "name": "example/image.jpg",
      "metadata": {
        "Channel": "telegram",
        "TimeStamp": "1754020094217",
        "File-Mime": "image/jpeg",
        "File-Size": "1024000"
      }
    }
  ],
  "directories": [
    "example/subfolder"
  ],
  "totalCount": 100, // Total file count in the specified directory and subdirectories
  "returnedCount": 50, // Actual number of files returned
  "indexLastUpdated": "1754020094217",
  "isIndexedResponse": true
}

Statistics Response

{
  "sum": 100,
  "indexLastUpdated": "1754020094217"
}

Index Information Response

{
  "totalFiles": 100,
  "lastUpdated": "1754020094217",
  "channelStats": {
    "telegram": 20
  },
  "directoryStats": {
    "/": 30
  },
  "typeStats": {
    "None": 20
  },
  "oldestFile": {},
  "newestFile": {}
}

Error Response

{
  "error": "Internal server error",
  "message": "Detailed error message"
}

Examples

Get File List

curl --location --request GET 'https://your.domain/api/manage/list?start=0&count=50' \
--header 'Authorization: Bearer your_token'

Search Files

curl --location --request GET 'https://your.domain/api/manage/list?search=image&count=20' \
--header 'Authorization: Bearer your_token'

Get Specific Directory

curl --location --request GET 'https://your.domain/api/manage/list?dir=photos/2024' \
--header 'Authorization: Bearer your_token'

Filter by Storage Channel

curl --location --request GET 'https://your.domain/api/manage/list?channel=telegram' \
--header 'Authorization: Bearer your_token'

Get Total Count Statistics

curl --location --request GET 'https://your.domain/api/manage/list?count=-1&sum=true' \
--header 'Authorization: Bearer your_token'

Rebuild Index

curl --location --request GET 'https://your.domain/api/manage/list?action=rebuild' \
--header 'Authorization: Bearer your_token'

Filter by Tags

# Files containing specific tags
curl --location --request GET 'https://your.domain/api/manage/list?includeTags=landscape,travel' \
--header 'Authorization: Bearer your_token'

# Files excluding specific tags
curl --location --request GET 'https://your.domain/api/manage/list?excludeTags=private,draft' \
--header 'Authorization: Bearer your_token'

# Combined usage: include "landscape" tag but exclude "draft" tag
curl --location --request GET 'https://your.domain/api/manage/list?includeTags=landscape&excludeTags=draft' \
--header 'Authorization: Bearer your_token'