API documentation




Do I really need to provide my server’s IP address?

Providing your IP addresses is optional, but is highly recommended if your servers have static IP addresses. IP address based filtering is more secure than using password-based authentication, but we support both.

If you are unsure of your IP address, run the following from your server(s):


That command will return your IP address, which will be four numbers separated by periods, such as

How can I add or remove IP addresses?

Registered IP(s) that can connect to your API appear in your dashboard. You can directly edit your registered IP list from that page.

If you are currently setup for password-based authentication, then instead of an IP list there will be a “contact us” link to enable IP-based authentication.

Can I add a range of IP addresses?

Yes, our IP authentication system accepts IP address ranges. When setting up your IP-based security for the first time, or when adding or removing IP addresses in your dashboard, simply enter the range in CIDR notation. For example,

What should I do if I have a dynamic IP?

IP Filtering does not work with dynamic IP addresses. Please use to request a user name and password to log in with. We will also turn off IP-based authentication for you.

I can’t reset my password, what do I do?

Go to forgot_password. If you are still having problems, please contact us and we will investigate the issue as soon as possible.


What methods count toward searches?

Only Search requests count.

Where can I find my current usage of the API?

Go to the summary log in your dashboard.


Why am I getting a 401 (Authorization Required) error?

If you are using password authentication, a 401 error means that the username/password combination for that request is wrong.

If you are using IP filtering, a 401 error means that the server that made the request is not listed as one of your authorized IP addresses. You can get the IP address of your server by running the following command on your server:


That command will return your IP address, which will be four numbers separated by periods, such as

If this does not help, please contact us and we will get in touch as soon as possible.

Why am I getting a 500 error?

This may be because the HTTP request sent was malformed; common problems include missing multipart boundaries or the last boundary not ending with “–”. If checking the validity of your HTTP request doesn’t solve your problem, please send us the details of the request you sent and the response you got using and we will get back to you as soon as possible.


Do I need to use cURL to make API requests?

No, you can use any method which sends HTTP requests to the server, and retrieves the results. All major programming languages and platforms have HTTP libraries, and you should use one for your development environment. We use curl in our examples because it is a handy way to try it out from a terminal, and to make simple scripts.

How do I send files using cURL?

You can find an example on the Requests page. Be careful about the use of images, filepaths and @; their meanings are not obvious.

Can I call my API directly from a browser or mobile device/application? Can I make AJAX calls to my API?

Your API should only be called from your server’s scripts and never from a browser or a mobile application. Otherwise you would expose your API to the public, which would allow anyone to add and delete images from your collection.

How many concurrent operations can be done?

WineEngine can run 4 operations simultaneously except for Add and Delete operations which run atomically.

What programming language can be used to connect with the API?

WineEngine Libraries are available for C#, Java, PHP and Python. You can also use any language which can make HTTP requests and receive the results, which includes all major programming languages.

Can I use the API explorer on my site?

You can, but you must proxy the calls to the API, or use wrappers to make those calls from your own site. This is necessary because of the AJAX same-origin policy, which enhances security.


How do I access my image collection?

You can view your collection images by accessing the following URL:<company name>/collection/?filepath=<filepath>

How do I access my query images?

You can view query images by accessing the following URL:<company name>/query/?filepath=<filepath>

How long are query and overlay images stored for?

Overlay and query images are stored for one day.

Can I clear my API’s image collection?

Please contact us if you wish to clear your image collection.

What image formats do the APIs accept?

WineEngine accepts JPEG, PNG, GIF, BMP and TIFF images. Animated images are not supported. The format is found from the file content; the associated filename extension, if any, is ignored.

What is the suggested size for images?

Images should be 1000 pixels in the smaller dimension for WineEngine. Images larger than optimal will be resized by the API. For example, a 1800x1500 pixels image will be resized to 1200x1000 pixels by WineEngine. To reduce upload time, it is recommended that you pre-scale your images accordingly.

Are folders for images created dynamically?

Yes. They are created when images are uploaded, using the path in the filepath parameter.

I only see 20 images when I list my collection, what’s going on?

Listing your collection only shows 20 images by default. To confirm that Add calls to your collection were successful, it is faster to use the Count request.