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.
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/tumblelog/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.