Tumblr API v1

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.

Contents

• /api/read: Reading posts as XML or JSON

/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 name="..." label="...">...</line>
                <line name="..." label="...">...</line>
                ...
            </conversation>
        </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>
        <post type="answer" ... >
            <question>...</question>
            <answer>...</answer>
        </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 text, quote, photo, link, chat, 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.)
• tagged - Return posts with this tag in reverse-chronological order (newest first). Optionally specify chrono=1 to sort in chronological order (oldest first).

For detailed example feeds, see the live Read API on derekg.org or the demo blog. 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>