List and Search Media

GEThttps://api.perceptpixel.com/v1/media

Listing files is a paginated API. You may additionally specify a search query to filter the results.

Parameters

The query parameters supported by the API are as follows.

name	type	description
limit	number	Limit the number of results per page. (default=10)
offset	number	The number of results to skip from the beginning. (default=0)
query	text	Search query to filter the results. If unspecified, all files are returned. (default=none)
sort	text	Sort the results by a field. The following fields are supported: created_at (default), updated_at, name, file_size.
order	text	The order of the results. The following values are supported: asc, desc (default).
folder_name	text	List media from a specific folder (default=none)

Response (200)

The response is a paginated list of media files, with the following format.

{
  "count": 83,
  "next": "https://api.perceptpixel.com/v1/media?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "uid": "a1",
      "name": "cat.jpg",
      "path": "demo-brjexrkh/cat.jpg",

      "cdn_url": "https://img.perceptpixel.com/demo-brjexrkh/cat.jpg",
      "thumbnail_url": "https://img.perceptpixel.com/demo-brjexrkh/w_600,h_600,c_pad/cat.jpg",

      "updated_at": "2024-02-28T08:49:31.747492Z",
      "file_size": 1020789,
      "type": "jpeg",
      "width": 3374,
      "height": 4498,

      "uploaded_by": "demo@perceptpixel.com",
      "client_ip": "123.123.123.123",

      "caption": null,
      "tags": [],

      "saved_images": {},
      "folder": {
                "uid": "xqasdfjMJgMAsdfe",
                "parent_uid": null,
                "name": "folder1"
            }

    },
    {
      "uid": "a2..",
      "name": "dog.jpg",
      "path": "demo-brjexrkh/dog.jpg",
      // ...
    }
  ]
}

Types

The response type is mocked in Typescript below. The Media type is as described in the Upload API.

type MediaListResponse = {
    count: number;
    next: string | null;
    previous: string | null;
    results: Media[];
};

Example (curl)

# Replace {API_KEY} with your actual API key, without enclosing it in curly braces
curl "https://api.perceptpixel.com/media?sort=updated_at" \
  -H "Authorization: Api-Key {API_KEY}"