API Documentation

Overview
Method
Variables
On Success / XML Feedback
Errors
Simple Demo
Sample Code

Overview

Our simple API allows you to create custom applications, addons, and scripts that can upload screenshots to our website.

Simply register for an API key, and then read through the documentation below. If you have any questions after reading the documentation feel free to email gordon@incero.com.

Method

Simply use POST or any combination of GET and POST to pass the variables detailed below to http://img1.uploadscreenshot.com/api-upload.php.

For example you could:

POST all the variables and the image file to http://img1.uploadscreenshot.com/api-upload.php.

or

POST just the image to the URL with the variables added in the URL like so:
http://img1.uploadscreenshot.com/api-upload.php?apiKey=dsfsdf2345543534431435&xmlOutput=1&imageMD5=098f6bcd4621d373cade4e832627b4f6&testMode=1

Once uploaded we will either redirect you to the uploaded image or provide you with information about the upload via xml output based on your settings.

Variables

Name Required? Method Description

userfile Required POST contains the jpg or png image file

apiKey Required POST or GET contains your api key

imageMD5 Optional POST or GET MD5 sum of the image being uploaded. If you submit it and the md5 does not match when uploaded we will report an error. For uploads without an md5 sum we will assume that it uploaded correctly.

username Optional POST or GET If you want to upload to a user account enter their username here. Leave empty to not upload to a user account.

userPasswordMD5 Optional POST or GET MD5 of the user account password. Leave empty to not upload to a user account.

xmlOutput Optional POST or GET If set to 1 we will output xml after the upload is complete. If it is not 1 we will use header to redirect to the uploaded image page after upload.

testMode Optional POST or GET If set to 1 the image will be set to be removed. Please set to 1 during your tests so that our servers do not fill up with test uploads. Images are removed approximately every 15 minutes.

Name	Required?	Method	Description
userfile	Required	POST	contains the jpg or png image file
apiKey	Required	POST or GET	contains your api key
imageMD5	Optional	POST or GET	MD5 sum of the image being uploaded. If you submit it and the md5 does not match when uploaded we will report an error. For uploads without an md5 sum we will assume that it uploaded correctly.
username	Optional	POST or GET	If you want to upload to a user account enter their username here. Leave empty to not upload to a user account.
userPasswordMD5	Optional	POST or GET	MD5 of the user account password. Leave empty to not upload to a user account.
xmlOutput	Optional	POST or GET	If set to 1 we will output xml after the upload is complete. If it is not 1 we will use header to redirect to the uploaded image page after upload.
testMode	Optional	POST or GET	If set to 1 the image will be set to be removed. Please set to 1 during your tests so that our servers do not fill up with test uploads. Images are removed approximately every 15 minutes.

On Success / XML Feedback

If there are no errors and xmlOutput is not set to 1 the user will be redirected to the url of the uploaded image, for example: http://www.uploadscreenshot.com/image/53906/8093736.

If xmlOutput is set to 1 then XML feedback will be provided within the upload xml parent. Below are details of the various feedback data, and you can test your script with this sample xml feedback of a successful upload: http://uploadscreenshot.com/api/success-demo.xml

Variable Details Example

success If the upload was successful this will be set to 1. 1

id The unique identifier for the image upload. 53900

url URL of the web page that displays the screenshot and provides the user with embed codes. http://www.uploadscreenshot.com/image/53900/6560666

shorturl A short URL for the screenshot page. http://ScrnSht.com/lcowyq

statsurl URL of the stats page for the uploaded image. http://www.uploadscreenshot.com/stats/53900/6560666

deleteurl Accessing this URL will delete the image. It may take 15 minutes for the image to be removed from the server. http://www.uploadscreenshot.com/api/delete/53900/2147483423

small URL of the small thumbnail of the image. http://img1.uploadscreenshot.com/images/thumb/3/8720375751.png

large URL for the large version of the image. http://img1.uploadscreenshot.com/images/main/3/8720375751.png

original URL for the original resolution copy of the image. http://img1.uploadscreenshot.com/images/orig/3/8720375751-orig.png

Variable	Details	Example
success	If the upload was successful this will be set to 1.	1
id	The unique identifier for the image upload.	53900
url	URL of the web page that displays the screenshot and provides the user with embed codes.	http://www.uploadscreenshot.com/image/53900/6560666
shorturl	A short URL for the screenshot page.	http://ScrnSht.com/lcowyq
statsurl	URL of the stats page for the uploaded image.	http://www.uploadscreenshot.com/stats/53900/6560666
deleteurl	Accessing this URL will delete the image. It may take 15 minutes for the image to be removed from the server.	http://www.uploadscreenshot.com/api/delete/53900/2147483423
small	URL of the small thumbnail of the image.	http://img1.uploadscreenshot.com/images/thumb/3/8720375751.png
large	URL for the large version of the image.	http://img1.uploadscreenshot.com/images/main/3/8720375751.png
original	URL for the original resolution copy of the image.	http://img1.uploadscreenshot.com/images/orig/3/8720375751-orig.png

Errors

If there are any errors during the process they will be returned to you in xml form, regardless of whether xmlOutput is set. errorCode will be set to one of the values below and will be within the upload xml parent.

Example error output xml can be viewed here: http://uploadscreenshot.com/api/error-demo.xml. You can also just use a bogus API key in your code to generate an error so that you can test your code's handling of errors.

errorCode Reason For Error

1 The MD5 sum that you provided did not match the MD5 sum that we calculated for the uploaded image file. There may of been a network interruption during upload. Suggest that you try the upload again.

2 The apiKey that you provided does not exist or has been banned. Please contact us for more information.

3 The file that you provided was not a png or jpg.

4 The file that you provided was too large, currently the limit per file is 50MB.

5 The username or userPasswordMD5 provided was not correct. Make sure you are sending the MD5 of the user password.

6 No file was uploaded, userfile was empty.

99 An unkown error occured, please contact the admin and include a copy of the file that you were trying to upload.

errorCode	Reason For Error
1	The MD5 sum that you provided did not match the MD5 sum that we calculated for the uploaded image file. There may of been a network interruption during upload. Suggest that you try the upload again.
2	The apiKey that you provided does not exist or has been banned. Please contact us for more information.
3	The file that you provided was not a png or jpg.
4	The file that you provided was too large, currently the limit per file is 50MB.
5	The username or userPasswordMD5 provided was not correct. Make sure you are sending the MD5 of the user password.
6	No file was uploaded, userfile was empty.
99	An unkown error occured, please contact the admin and include a copy of the file that you were trying to upload.

Simple Demo

You can test the various settings of the API by using this demo: http://uploadscreenshot.com/api/test-api.html.

The demo is a very simple html form that POSTs the required data to our API URL.

Sample Code

If you have clearly documented sample code that you are willing to share here, please email it to me at gordon@incero.com. We could really use some Java, Javascript, C++, Visual Basic and other exmples to help people build desktop applications, browser add-ons etc.

Using HTML to POST data to the API: http://uploadscreenshot.com/api/test-api.html

Using PHP and CURL to POST data to the API: http://uploadscreenshot.com/api/curl-api-test.php.txt