Overview
If you’d like to do more with Posterous, we have an extensive API for you to use. While it’s still a work in progress, it allows you to read and write raw data, giving you loads of flexibility.
API Token
The API token is your identifier as a developer and is required for any non-public endpoint.
This token is required in every request that you make and can be found in the API Console next to each request description.
Authentication
Authentication is handled via HTTP Basic Auth and is required for any non-public endpoint. Basic Auth is what determines what user you are acting on behalf of.
Rate Limits and Throttling
The API provides HTTP headers that you can use to determine your remaining rate limit and the retry time when you have been throttled.
# Your daily limit X-RateLimit-Limit : 10000 # Your remaining requests X-RateLimit-Remaining : 9999 # When to schedule a retry when your client has been throttled (in seconds). X-Retry-After : 1
If you find that you need higher rate limits please contact help@posterous.com.
Public Methods
Methods that end in /public only return public data, and don't require an API Token or Basic Auth.
REST
Our API is RESTful. When performing any requests, you must specify the correct HTTP verb for the URL you are querying:
curl -X PUT --user you@example.com:password -d "api_token=<your token>" -d "post[title]=New Title" http://posterous.com/api/2/sites/12345/posts/6789
If your user agent is not capable of specifying the correct verb, you can instead make a POST request and set the _method parameter to the correct verb:
curl -X POST --user you@example.com:password -d "api_token=<your token>" -d "post[title]=New Title" -d "_method=put" http://posterous.com/api/2/sites/12345/posts/6789
All responses are returned as JSON.
Error Messages
Errors are sent with a corresponding HTTP Status code along with a JSON fragment containing the error and it’s messages.
Sample Error Messages
404 Not Found:
{
"message": "Could not find Post with ID=12345",
"error": "Resource not found"
}
422 Unprocessable Entity:
{
"message": [
"Title can't be blank",
...
]
"error": "Validation Failed"
}
JSONP
If you wish to receive the result from any endpoint as JSONP all you need is to specify the callback param with the method you would like to call.
GET http://posterous.com/api/2/users/33789/sites/twoism/posts/public?page=2&callback=someMethod