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.



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 ... >
            <feed ... />
            <feed ... />
        <post type="regular" ... >
        <post type="link" ... >
        <post type="quote" ... >
        <post type="photo" ... >
            <photo-url max-width="500">...</photo-url>
            <photo-url max-width="400">...</photo-url>
        <post type="conversation" ... >
                <line name="..." label="...">...</line>
                <line name="..." label="...">...</line>
        <post type="video" ... >
        <post type="audio" ... >
        <post type="answer" ... >

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.


<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.
        '<a href="' + tumblr_api_read[1][0]['url'] + 
        '">Most recent Tumblr post</a>'