Cheezburger API Home

Notice

The API as it exists today will be deprecated following a transition period after the next version is unveiled. No new keys will be issued for the existing API.

For more information please contact us or sign up for news about the all new API and await your invitation!

REST and POX

To make using the API as straightforward for developers as possible, the API is implemented as a REST (Representational State Transfer) service using POX (plain ol' XML).

Getting Started

HTTP Header Values
You will need the following HTTP header values in each request.

• Content-type: text/xml
• DeveloperKey: {your developer key here}
• ClientID: {your client id here}
• AuthenticationToken: {authentication token, if you have one} see the Authentication API Documentation for more details

To get a developer key and client ID, please contact us at api@cheezburger.com with details of your development organization and the client application you are writing. Please include the URL of your company and application (if applicable).

API Features

• The Content Retrieval API allows your program to tap into our database of over four million funny images
• The Authentication API allows your program's users to log in to their Cheezburger Account
• The Content Submission API allows your program's users to submit their own pictures and lols (captioned pictures) to the Cheezburger Network
• The Caption API provides tools for putting captions on images.
• The Image Type documentation explains how to submit content to FailBlog, GraphJam, Engrish Funny, and Comixed.
• The Favorites API allows your program's users to see favorite lols by user, as well as add and remove their own favorite lols.

API Reference

The End Point Reference is a complete list of API end points along with example inputs and outputs.

Error messages

If anything goes wrong, the API will return error messages in this specific format.

<?xml version="1.0" encoding="utf-8"?>
<Fail>
<FailureMessage>Example Api Exception Message</FailureMessage>
<FailureDetail>Details and/or advice on how to correct this error message would go here</FailureDetail>
<FailureEventId>9a03febb-886d-4e0f-818e-0375adb0d880</FailureEventId>
</Fail>

For any unexpected or unhandled errors, the FailureEventId will be recorded in our server logs, so we can understand exactly what was happening when the error occurred. Please refer to the Event ID when contacting us to help us find any issue more quickly.

Hello World Service

The Hello World Service returns diagnostic information about the request and the API server configuration.

You can use the "Hello World" Service to test your client's HTTP GET, POST, and DELETE calls by sending an empty (no form body) request to http://api.cheezburger.com/xml/hai

If you include any of the expected HTTP headers (DeveloperKey, ClientId, AuthenticationToken) in your request, the Hello World Service will validate those values and provide information about them.

<?xml version="1.0" encoding="utf-8"?>
<Hai>
<Greeting>O Hai!</Greeting>
<Description>Hello World Service Example Response</Description>
<ServerTime>2010-08-25T11:11:58.8144387-07:00</ServerTime>
<Version>The Version # of the Cheezburger API</Version>
<Environment>The environment of this instance ('Staging' or 'Production')</Environment>
<Method>The method used to request the service. ('GET' or 'POST' or 'DELETE')</Method>
<DeveloperKeyInfo>Information about DeveloperKey provided in HTTP Header</DeveloperKeyInfo>
<ClientIdInfo>Information about ClientId provided in HTTP Header</ClientIdInfo>
<AuthTokenInfo>Information about the Authentication Token provided in HTTP Header</AuthTokenInfo>
<Headers>
<HttpHeader>
<key>request header key</key>
<value>request header value</value>
</HttpHeader>
</Headers>
</Hai>

I'm getting a 415 error message response.

You need to include the "Content-type:text/xml" HTTP header in your POST requests.

I'm getting a 404 error message response when making a GET request.

Either your URL is malformed, or the underlying item has been deleted. You can check the End Point Reference to make sure that the end point URL you are using is correct.

I'm getting a 403 error message response.

Each developer key has a limit of 1000 requests per hour, or 4 requests per second. If your application is receiving these errors you are exceeding those limits and will receive an email alerting you. If you need higher limits please contact us at api@cheezburger.com.

Help! I'm using a client (e.g. Flash) that doesn't support HTTP verbs other than GET and POST. How can I DELETE things?

You can include X-HTTP-Method-Override: VERB in your HTTP Headers when you make a POST call, and our system will then treat that POST as if it were the other verb.