API

The Tumblr API is implemented over standard HTTP requests. This allows Tumblr to be integrated with just about any application that can connect to the web.

/api/read

Reading Tumblr data is easy: just fetch the page at http://(you).tumblr.com/api/read and you'll get a structured XML version of your content in this format:

<tumblr version="1.0">
    <tumblelog ... >
        ...
        <feeds>
            <feed ... />
            <feed ... />
            ...
        </feeds>
    </tumblelog>
    <posts>
        <post type="regular" ... >
            <regular-title>...</regular-title>
            <regular-body>...</regular-body>
        </post>
        <post type="link" ... >
            <link-text>...</link-text>
            <link-url>...</link-url>
        </post>
        <post type="quote" ... >
            <quote-text>...</quote-text>
            <quote-source>...</quote-source>
        </post>
        <post type="photo" ... >
            <photo-caption>...</photo-caption>
            <photo-url max-width="500">...</photo-url>
            <photo-url max-width="400">...</photo-url>
            ...
        </post>
        <post type="conversation" ... >
            <conversation-title>...</conversation-title>
            <conversation-text>...</conversation-text>
            <conversation-line>...</conversation-line>
            <conversation-line>...</conversation-line>
            ...
        </post>
        <post type="video" ... >
            <video-caption>...</video-caption>
            <video-source>...</video-source>
            <video-player>...</video-player>
        </post>
        <post type="audio" ... >
            <audio-caption>...</audio-caption>
            <audio-player>...</audio-player>
        </post>
        ...
    </posts>
</tumblr>

The most recent 20 posts are included by default. You may pass these optional GET parameters:

  • start - The post offset to start from. The default is 0.
  • num - The number of posts to return. The default is 20, and the maximum is 50.
  • type - The type of posts to return. If unspecified or empty, all types of posts are returned. Must be one of regular, quote, photo, link, conversation, video, or audio.
  • id - A specific post ID to return. Use instead of start, num, or type.
  • filter - Alternate filter to run on the text content. Allowed values:
    • text - Plain text only. No HTML.
    • none - No post-processing. Output exactly what the author entered. (Note: Some authors write in Markdown, which will not be converted to HTML when this option is used.)

For detailed example feeds, see the live Read API on Marco's Log or the demo tumblelog. A browser that pretty-prints XML, such as Firefox, is recommended.

JSON output

By using /api/read/json instead of /api/read when calling the Read API, the output will be sent as JSON assigned to a Javascript variable named tumblr_api_read. All regular Read API parameters are accepted, plus:

  • callback - A function name to call with the JSON object as its only parameter. When set, the function will be called instead of the tumblr_api_read variable being set.

Example:

<script type="text/javascript" src="http://(you).tumblr.com/api/read/json"></script>

<script type="text/javascript">
    // The variable "tumblr_api_read" is now set.
    document.write(
        '<a href="' + tumblr_api_read[1][0]['@url'] + 
        '">Most recent Tumblr post</a>'
    );
</script>

To view a human-readable map of the array's structure for easy reference, pass debug=1 as a GET parameter. The output will be like that of PHP's print_r() function.

/api/write

The Write API is a very simple HTTP interface. To create a post, send a POST request to http://www.tumblr.com/api/write with the following parameters:

  • email - Your account's email address.
  • password - Your account's password.
  • type - The post type.
  • (content parameters) - These vary by post type.
  • generator (optional) - A short description of the application making the request for tracking and statistics, such as "John's Widget 1.0". Must be 64 or fewer characters.
  • date (optional) - The post date, if different from now, in the tumblelog's timezone. Most unambiguous formats are accepted, such as '2007-12-01 14:50:02'. Dates may not be in the future.
  • private (optional) - 1 or 0. Whether the post is private. Private posts only appear in the Dashboard or with authenticated links, and do not appear on the tumblelog's main page.
  • tags (optional) - Comma-separated list of post tags. You may optionally enclose tags in double-quotes.
  • format (optional) - html or markdown.
  • group (optional) - Post this to a group instead of your tumblelog. Value types:
    1. Domain, e.g. mygroup.tumblr.com (for public groups only)
    2. Group ID number, e.g. 1495028. Found with the Dashboard URL for that group, e.g. www.tumblr.com/group/1495028.

Post types

These are the valid values for the type parameter, with the associated content parameters that each type supports:

  • regular - Requires at least one:
    • title
    • body (HTML allowed)
  • photo - Requires either source or data, but not both. If both are specified, source is used.
    • source - The URL of the photo to copy. This must be a web-accessible URL, not a local file or intranet location.
    • data - An image file. See File uploads below.
    • caption (optional, HTML allowed)
    • click-through-url (optional)
  • quote
    • quote
    • source (optional, HTML allowed)
  • link
    • name (optional)
    • url
    • description (optional, HTML allowed)
  • conversation
    • title (optional)
    • conversation
  • video - Requires either embed or data, but not both.
    • embed - Either the complete HTML code to embed the video, or the URL of a YouTube video page.
    • data - A video file for a Vimeo upload. See File uploads below.
    • title (optional) - Only applies to Vimeo uploads.
    • caption (optional, HTML allowed)
  • audio
    • data - An audio file. See File uploads below.
    • caption (optional, HTML allowed)

File uploads

File uploads can be done in a data parameter where specified above. You may use either of the common encoding methods:

  • multipart/form-data method, like a file upload box in a web form. Maximum size:
    • 50 MB for videos
    • 10 MB for photos
    • 10 MB for audio
    This is recommended since there's much less overhead.
  • Normal POST method, in which the file's entire binary contents are URL-encoded like any other POST variable. Maximum size:
    • 5 MB for videos
    • 5 MB for photos
    • 5 MB for audio

Return values

We return standard HTTP status codes for each request, plus a plaintext response.

  • 201 Created - Success! The newly created post's ID is returned.
  • 403 Forbidden - Your email address or password were incorrect.
  • 400 Bad Request - There was at least one error while trying to save your post. Errors are sent in plain text, one per line.

Sample PHP code

<?php

// Authorization info
$tumblr_email    = 'info@davidville.com';
$tumblr_password = 'secret';

// Data for new record
$post_type  = 'regular';
$post_title = 'The post title';
$post_body  = 'This is the body of the post.';

// Prepare POST request
$request_data = http_build_query(
    array(
        'email'     => $tumblr_email,
        'password'  => $tumblr_password,
        'type'      => $post_type,
        'title'     => $post_title,
        'body'      => $post_body,
        'generator' => 'API example'
    )
);

// Send the POST request (with cURL)
$c = curl_init('http://www.tumblr.com/api/write');
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, $request_data);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($c);
$status = curl_getinfo($c, CURLINFO_HTTP_CODE);
curl_close($c);

// Check for success
if ($status == 201) {
    echo "Success! The new post ID is $result.\n";
} else if ($status == 403) {
    echo 'Bad email or password';
} else {
    echo "Error: $result\n";
}

?>

If you have any questions, please pass them along to Tumblr Support.

Other actions

We provide additional actions that may be beneficial. Pass these values as a POST parameter called action. You may omit type and other post-specific parameters since a post is not created for these actions.

  • authenticate - Only checks authentication without creating a post. Returns 403 if invalid, 200 if valid.
  • check-vimeo - Checks to see if the user is logged into Vimeo through Tumblr. This is required to upload videos. Returns a 400 status with a message and a login URL in the response if the user is not logged into Vimeo. If the user is logged in, this returns a 200 status with the maximum number of bytes available for the user to upload as the response.
  • check-audio - Checks to see if the user can upload an audio file. Returns a 400 status if the user has exceeded the daily audio quota, or a 200 status with "OK" as the response.

  • list-tumblelogs - Lists the tumblelogs, both public and private, that the user is a member of.

    The output is XML with a root <tumblr> element with one child <tumblelog> element per tumblelog membership, including the user's default tumblelog.

    Attributes on <tumblelog>:

    • title
    • type: public or private
    • private-id (private tumblelogs only): The ID number for private tumblelogs. Use this value for the group parameter on /api/write.
    • name (public tumblelogs only)
    • url (public tumblelogs only)
    • avatar-url (public tumblelogs only)
    • is-primary: yes if this is the user's primary tumblelog

iPhone

For iPhone apps that want to display a user's Dashboard, Tumblr offers an iPhone-optimized view at http://www.tumblr.com/iphone.

To avoid making the user log into Tumblr separately if you already have their credentials, you can send an HTTP POST to http://www.tumblr.com/login with these form-encoded parameters:

  • email
  • password
  • redirect_to: the relative destination URL to open after a successful login

Example Cocoa code:

NSString *email           = @"example@email.com";
NSString *password        = @"password";
NSString *destination_url = @"/iphone";

NSMutableURLRequest *request = [[NSMutableURLRequest alloc]
    initWithURL:[NSURL URLWithString:@"http://www.tumblr.com/login"]
];
[request setHTTPMethod:@"POST"];
NSString *request_body = [NSString 
    stringWithFormat:@"email=%@&password=%@&redirect_to=%@",
    [email           stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding],
    [password        stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding],
    [destination_url stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding]
];
[request setHTTPBody:[request_body dataUsingEncoding:NSUTF8StringEncoding]];
/* Load the request here with an NDA-covered iPhone component
   that can view the web.
*/
[request release];