TwitrPix API Documentation

TwitrPix provides a set of API tools to allow developers to integrate TwitrPix into their applications. These APIs may change and new functionality added in the future.

If you have special needs or would like to be notified when our API's are updated, please drop us a note at hi@twitrpix.com.

Requests

All requests must post data as multipart/form-data unless sending media as base64 encoded.

Responses

- UTF-8 encoded
- Success returns HTTP 200 OK
- Error return HTTP 400 BAD REQUEST

Info TwitrPix API version 1.0 (June 13, 2010)

METHOD: upload

Description
This API endpoint supports oAuth pass-thru to Twitter and accepts media uploads from consumer applications. As this is an "upload" only endpoint, you are responsible for sending the actual status update to Twitter on the user's behalf.

Requires a valid API Key from TwitrPix. Please email hi@twitrpix.com to receive one.
API Endpoint / URL
http://api.twitrpix.com/1/upload.format
Available Response Formats
xml, json
HTTP Method
POST
Parameters
Post data (must be formatted as multipart/form-data):
  • api_key (required) - Your TwitrPix API Key
  • consumer_token (required) - Your Twitter consumer Key
  • consumer_secret (required) - Your Twitter consumer secret
  • oauth_token (required) - The oAuth token for the user
  • oauth_secret (required) - The oAuth secret for the user
  • media (required) - Binary image data
  • message (optional) - Status update / photo caption
  • tags (optional) - User-supplied tags (comma-delimited)
  • latitude (optional) - Latitude; used to geocode photos
  • longitude (optional) - Longitude; used to geocode photos
Responses
All successful responses returns a HTTP 200 OK header.
All error responses return an HTTP 400 BAD REQUEST header.

Sample XML - Success Response:
<response>
    <media>
        <id>5kr</id>
        <url>http://twitrpix.com/5kr</url>
        <text>http://twitrpix.com/5kr [pic] My photo upload</text>
        <thumb>http://img.twitrpix.com/thumb/5kr</thumb>
        <full>http://img.twitrpix.com/5kr</full>
    </media>
    <user>
        <id>5</id>
        <screen_name>twitrpixsupport</screen_name>
        <profile_url>http://twitrpix.com/user/twitrpixsupport</profile_url>
    </user>
</response>

Sample JSON - Success Response:
{
    "response":{
        "media":{
            "id":"5kr",
            "url":"http://twitrpix.com/5kr",
            "text":"http://twitrpix.com/5kr [pic] My photo upload",
            "thumb":"http://img.twitrpix.com/thumb/5kr",
            "full":"http://img.twitrpix.com/5kr"
        },
        "user":{
            "id":"5",
            "screen_name":"twitrpixsupport",
            "profile_url":"http://twitrpix.com/user/twitrpixsupport"
        }
    }
}

Sample XML - Error Response:
<?xml version="1.0" encoding="utf-8" ?>
<response status="fail">
	<error code="1001" msg="Unable to authenticate" />
</response>

Sample JSON - Error Response:
{
    "response":{
        "status":"fail",
        "error":{
            "code":1001,
            "msg":"Unable to authenticate"
        }
    }
}

Error codes:
				999  - Invalid or missing API key
				1000 - Unknown error
				1001 - Unable to authenticate
				1002 - Media not attached
				1003 - Media not supported
				1004 - Media exceeds maximum size

METHOD: uploadAndPost

Description
This API endpoint supports oAuth pass-thru to Twitter and accepts media uploads from consumer applications as well as sending the status update on the user's behalf.

Requires a valid API Key from TwitrPix. Please email hi@twitrpix.com to receive one.
API Endpoint / URL
http://api.twitrpix.com/1/uploadAndPost.format
Available Response Formats
xml, json
HTTP Method
POST
Parameters
Post data (must be formatted as multipart/form-data):
  • api_key (required) - Your TwitrPix API Key
  • consumer_token (required) - Your Twitter consumer Key
  • consumer_secret (required) - Your Twitter consumer secret
  • oauth_token (required) - The oAuth token for the user
  • oauth_secret (required) - The oAuth secret for the user
  • media (required) - Binary image data
  • message (optional) - Status update / photo caption
  • tags (optional) - User-supplied tags (comma-delimited)
  • latitude (optional) - Latitude; used to geocode photos
  • longitude (optional) - Longitude; used to geocode photos
Responses
All successful responses returns a HTTP 200 OK header.
All error responses return an HTTP 400 BAD REQUEST header.

Sample XML - Success Response:
<response>
    <media>
        <id>5kr</id>
        <url>http://twitrpix.com/5kr</url>
        <text>http://twitrpix.com/5kr [pic] My photo upload</text>
        <thumb>http://img.twitrpix.com/thumb/5kr</thumb>
        <full>http://img.twitrpix.com/5kr</full>
    </media>
    <user>
        <id>5</id>
        <screen_name>twitrpixsupport</screen_name>
        <profile_url>http://twitrpix.com/user/twitrpixsupport</profile_url>
    </user>
</response>

Sample JSON - Success Response:
{
    "response":{
        "media":{
            "id":"5kr",
            "url":"http://twitrpix.com/5kr",
            "text":"http://twitrpix.com/5kr [pic] My photo upload",
            "thumb":"http://img.twitrpix.com/thumb/5kr",
            "full":"http://img.twitrpix.com/5kr"
        },
        "user":{
            "id":"5",
            "screen_name":"twitrpixsupport",
            "profile_url":"http://twitrpix.com/user/twitrpixsupport"
        }
    }
}

Sample XML - Error Response:
<?xml version="1.0" encoding="utf-8" ?>
<response status="fail">
	<error code="1001" msg="Unable to authenticate" />
</response>

Sample JSON - Error Response:
{
    "response":{
        "status":"fail",
        "error":{
            "code":1001,
            "msg":"Unable to authenticate"
        }
    }
}

Error codes:
				999  - Invalid or missing API key
				1000 - Unknown error
				1001 - Unable to authenticate
				1002 - Media not attached
				1003 - Media not supported
				1004 - Media exceeds maximum size

METHOD: Fullsize & Thumbnail Images

Description
While part of our API spec, it is essentially *not* an API call in itself. Instead, you to use this method to show TwitrPix media within your app. By parsing a TwitrPix URL within a status update, you can extract the media id and show various sizes of the media directly.
API Endpoint / URL
http://img.twitrpix.com/<size>/<media id>

Sizes:
thumb - thumbnail
full - fullsize image

ie. http://twitrpix.com/6o - the media id

Obtain the thumbnail by using: http://img.twitrpix.com/thumb/6o
The full size image can be retrieved by: http://img.twitrpix.com/full/6o

Note: Thumbnails and fullsize images should link back to the photo detail page on TwitrPix or a link to the photo detail page provided to your end user.

METHOD: ping

Description
Used to ping our API versioning system for uptime / availability.
API Endpoint / URL
http://api.twitrpix.com/1/ping
Available Response Formats
xml (default)
Parameters
None
Responses
Sample Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
	<message>pong</message>
</response>

Sample Maintenance Response:
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
	<message>maintenance</message>
</response>