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.
- /api/read: Reading posts as XML or JSON
- /api/authenticate: Validating credentials and getting account information
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
id- A specific post ID to return. Use instead of
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=1to sort in chronological order (oldest first).
search- Search for posts with this query.
/api/read/json instead of
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_readvariable being set.
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.
Pages reading: /api/pages
To read your tumblelog's Pages, fetch
and you'll get a structured XML copy of all pages for which the
"Show a link to this page" option in the Customize screen is enabled.
Page reads may return cached content. Requests are rate-limited to one every 10 seconds.