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×tamp=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 |