List Image Files
Uri: https://api.finerworks.com/v3/list_images
Method: POST

Provides a list of image files you have uploaded and any virtual inventory items assigned to them.

Body

NameDescriptionTypeAdditional information
library

Contains parameters which help to determine the location of the image.

 image_library

Required
search_filter

Optional - Search query filter that searches based on text in the title or description.

 text

None.
guid_filter

Optional - If you have a list of image guids you can filter by a list of image unique identifiers.

 array (globally unique identifier)

None.
page_number

Optional - Page number.

 number

None.
per_page

Optional - Default is 10 however you can display up to 50 at a time.

 number

None.
sort_field

Optional - Default is by id. Alternatively these fields can also be used: title, file_name, file_size, or date_added.

 text

None.
sort_direction

Optional - Default is "DESC" for descending order however if you want it to be ascending order, use "ASC".

 text

None.
upload_date_from

Optional - Default is null however you can filter by earliest date uploaded.

 date

None.
upload_date_to

Optional - Default is null however you can filter by latest date uploaded.

 date

None.
list_products

Optional - Default is false. If set to true, AND viewing inventory files, you can also get a list of virtual inventory products associated with its parent image.

 boolean

None.
active

Optional - Default is null. If used, it will filter image files you have listed as active (true) or inactive (false)

 boolean

None.

Example JSON Body

application/json, text/json

{
  "library": {
    "name": "inventory",
    "session_id": "1234567890",
    "account_key": "",
    "site_id": 0
  },
  "search_filter": "",
  "guid_filter": null,
  "page_number": 1,
  "per_page": 10,
  "sort_field": "id",
  "sort_direction": "DESC",
  "upload_date_from": null,
  "upload_date_to": null,
  "list_products": true,
  "active": null
}

Sample Code Library


                        
curl --location --request sample_method 'https://api.finerworks.comsample_endpoint' \
--header 'Content-Type: application/json' \
--header 'web_api_key: my-web-api-key-goes-here' \
--header 'app_key: my-app-key-goes-here' \
--data-raw '{
  "library": {
    "name": "inventory",
    "session_id": "1234567890",
    "account_key": "",
    "site_id": 0
  },
  "search_filter": "",
  "guid_filter": null,
  "page_number": 1,
  "per_page": 10,
  "sort_field": "id",
  "sort_direction": "DESC",
  "upload_date_from": null,
  "upload_date_to": null,
  "list_products": true,
  "active": null
}'
                            
                        


require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.finerworks.comsample_endpoint');
$request->setMethod(HTTP_Request2::METHOD_sample_method);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'web_api_key' => 'my-web-api-key-goes-here',
'app_key' => 'my-app-key-goes-here'
));
$request->setBody('{
  'library': {
    'name': 'inventory',
    'session_id': '1234567890',
    'account_key': '',
    'site_id': 0
  },
  'search_filter': '',
  'guid_filter': null,
  'page_number': 1,
  'per_page': 10,
  'sort_field': 'id',
  'sort_direction': 'DESC',
  'upload_date_from': null,
  'upload_date_to': null,
  'list_products': true,
  'active': null
}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}

                        


var client = new RestClient("https://api.finerworks.comsample_endpoint");
client.Timeout = -1;
var request = new RestRequest(Method.sample_method);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("web_api_key", "my-web-api-key-goes-here");
request.AddHeader("app_key", "my-app-key-goes-here");
request.AddParameter("application/json", "{
  'library': {
    'name': 'inventory',
    'session_id': '1234567890',
    'account_key': '',
    'site_id': 0
  },
  'search_filter': '',
  'guid_filter': null,
  'page_number': 1,
  'per_page': 10,
  'sort_field': 'id',
  'sort_direction': 'DESC',
  'upload_date_from': null,
  'upload_date_to': null,
  'list_products': true,
  'active': null
},  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

                        


var settings = {
"url": "https://api.finerworks.comsample_endpoint",
"method": "sample_method",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"web_api_key": "my-web-api-key-goes-here",
"app_key": "my-app-key-goes-here"
},
"data": JSON.stringify({
  'library': {
    'name': 'inventory',
    'session_id': '1234567890',
    'account_key': '',
    'site_id': 0
  },
  'search_filter': '',
  'guid_filter': null,
  'page_number': 1,
  'per_page': 10,
  'sort_field': 'id',
  'sort_direction': 'DESC',
  'upload_date_from': null,
  'upload_date_to': null,
  'list_products': true,
  'active': null
}),
};

$.ajax(settings).done(function (response) {
console.log(response);
});

                        

                        
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
'method': 'sample_method',
'hostname': 'api.finerworks.com',
'path': 'sample_endpoint',
'headers': {
'Content-Type': 'application/json',
'web_api_key': 'my-web-api-key-goes-here',
'app_key': 'my-app-key-goes-here'
},
'maxRedirects': 20
};

var req = https.request(options, function (res) {
var chunks = [];

res.on("data", function (chunk) {
chunks.push(chunk);
});

res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});

res.on("error", function (error) {
console.error(error);
});
});

var postData = JSON.stringify({
  "library": {
    "name": "inventory",
    "session_id": "1234567890",
    "account_key": "",
    "site_id": 0
  },
  "search_filter": "",
  "guid_filter": null,
  "page_number": 1,
  "per_page": 10,
  "sort_field": "id",
  "sort_direction": "DESC",
  "upload_date_from": null,
  "upload_date_to": null,
  "list_products": true,
  "active": null
});

req.write(postData);

req.end();
                            
                        

                        
    require "uri"
    require "net/http"

    url = URI("https://api.finerworks.comsample_endpoint")

    https = Net::HTTP.new(url.host, url.port)
    https.use_ssl = true

    request = Net::HTTP::sample_method.new(url)
    request["Content-Type"] = "application/json"
    request["web_api_key"] = "my-web-api-key-goes-here"
    request["app_key"] = "my-app-key-goes-here"
    request.body = "{
  'library': {
    'name': 'inventory',
    'session_id': '1234567890',
    'account_key': '',
    'site_id': 0
  },
  'search_filter': '',
  'guid_filter': null,
  'page_number': 1,
  'per_page': 10,
  'sort_field': 'id',
  'sort_direction': 'DESC',
  'upload_date_from': null,
  'upload_date_to': null,
  'list_products': true,
  'active': null
}"

    response = https.request(request)
    puts response.read_body

NameDescriptionTypeAdditional information
status

Response status details

 response_status

None.
images

A list of the files uploaded to your account

 array (image_details)

None.
page_number

Current page number.

 number

None.
per_page

Current count of images returned.

 number

None.
count

Total images count

 number

None.

Example JSON Response

application/json, text/json

{
  "status": {
    "success": true,
    "status_code": 200,
    "message": "",
    "debug": null
  },
  "images": [
    {
      "id": 0,
      "guid": "adb88831-c50a-454a-b8b3-017ef1a646bb",
      "title": "My Image",
      "description": "Some interesting things about this image...",
      "file_name": "myimage.jpg",
      "file_size": 100000,
      "thumbnail_file_name": null,
      "preview_file_name": null,
      "hires_file_name": null,
      "public_thumbnail_uri": "https://finerworks.com/myimages/myimage_thumb.jpg",
      "public_preview_uri": "https://finerworks.com/myimages/myimage_small.jpg",
      "personal_gallery_title": null,
      "members_gallery_category": null,
      "private_hires_uri": "https://finerworks.com/myimages/myimage.jpg",
      "pix_w": 2000,
      "pix_h": 3000,
      "date_added": "2025-10-23T08:46:17.3909266-05:00",
      "date_expires": null,
      "active": true,
      "products": [
        {
          "monetary_format": "USD",
          "quantity": 1,
          "sku": "AP1556P79511",
          "product_code": null,
          "per_item_price": 113.0,
          "total_price": 113.0,
          "asking_price": 200.0,
          "name": null,
          "description_short": null,
          "description_long": null,
          "image_url_1": "https://somewhere.com/image.png",
          "image_url_2": null,
          "image_url_3": null,
          "image_url_4": null,
          "image_url_5": null,
          "image_guid": "adb88831-c50a-454a-b8b3-017ef1a646bb",
          "product_size": null
        }
      ]
    }
  ],
  "page_number": 0,
  "per_page": 0,
  "count": 0
}