Su.pr API

The Su.pr API allows application support for short URL and posting functionality available from Su.pr. The ability to shorten, expand as well as post to authorized services are available through a simple REST API.

Current Version: 1.0
Default Version: 0.95
[[Su.pr API Release Notes]]

Version Support

The Su.pr API has version support to be able to add in new features without interrupting production code. By adding a version parameter, you can select which version of the API you would like to use. If no version is specified, the default version (above) will be used.

Example

http://su.pr/api/shorten?longUrl=http://www.stumbleupon.com&version=1.0

REST Request Format

The Su.pr API uses the REST format. A simple HTTP GET or POST is all you need to get going.

Su.pr API calls use the following format:

http://su.pr/api/[method]?[params]

Example

http://su.pr/api/shorten?longUrl=http://www.stumbleupon.com

Response Formats

By default, Su.pr returns all responses in the well supported easy to use JSON format. If you must, you may change the response format to XML by setting the format parameter to any API request.

Example

http://su.pr/api/shorten?longUrl=http://www.stumbleupon.com&format=xml

Sample JSON response


{"errorCode":0,"errorMessage":"","results":{"http://www.stumbleupon.com":{"hash":"1nlKX2","shortUrl":"http://su.pr/1nlKX2"}},"statusCode":"OK"}

Sample XML response


<supr>
<errorCode>0</errorCode>
<errorMessage/>
<results>
<nodeKeyVal>
<nodeKey>http://www.stumbleupon.com</nodeKey>
<hash>1SUJk7</hash>
<shortUrl>http://su.pr/1SUJk7</shortUrl>
</nodeKeyVal>
</results>
<statusCode>OK</statusCode>
</supr>

Authentication

Authentication is required for unique account based statistic tracking associated with any shortened URL generated using Su.pr. It is handled through your Su.pr username and a private API Key which can be found and generated on your settings page.

Parameters

Required Name Type Description
optional login string Your Su.pr username (also your StumbleUpon username)
optional apiKey string Your private API key. This can be generated on your Su.pr settings page.

shorten

The shorten API is used to create Su.pr short URLs. Authenticated requests can be used to create account based unique short URLs used for Su.pr analytics. Authenticated items will appear on your Su.pr home page.

Parameters

Required Name Type Description
required longUrl string The long URL you wish to shorten
optional login string Your Su.pr username (also your StumbleUpon username)
apiKey string Your private API key. This can be generated on your Su.pr settings page.

Example

http://su.pr/api/shorten?longUrl=http://www.stumbleupon.com&login=yourusername&apiKey=yourapikey

Sample Response


{"errorCode":0,"errorMessage":"","results":{"http://www.stumbleupon.com":{"hash":"1nlKX2","shortUrl":"http://su.pr/1nlKX2"}},"statusCode":"OK"}

Errors

Code Description
1206 Invalid URL

simpleshorten

The simpleshorten API is a simplified version of the shorten API method which returns the shortened Su.pr URL as plain text. Authenticated requests can be used to create account based unique short URLs used for Su.pr analytics. Authenticated items will appear on your Su.pr home page. Additionally, a shortcut to this method is also available (see below for alternative example).

Parameters

Required Name Type Description
required url string The long URL you wish to shorten
optional login string Your Su.pr username (also your StumbleUpon username)
apiKey string Your private API key. This can be generated on your Su.pr settings page.

Example

http://su.pr/api/simpleshorten?url=http://www.stumbleupon.com

Alternative Example

http://su.pr/api?url=http://www.stumbleupon.com

Sample Response

http://su.pr/1nlKX2

Errors

Plain Text Description
ERROR_1206 Invalid URL

expand

The expand API is used to expand Su.pr URLs via the URL itself or the corresponding hash.

Parameters

Required Name Type Description
required* shortUrl string The Su.pr URL you wish to expand
hash string The six character hash you wish to expand
apiKey string Your private API key. This can be generated on your Su.pr settings page.

Example

http://su.pr/api/expand?shortUrl=http://su.pr/1SUJk7

Sample Response


{"errorCode":0,"errorMessage":"","results":{"1SUJk7":{"longUrl":"http://www.stumbleupon.com/"}},"statusCode":"OK"}

Errors

Code Description
1204 Invalid Su.pr Hash

post

The post API is used to post Su.pr converted messages to associated services such as Twitter and Facebook. Authentication is required for this API.

Parameters

Required Name Type Description
required msg string Message you wish to convert and post. All links contained in the message will be converted to Su.pr URLs.
login string Your Su.pr username (also your StumbleUpon username)
apiKey string Your private API key. This can be generated on your Su.pr settings page.
optional services array An array of authorized services you wish to submit to. Values: [twitter,facebook]. Default: All user authenticated services.

Example

http://su.pr/api/post?msg=Hello World! http:///www.stumbleupon.com&services;[]=twitter&services;[]=facebook&login=yourusername&apiKey=yourapikey

Sample Response


{"errorCode":0,"errorMessage":"","results":{"shortMsg":"Hello World! http://su.pr/1nlKX2"},"statusCode":"OK"}

Errors

Code Description
203 Su.pr Authentication failed
1301 Twitter Authentication failed
1302 Facebook authentication failed
1304 Your message must be 140 characters or less

schedule

The schedule API is used to schedule Su.pr converted messages to associated services such as Twitter and Facebook at a later date. Authentication is required for this API.

Parameters

Required Name Type Description
required msg string Message you wish to convert and post. All links contained in the message will be converted to Su.pr URLs.
timestamp int Unix timestamp of the date and time you wish to post. Posts will be submitted within a 15 minute bucket of the scheduled time.
login string Your Su.pr username (also your StumbleUpon username)
apiKey string Your private API key. This can be generated on your Su.pr settings page.
optional services array An array of authorized services you wish to submit to. Values: [twitter,facebook]. Default: All user authenticated services.

Example

http://su.pr/api/post?msg=Hello World! http:///www.stumbleupon.com&services;[]=twitter&services;[]=facebook&timestamp=499162800&login=yourusername&apiKey=yourapikey

Sample Response


{"errorCode":0,"errorMessage":"","results":{"shortMsg":"Hello World! http://su.pr/1nlKX2"},"statusCode":"OK"}

Errors

Code Description
203 Su.pr Authentication failed
1301 Twitter Authentication failed
1302 Facebook authentication failed
1303 Invalid timestamp
1304 Your message must be 140 characters or less