Skip to content
Wbiztool

Media API

List media files API

Get the files in your workspace's media library with their download URLs, newest first. Filter by type or search by name to find a file you uploaded earlier and reuse its URL in a message.

GEThttps://wbiztool.com/api/v1/media/list/

Body: Query string, or a JSON body with POST

The list includes files uploaded with the Upload media API and on the Media directory page. Deleted files are not included.

Quick example#

curl -G https://wbiztool.com/api/v1/media/list/ \
  --data-urlencode client_id=12345 \
  --data-urlencode api_key=YOUR_API_KEY \
  --data-urlencode file_type=image \
  --data-urlencode page=1 \
  --data-urlencode limit=20

Replace 12345 and YOUR_API_KEY with your own values. See Authentication for where to find them.

Request parameters#

Send the parameters in the query string of a GET request, or as a JSON body in a POST request with Content-Type: application/json. Don't mix the two: if client_id is in the query string, the JSON body is ignored. A form-encoded POST also works for client_id, api_key, file_type and search, but page and limit are ignored in form fields; send those in the query string or JSON.

Authentication

client_idintegerrequired

Your API Client ID from Settings → API keys.

api_keystringrequired

Your API key from the same page.

Filters and pagination

pageintegeroptional

Page number, starting at 1 (default). Values below 1 are treated as 1.

limitintegeroptional

Files per page, from 1 to 100. Default 20. Values above 100 are treated as 100, and values below 1 as 20.

file_typestringoptional

image for images only, or file for everything else. Any other value is ignored.

searchstringoptional

Only return files whose original name or stored name contains this text. Not case-sensitive.

POST with a JSON bodycURL
curl -X POST https://wbiztool.com/api/v1/media/list/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "search": "invoice",
    "page": 1,
    "limit": 50
  }'

Response#

{
  "status": 1,
  "message": "Media files retrieved successfully",
  "data": {
    "total_count": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "media_files": [
      {
        "id": 5123,
        "file_name": "media_12345_17895806123456.jpg",
        "original_file_name": "diwali-sale.jpg",
        "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895806123456.jpg",
        "file_type": "image",
        "file_size": 524288,
        "file_size_display": "512.0 KB",
        "mime_type": "image/jpeg",
        "is_image": true,
        "file_extension": "jpg",
        "created_at": "2026-09-16T10:23:52.106447+00:00",
        "uploaded_by": "[email protected]"
      }
    ]
  }
}
FieldTypeDescription
statusinteger1 on success, 0 if the request failed.
messagestringMedia files retrieved successfully, otherwise the error.
data.total_countintegerFiles matching your filters, across all pages.
data.pageintegerThe page returned.
data.limitintegerThe page size used, after the 1 to 100 adjustment.
data.total_pagesintegerNumber of pages. 0 when there are no files.
data.has_nextbooleantrue if there's a page after this one.
data.has_previousbooleantrue if page is greater than 1.
data.media_filesarrayThe files on this page, newest first. Empty if the page is past the end.

Media file fields#

FieldTypeDescription
idintegerID of the media file. Use it with Get media file.
file_namestringName the file is stored under.
original_file_namestringThe name the file had when it was uploaded.
file_urlstringDirect download URL. Use it as img_url or file_url when sending.
file_typestringimage or file.
file_sizeintegerSize in bytes.
file_size_displaystringReadable size with one decimal, for example 512.0 KB.
mime_typestringMIME type, for example image/jpeg.
is_imagebooleantrue when file_type is image.
file_extensionstringLower-case extension of original_file_name, without the dot.
created_atstringUpload time, ISO 8601 in UTC with a +00:00 offset.
uploaded_bystring or nullLogin username (usually the email address) of the team member who uploaded the file.

Errors#

Errors also return HTTP 200, with status set to 0:

{ "status": 0, "message": "Invalid API key" }
MessageHow to fix it
client_id is requiredAdd client_id. If you send JSON, check the body is valid JSON (a parse error is reported as this message).
api_key is requiredAdd api_key.
client_id must be a valid integerSend client_id as a number.
Invalid API keyCheck the key exists and hasn't been deleted or disabled.
Invalid client_id for this API keyThe key belongs to a different client_id.
Error retrieving media files: …Usually page or limit in the query string or form fields isn't a whole number. In a JSON body there's no error: if page isn't a whole number, page, limit, file_type and search are all ignored, so you get page 1 with 20 files and no filters. If only limit isn't, limit, file_type and search are ignored.

Reading every page#

Keep requesting the next page while data.has_next is true.

Fetch all media files
import requests

files, page = [], 1

while True:
    result = requests.get(
        "https://wbiztool.com/api/v1/media/list/",
        params={"client_id": 12345, "api_key": "YOUR_API_KEY", "page": page, "limit": 100},
        timeout=60,
    ).json()
    if result["status"] != 1:
        raise RuntimeError(result["message"])

    files += result["data"]["media_files"]
    if not result["data"]["has_next"]:
        break
    page += 1

print(len(files), "files")

Tips#

  • Use the right send parameter: when is_image is true, send the URL as img_url with msg_type 1; otherwise as file_url with msg_type 2. See Send message.
  • Keep your API key out of logs: query strings are often logged by proxies and servers. If that matters to you, use POST with a JSON body instead.