What You Need
Overview
Authentication
Clients
Blog Methods
Blog Info
Avatar
Followers
Likes
Posts
Text
Photo
Quote
Link
Chat
Audio
Video
Answer
Queue
Drafts
Submissions
Posting
Editing Posts
Reblogging Posts
Deleting Posts
User Methods
Tagged Method

Tumblr API

Welcome to the Tumblr API! There isn't anything we enjoy more than seeing talented designers and engineers using Tumblr to invent whole new forms of creative expression. We've put a tremendous amount of care into making this API functional and flexible enough for any projects you throw at it. Join us in our discussion group to talk about how to use it, what could be better, and all the amazing things you're going to build with it. Follow our Developers Blog for important news and announcements. Please use the API responsibly, and send us your feedback. Enjoy!

If you're looking for documentation for the old API, you can find it here.

What You Need

Get an OAuth key: register an application

You'll need this to get your API key, even if you don't ever need to use a fully signed OAuth request.

For more details, see Authentication below.

Overview

Before you dive in, review these essentials.

URI Structure

All Tumblr API requests start with api.tumblr.com. The next segment of the URI path depends on the type of request:

Blog: get blog data or write to a blog
api.tumblr.com/v2/blog/{base-hostname}/...
User: get user data or perform user actions
api.tumblr.com/v2/user/...

See Methods below for complete details.

Blog Hostname

Each blog has a unique hostname. The hostname can be standard or custom.

Standard hostname: the blog short name + .tumblr.com.
Example: greentype.tumblr.com
Custom hostname: Anything at all, as determined by a DNS CNAME entry.
Example: www.davidslog.com

You'll need the blog hostname anytime you work with a blog. When you see the placeholder {base-hostname} in the API docs, substitute the standard or custom hostname.

Response Format

The API returns JSON-encoded objects (content-type: application/json). Responses vary according to the method used, but every response envelope includes these common parts:

meta	The `meta` object matches the HTTP response message: `status`: the 3-digit HTTP Status-Code (e.g., `200`) `msg`: the HTTP Reason-Phrase (e.g., `OK`)
response	API-specific results

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": { ... }
}

All requests made with HTTP GET are JSONP-enabled. To use JSONP, append jsonp= or callback= and the name of your callback function to the request. JSONP requests will always return an HTTP status code of 200 but will reflect the real status code in the meta field of the JSON response.

About the API Documentation

The docs include some working examples. Please click them to your heart's content, but don't use the embedded API key for your own nefarious purposes. Register your application to get your own API key (your OAuth Consumer Key).

URI Conventions

Notation	Meaning	Example
Curly brackets { }	Required item	`api.tumblr.com/v2/blog/ {base-hostname}/posts` The blog hostname is required.
Square brackets [ ]	Optional item	`api.tumblr.com/v2/blog/ {base-hostname}/posts[/type]` Specifying a post type is optional.

Authentication

The API uses three different levels of authentication, depending on the method.

None: No authentication. Anybody can query the method.
API key: Requires an API key. Use your OAuth Consumer Key as your api_key.
- Example: api_key=PyezS3Q4Smivb24d9SzZGYSuh--IaMfAkE
- Get an OAuth key: register an application
OAuth: Requires a signed request that meets the OAuth 1.0a Protocol.

Each method description includes a note about the authentication level.

OAuth

The API supports the OAuth 1.0a Protocol, accepting parameters via the Authorization header, with the HMAC-SHA1 signature method only. There's probably already an OAuth client library for your platform.

Endpoints

Request-token URL	`http://www.tumblr.com/oauth/request_token`
Authorize URL	`http://www.tumblr.com/oauth/authorize`
Access-token URL	`http://www.tumblr.com/oauth/access_token`

API Clients

Here is a list of official API client which will help you get up and running with your favorite language in no time. If you find that we've missed your favorite language, tell us!

Blog Methods

/info — Retrieve Blog Info

This method returns general information about the blog, such as the title, number of posts, and other high-level data.

Examples

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/info?api_key={key}`	GET	API key

Request Parameters

Parameter	Type	Description	Default	Required?
base-hostname	String	The standard or custom blog hostname See the Overview for more details.	N/A	Yes
api_key	String	Your OAuth Consumer Key See Authentication for more details.	N/A	Yes

Responses

Response Field	Type	Description	Notes
title	String	The display title of the blog	Compare `name`
posts	Number	The total number of posts to this blog
name	String	The short blog name that appears before tumblr.com in a standard blog hostname (and before the domain in a custom blog hostname)	Compare `title`
updated	Number	The time of the most recent post, in seconds since the epoch
description	String	You guessed it! The blog's description
ask	Boolean	Indicates whether the blog allows questions
ask_anon	Boolean	Indicates whether the blog allows anonymous questions	Returned only if `ask` is true
likes	Number	Number of likes for this user	Returned only if this is the user's primary blog and sharing of likes is enabled

Example

http://api.tumblr.com/v2/blog/david.tumblr.com/info?api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": {
         "title": "David's Log",
         "posts": 3456,
         "name": "david",
         "url": "http:\/\/david.tumblr.com\/",
         "updated": 1308953007,
         "description": "<p><strong>Mr. Karp<\/strong> is tall and skinny, with
            unflinching blue eyes a mop of brown hair.\r\n
            He speaks incredibly fast and in complete paragraphs.</p>",
         "ask": true,
         "ask_anon": false,
         "likes": 12345
      }
   }
}

/avatar — Retrieve a Blog Avatar

You can get a blog's avatar in 9 different sizes. The default size is 64x64.

Examples

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/avatar[/size]`	GET	None

Request Parameters

Parameter	Type	Description	Default	Required?
base-hostname	String	The standard or custom blog hostname See the Overview for more details.	N/A	Yes
size	Number	The size of the avatar (square, one value for both length and width). Must be one of the values: `16, 24, 30, 40, 48, 64, 96, 128, 512`	64	No

Responses

Response Field	Type	Description	Notes
avatar_url	String	The URL of the avatar image. This is also returned in the Location HTTP header field (see note).	An HTTP Location header field is returned — the response points to the avatar image. That means you can embed this method in an `img` tag in HTML.

/likes — Retrieve Blog's Likes

This method can be used to retrieve the publicly exposed likes from a blog.

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/likes?api_key={key}`	GET	API Key

Request Parameters

Parameter	Type	Description	Default	Required?
limit	Number	The number of results to return: `1–20`, inclusive	20	No
offset	Number	Liked post number to start at	0 (first post)	No

Responses

Response Field	Type	Description
liked_posts	Array	An array of post objects (posts liked by the user)
liked_count	Number	Total number of liked posts

/followers — Retrieve a Blog's Followers

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/followers`	GET	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
base-hostname	String	The standard or custom blog hostname See the Overview for more details.	N/A	Yes
limit	Number	The number of results to return: `1–20`, inclusive	20	No
offset	Number	Result to start at	0 (first follower)	No

Responses

These fields are wrapped in a users object:

Response Field	Type	Description
total_users	Number	The number of users currently following the blog
users	Array	Each item is a follower, containing these fields:
name	String	The user's name on tumblr
url	String	The URL of the user's primary blog
updated	Number	The time of the user's most recent post, in seconds since the epoch

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "total_users": 2684,
      "users":  [
            {
               "name": "david",
               "url": "http:\/\/www.davidslog.com",
               "updated": 1308781073
            },
            {
               "name": "ben",
               "url": "http:\/\/bengold.tv",
               "updated": 1308841333
            },
            ...
         ]
   }
}

/posts – Retrieve Published Posts

Examples

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/posts[/type]?api_key={key}&[optional-params=]`	GET	API key

Request Parameters

Parameter	Type	Description	Default	Required?
base-hostname	String	The standard or custom blog hostname See the Overview for more details.	N/A	Yes
api_key	String	Your OAuth Consumer Key See Authentication for more details.	N/A	Yes
type	String	The type of post to return. Specify one of the following: `text, quote, link, answer, video, audio, photo, chat`	None – return all types	No
id	Number	A specific post ID. Returns the single post specified or (if not found) a 404 error.	None	No
tag	String	Limits the response to posts with the specified tag	None	No
limit	Number	The number of posts to return: `1–20`, inclusive	20	No
offset	Number	Post number to start at	0 (first post)	No
reblog_info	Boolean	Indicates whether to return reblog information (specify `true` or `false`). Returns the various `reblogged_` fields.	False	No
notes_info	Boolean	Indicates whether to return notes information (specify `true` or `false`). Returns note count and note metadata.	False	No
filter	String	Specifies the post format to return, other than HTML: `text` – Plain text, no HTML `raw` – As entered by the user (no post-processing); if the user writes in Markdown, the Markdown will be returned rather than HTML	None (HTML)	No

reblog_info and notes_info are false by default because of the server impact involved in retrieving the data.

Responses

Each response includes a blog object that is the equivalent of an /info response. Posts are returned as an array attached to the posts field.

All Post Types

Response Field	Type	Description	Notes
blog_name	String	The short name used to uniquely identify a blog
id	Number	The post's unique ID
post_url	String	The location of the post
type	String	The type of post	See the `type` request parameter
timestamp	Number	The time of the post, in seconds since the epoch
date	String	The GMT date and time of the post, as a string
format	String	The post format: `html` or `markdown`
reblog_key	String	The key used to reblog this post	See the `/reblog` method
tags	Array (string)	Tags applied to the post
bookmarklet	Boolean	Indicates whether the post was created via the Tumblr bookmarklet	Exists only if true
mobile	Boolean	Indicates whether the post was created via mobile/email publishing	Exists only if true
source_url	String	The URL for the source of the content (for quotes, reblogs, etc.)	Exists only if there's a content source
source_title	String	The title of the source site	Exists only if there's a content source
liked	Boolean	Indicates if a user has already liked a post or not	Exists only if the request is fully authenticated with OAuth.
state	String	Indicates the current state of the post	States are `published`, `queued`, `draft` and `private`
total_posts	Number	The total number of post available for this request, useful for paginating through results

Text Posts

Response Field	Type	Description
title	String	The optional title of the post
body	String	The full post body

http://api.tumblr.com/v2/blog/citriccomics.tumblr.com/posts/text?api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "citriccomics",
            "id": 3507845453,
            "post_url": "http:\/\/citriccomics.tumblr.com\/post\/3507845453",
            "type": "text",
            "date": "2011-02-25 20:27:00 GMT",
            "timestamp": 1298665620,
            "state": "published",
            "format": "html",
            "reblog_key": "b0baQtsl",
            "tags": [
               "tumblrize",
               "milky dog",
               "mini comic"
            ],
            "note_count": 14,
            "title": "Milky Dog",
            "body": "<p><img src=\"http:\/\/media.tumblr.com\
               /tumblr_lh6x8d7LBB1qa6gy3.jpg\"\/><a href=\"http:\/\
               /citriccomics.com\/blog\/?p=487\" target=\"_blank\">TO READ
               THE REST CLICK HERE<\/a><br\/>\n\nMilky Dog was inspired by
               something <a href=\"http:\/\/gunadie.com\/naomi\"
               target=\"_blank\">Naomi Gee<\/a> wrote on twitter, I really
               liked the hash tag <a href=\"http:\/\/twitter.com\/
               search?q=%23MILKYDOG\" target=\"_blank\">#milkydog<\/a>
               and quickly came up with a little comic about it. You can
               (and should) follow Naomi on twitter <a href=\"http:\/\
               /twitter.com\/ngun\" target=\"_blank\">@ngun<\/a> I'm on
               twitter as well <a href=\"http:\/\/twitter.com\
               /weflewairplanes\"target=\"_blank\">@weflewairplanes<\/a>
               <\/p>\n\nAlso, if youâ€™re a Reddit user (or even if
               you're not) I submitted this there, if you could up vote
               it I'd be super grateful just <a href=\"http:\/\
               /tinyurl.com\/5wj3tqz\" target=\"_blank\">CLICK HERE<\/a>"
         },
         ...
      ],
      "total_posts": 3
   }
}

Photo Posts

Response Field	Type	Description
photos	Array	Photo objects with properties: `caption` – string: user supplied caption for the individual photo (Photosets only) `alt_sizes` – array: alternate photo sizes, each with: `width` – number: width of the photo, in pixels `height` – number: height of the photo, in pixels `url` – string: Location of the photo file (either a JPG, GIF, or PNG)
caption	String	The user-supplied caption
width	Number	The width of the photo or photoset
height	Number	The height of the photo or photoset

Multi-photo Photo posts, called Photosets, will send return multiple photo objects in the photos array.

http://api.tumblr.com/v2/blog/derekg.org/posts?id=7431599279&api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "derekg",
            "id": 7431599279,
            "post_url": "http:\/\/derekg.org\/post\/7431599279",
            "type": "photo",
            "date": "2011-07-09 22:09:47 GMT",
            "timestamp": 1310249387,
            "format": "html",
            "reblog_key": "749amggU",
            "tags": [],
            "note_count": 18,
            "caption": "<p>my arm is getting tired.<\/p>",
            "photos": [
               {
                  "caption": "",
                  "alt_sizes": [
                     {
                        "width": 1280,
                        "height": 722,
                        "url": "http:\/\/derekg.org\/photo\/1280\/7431599279\/1\/
                           tumblr_lo36wbWqqq1qanqww"
                     },
                     {
                        "width": 500,
                        "height": 282,
                        "url": "http:\/\/30.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_500.jpg"
                     },
                     {
                        "width": 400,
                        "height": 225,
                        "url": "http:\/\/29.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_400.jpg"
                     },
                     {
                        "width": 250,
                        "height": 141,
                        "url": "http:\/\/26.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_250.jpg"
                     },
                     {
                        "width": 100,
                        "height": 56,
                        "url": "http:\/\/24.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_100.jpg"
                     },
                     {
                        "width": 75,
                        "height": 75,
                        "url": "http:\/\/30.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_75sq.jpg"
                     }
                  ]
               }
            ]
         }
      ],
      "total_posts": 1
   }
}

Quote Posts

Response Field	Type	Description	Notes
text	String	The text of the quote (can be modified by the user when posting)
source	String	Full HTML for the source of the quote Example: `<a href="...">Steve Jobs</a>`	See also the table of common response fields

http://api.tumblr.com/v2/blog/museumsandstuff.tumblr.com/posts/quote?api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "museumsandstuff",
            "id": 4742980381,
            "post_url": "http:\/\/museumsandstuff.tumblr.com\/post\/4742980381",
            "type": "quote",
            "date": "2011-04-19 08:52:34 GMT",
            "timestamp": 1303203154,
            "format": "html",
            "reblog_key": "KLA85e6c",
            "tags": [],
            "note_count": 23,
            "source_url": "http:\/\/museumtwo.blogspot.com\/2011\/04\/
               guest-post-convivial-museum-photo-essay.html",
            "source_title": "museumtwo.blogspot.com",
            "text": "Why do visitors still report discomfort, confusion,
               elitism, exclusion?",
            "source": "<a href=\"http:\/\/museumtwo.blogspot.com\/2011\/04\/
               guest-post-convivial-museum-photo-essay.html\"
               target=\"_blank\">Museum 2.0: Guest Post: The Convivial
               Museum Photo Essay<\/a> (via <a href=\"http:\/\/
               www.joshrobinson.org\/\"target=\"_blank\">joshrobinsonblog
               <\/a>)"
         },
         ...
      ],
      "total_posts": 9
   }
}

Link Posts

Response Field	Type	Description
title	String	The title of the page the link points to
url	String	The link
description	String	A user-supplied description

http://api.tumblr.com/v2/blog/travellingcameraclub.com/posts/link?api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "travellingcameraclub",
            "id": 688472164,
            "post_url": "http:\/\/travellingcameraclub.com\/post\/688472164",
            "type": "link",
            "date": "2010-06-11 23:17:08 GMT",
            "timestamp": 1276298228,
            "format": "html",
            "reblog_key": "RWhJJWia",
            "tags": [],
            "note_count": 9,
            "title": "Esther Aarts Illustration | News and Blog: Faq: How do
               you make those marker doodles?",
            "url": "http:\/\/blog.estadiezijn.nl\/post\/
               459075181\/faq-how-do-you-make-those-marker-doodles",
            "description": "<blockquote>\n<p>On my Ipad, of course!<\/p>
                <p>Nothing better than the latest technology to get the job done.
                Look at all my apps!<\/p> <p><img height=\"555\" width=\"500\"
                src=\"http:\/\/farm5.static.flickr.com\/4006\/
                4445161463_31da0327c2_o.jpg\" alt=\"my iPad\"\/><\/p>
                <p>My favourite markers are an Edding 400, a Sharpie and a
                Copic Ciao. The white gouache is from Dr Martins and does a
                decent job covering up whatever needs to be covered up, and
                flows.<\/p><\/blockquote>"
         }
         ...
      ],
      "total_posts": 7
   }
}

Chat Posts

Response Field	Type	Description
title	String	The optional title of the post
body	String	The full chat body
dialogue	Array	Array of objects with the following properties: `name` – string: name of the speaker `label` – string: label of the speaker `phrase` – string: text

http://api.tumblr.com/v2/blog/www.davidslog.com/posts/chat?api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "david",
            "id": 5845345725,
            "post_url": "http:\/\/www.davidslog.com\/5845345725\/
            if-youre-okay-with-it-destroying-tumblr,
            "type": "chat",
            "date": "2011-05-25 22:32:00 GMT",
            "timestamp": 1306362720,
            "format": "html",
            "reblog_key": "wlxAsElf",
            "tags": [],
            "note_count": 114,
            "title": null,
            "body": "David: http://staff.tumblr.com/post/5845153911
                [draft] Topherchris: are you freaking serious\r\n
                David: If you're okay with it - I'd love to :)\r\n
                Topherchris: i'm okay with it, if you're okay with
                it destroying tumblr",
            "dialogue": [
                {
                   "label": "David:",
                   "name": "David",
                   "phrase": "http://staff.tumblr.com/post/5845153911 [draft]\r",
                },
                {
                   "label": "Topherchris:",
                   "name": "Topherchris",
                   "phrase":"are you freaking serious\r"
                },
                {
                   "label": "David:",
                   "name": "David",
                   "phrase": "If you're okay with it - I'd love to :)"
                },
                {
                   "label": "Topherchris:",
                   "name": "Topherchris",
                   "phrase": "i'm okay with it, if you're okay with it
                      destroying tumblr",
                }
            ]
         }
         ...
      ],
      "total_posts": 7
   }
}

Audio Posts

Response Field	Type	Description
caption	String	The user-supplied caption
player	String	HTML for embedding the audio player
plays	Number	Number of times the audio post has been played
album_art	String	Location of the audio file's ID3 album art image
artist	String	The audio file's ID3 `artist` value
album	String	The audio file's ID3 `album` value
track_name	String	The audio file's ID3 `title` value
track_number	Number	The audio file's ID3 `track` value
year	Number	The audio file's ID3 `year` value

http://api.tumblr.com/v2/blog/derekg.org/posts?id=5578378101&api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "derekg",
            "id": 5578378101,
            "post_url": "http:\/\/derekg.org\/post\/5578378101/otis-redding",
            "type": "audio",
            "date": "2011-05-17 16:21:05 GMT",
            "timestamp": 1305649265,
            "format": "html",
            "reblog_key": "Wa65rR5l",
            "tags": [],
            "note_count": 3,
            "source_url": "http:\/\/soundcloud.com\/mariam-cabal\/otis-redding",
            "source_title": "SoundCloud \/ Mariam Caballero",
            "id3_title": "Otis Redding - Cigarettes And Coffee",
            "caption": "<p>Otis Redding never fails me.\u00a0<\/p>",
            "player": "<embed type=\"application\/x-shockwave-flash\"
                src=\"http:\/\/assets.tumblr.com\/swf\/audio_player.swf?
                audio_file=http:\/\/www.tumblr.com\/audio_file\/5578378101\/
                tumblr_llclf5oDKZ1qanqww&color=FFFFFF&logo=soundcloud\"
                height=\"27\" width=\"207\" quality=\"best\"><\/embed>",
            "plays": 1576
         }
      ],
      "total_posts": 1
   }
}

Video Posts

Response Field	Type	Description	Notes
caption	String	The user-supplied caption
player	Array of embed objects	Object fields within the array: `width` – number: width of video player, in pixels `embed_code` – string: HTML for embedding the video player	Values vary by video source

http://api.tumblr.com/v2/blog/john.io/posts/video?api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "john",
            "id": 6522991678,
            "post_url": "http:\/\/john.io\/post\/6522991678",
            "type": "video",
            "date": "2011-06-14 15:51:21 GMT",
            "timestamp": 1308066681,
            "format": "html",
            "reblog_key": "sWRdVJrI",
            "tags": [],
            "note_count": 17,
            "source_url": "http:\/\/www.WatchMojo.com",
            "source_title": "WatchMojo.com",
            "caption": "<p><a href=\"http:\/\/foreverneilyoung.tumblr.com\/
               post\/6522738445\" target=\"_blank\">foreverneilyoung<\/a>:
               <\/p>\n<blockquote>\n<p><a href=\"http:\/\/watchmojo.tumblr.com\/
               post\/6521201320\" target=\"_blank\">watchmojo<\/a>:<\/p>\n
               <blockquote>\n<p>Neil Young\u2019s live album \u201cA Treasure\
               u201d is available today. To celebrate, we take a look at the
               life and career of the Canadian singer-songwriter.
               <\/p>\n<\/blockquote>\n<p>Neil 101 for you new fans out
               there.<\/p>\n<\/blockquote>\n<p><strong>If you don't
               know\/appreciate Neil Young's impressive body of work,
               this will help<\/strong><\/p>",
            "player": [
               {
                  "width": 250,
                  "embed_code": "<object width=\"248\" height=\"169\"><param
                     name=\"movie\" value=\"http:\/\/www.youtube.com\/
                     v\/4Q1aI7xPo0Y&rel=0&egm=0&
                     showinfo=0&fs=1\"><\/param><param name=\"wmode\"
                     value=\"transparent\"><\/param><param name=\"
                     allowFullScreen\" value=\"true\"><\/param><embed
                     src=\"http:\/\/www.youtube.com\/v\/
                     4Q1aI7xPo0Y&rel=0&egm=0&showinfo=
                     0&fs=1\" type=\"application\/x-shockwave-flash\"
                     width=\"248\" height=\"169\" allowFullScreen=\"true\"
                     wmode=\"transparent\"><\/embed><\/object>"
               },
               {
                  "width": 400,
                  "embed_code": "<object width=\"400\" height=\"251\">
                     <param name=\"movie\" value=\"http:\/\/www.youtube.com\/
                     v\/4Q1aI7xPo0Y&rel=0&egm=0&showinfo=0&fs=1\"><\/
                     param><param name=\"wmode\" value=\"transparent
                     \"><\/param><param name=\"allowFullScreen\" value=
                     \"true\"><\/param><embed src=\"http:\/\/www.youtube.com
                     \/v\/4Q1aI7xPo0Y&rel=0&egm=0&
                     showinfo=0&fs=1\" type=\"application\/
                     x-shockwave-flash\" width=\"400\" height=\"251\"
                     allowFullScreen=\"true\" wmode=\"transparent\">
                     <\/embed><\/object>"
               },
               {
                  "width": 500,
                  "embed_code": "<object width=\"500\" height=\"305\"><param
                     name=\"movie\" value=\"http:\/\/www.youtube.com\/
                     v\/4Q1aI7xPo0Y&rel=0&egm=0&
                     showinfo=0&fs=1\"><\/param><param name=\"wmode\"
                     value=\"transparent\"><\/param><param name=\"
                     allowFullScreen\" value=\"true\"><\/param><embed
                     src=\"http:\/\/www.youtube.com\/v\/4Q1aI7xPo0Y&
                     rel=0&egm=0&showinfo=0&fs=1\"
                     type=\"application\/x-shockwave-flash\" width=\"500\"
                     height=\"305\" allowFullScreen=\"true\"
                     wmode=\"transparent\"><\/embed><\/object>"
               }
            ]
         },
         ...
      ],
      "total_posts": 48
   }
}

Answer Posts

Response Field	Type	Description
asking_name	String	The blog name of the user asking the question
asking_url	String	The blog URL of the user asking the question
question	String	The question being asked
answer	String	The answer given

http://api.tumblr.com/v2/blog/david.tumblr.com/posts?id=7504154594&api_key={key}

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "david",
            "id": 7504154594,
            "post_url": "http://www.davidslog.com/7504154594",
            "type": "answer",
            "date": "2011-07-11 20:24:14 GMT",
            "timestamp": 1310415854,
            "format": "html",
            "reblog_key": "HNvqLd5G",
            "tags": [],
            "asking_name": "aperfectfacade",
            "asking_url": "http://aperfectfacade.tumblr.com/",
            "question": "I thought Tumblr started in 2007, yet you
               have posts from 2006?",
            "answer": "<p>Good catch! Tumblr <strong>launched</strong> in
               February 2007. We were testing it for a few months before
               then.</p>\n<p><strong>Tumblr Trivia:</strong> Before Tumblr,
               my blog (davidslog.com) was a manually edited, single page,
               HTML tumblelog.</p>"
         }
      ],
      "total_posts": 1
   }
}

/posts/queue — Retrieve Queued Posts

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/posts/queue`	GET	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
offset	String	Post number to start at	0 (first post)	No
limit	Number	The number of results to return: `1–20`, inclusive	20	No
filter	String	Specifies the post format to return, other than HTML: `text` – Plain text, no HTML `raw` – As entered by the user (no post-processing); if the user writes in Markdown, the Markdown will be returned rather than HTML	None (HTML)	No

Responses

See the table of common response fields.

/posts/draft — Retrieve Draft Posts

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/posts/draft`	GET	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
filter	String	Specifies the post format to return, other than HTML: `text` – Plain text, no HTML `raw` – As entered by the user (no post-processing); if the user writes in Markdown, the Markdown will be returned rather than HTML	None (HTML)	No

Responses

See the table of common response fields.

The complete set of draft posts is returned (no pagination).

/posts/submission — Retrieve Submission Posts

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/posts/submission`	GET	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
offset	String	Post number to start at	0 (first post)	No
filter	String	Specifies the post format to return, other than HTML: `text` – Plain text, no HTML `raw` – As entered by the user (no post-processing); if the user writes in Markdown, the Markdown will be returned rather than HTML	None (HTML)	No

Responses

See the table of common response fields.

/post — Create a New Blog Post

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/post`	POST	OAuth

Request Parameters

These parameters are used for /post, /post/edit and /post/reblog methods.

All Post Types

Parameter	Type	Description	Default	Required?
type	String	The type of post to create. Specify one of the following: `text, photo, quote, link, chat, audio, video`	text	Yes
state	String	The state of the post. Specify one of the following: `published, draft, queue, private`	published	No
tags	String	Comma-separated tags for this post	None	No
tweet	String	Manages the autotweet (if enabled) for this post: set to `off` for no tweet, or enter text to override the default tweet	None	No
date	String	The GMT date and time of the post, as a string	The date and time of the POST request	No
format	String	Sets the format type of post. Supported formats are: html & markdown	html	No
slug	String	Add a short text summary to the end of the post URL	Dynamically generated if enabled on the blog	No

Text Posts

Parameter	Type	Description	Default	Required?
title	String	The optional title of the post, HTML entities must be escaped	None	No
body	String	The full post body, HTML allowed	None	Yes

Photo Posts

Parameter	Type	Description	Default	Required?
caption	String	The user-supplied caption, HTML allowed	None	No
link	String	The "click-through URL" for the photo	None	No
source	String	The photo source URL	None	Yes, either `source` or `data`
data	Array (URL-encoded binary contents) Limit: 10 MB	One or more image files (submit multiple times to create a slide show)	None	Yes, either `source` or `data`

Quote Posts

Parameter	Type	Description	Default	Required?
quote	String	The full text of the quote, HTML entities must be escpaed	None	Yes
source	String	Cited source, HTML allowed	None	No

Link Posts

Parameter	Type	Description	Default	Required?
title	String	The title of the page the link points to, HTML entities should be escaped	None	No
url	String	The link	None	Yes
description	String	A user-supplied description, HTML allowed	None	No

Chat Posts

Parameter	Type	Description	Default	Required?
title	String	The title of the chat	None	No
conversation	String	The text of the conversation/chat, with dialogue labels (no HTML)	None	Yes

Audio Posts

Parameter	Type	Description	Default	Required?
caption	String	The user-supplied caption	None	No
external_url	String	The URL of the site that hosts the audio file (not tumblr)	None	Yes, either `external_url` or `data`
data	String (URL-encoded binary contents) Limit: 10 MB	An audio file	None	Yes, either `external_url` or `data`

Video Posts

Parameter	Type	Description	Default	Required?
caption	String	The user-supplied caption	None	No
embed	String	HTML embed code for the video	None	Yes, either `embed` or `data`
data	String (URL-encoded binary contents) Limit: 100 MB	A video file	None	Yes, either `embed` or `data`

Responses

Returns 201: Created or an error code.

/post/edit – Edit a Blog Post

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/post/edit`	POST	OAuth

Request Parameters

This parameter is in addition to the common parameters listed under /post.

Parameter	Type	Description	Default	Required?
id	Number	The ID of the post to edit	None	Yes

Responses

Returns 200: OK (successfully edited) or an error code.

/post/reblog – Reblog a Post

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/post/reblog`	POST	OAuth

Request Parameters

These parameters are in addition to the common parameters listed under /post.

Parameter	Type	Description	Default	Required?
id	Number	The ID of the reblogged post on `tumblelog`	None	Yes
reblog_key	Number	The reblog key for the reblogged post – get the reblog key with a /posts request	None	Yes
comment	String	A comment added to the reblogged post	None	No

Responses

Returns 201: Created or an error code.

/post/delete – Delete a Post

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/blog/{base-hostname}/post/delete`	POST	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
id	Number	The ID of the post to delete	None	Yes

Responses

Returns 200: OK (successfully deleted) or an error code.

User Methods

/user/info – Get a User's Information

Use this method to retrieve the user's account information that matches the OAuth credentials submitted with the request.

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/info`	GET	OAuth

Responses

Response Field	Type	Description
following	Number	The number of blogs the user is following
default_post_format	String	The default posting format - `html, markdown or raw`
name	String	The user's tumblr short name
likes	Number	The total count of the user's likes
blogs	Array	Each item is a blog the user has permissions to post to, containing these fields: `name` – string: the short name of the blog `url` – string: the URL of the blog `title` – string: the title of the blog `primary` – boolean: indicates if this is the user's primary blog `followers` – number: total count of followers for this blog `tweet` – number: indicate if posts are tweeted `auto, Y, N` `facebook` – indicate if posts are sent to facebook `Y, N` `type` – indicates whether a blog is `public` or `private`

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
     "user": {
       "following": 263,
       "default_post_format": "html",
       "name": "derekg",
       "likes": 606,
       "blogs": [
          {
           "name": "derekg",
           "title": "Derek Gottfrid",
           "url": "http://derekg.org/",
           "tweet": "auto",
           "primary": true,
           "followers": 33004929,
          },
          {
           "name": "ihatehipstrz",
           "title": "I Hate Hipstrz",
           ...
          }
        ]
     }
}

/user/dashboard – Retrieve a User's Dashboard

Use this method to retrieve the dashboard that matches the OAuth credentials submitted with the request.

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/dashboard`	GET	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
limit	Number	The number of results to return: `1–20`, inclusive	20	No
offset	Number	Post number to start at	0 (first post)	No
type	String	The type of post to return. Specify one of the following: `text, photo, quote, link, chat, audio, video, answer`	None – return all types	No
since_id	Number	Return posts that have appeared after this ID Use this parameter to page through the results: first get a set of posts, and then get posts since the last ID of the previous set.	0	No
reblog_info	Boolean	Indicates whether to return reblog information (specify `true` or `false`). Returns the various `reblogged_` fields.	False	No
notes_info	Boolean	Indicates whether to return notes information (specify `true` or `false`). Returns note count and note metadata.	False	No

Responses

Dashboard responses include the fields returned in /posts responses (with all the various type-specific fields), but without the blog object. Instead, a blog_name field identifies the blog for each post returned.

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "posts": [
         {
            "blog_name": "laughingsquid",
            "id": 6828225215,
            "post_url": "http:\/\/links.laughingsquid.com\/post\/6828225215",
            ...
         }
      ]
   }
}

/user/likes — Retrieve a User's Likes

Use this method to retrieve the liked posts that match the OAuth credentials submitted with the request.

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/likes`	GET	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
limit	Number	The number of results to return: `1–20`, inclusive	20	No
offset	Number	Liked post number to start at	0 (first post)	No

Responses

Response Field	Type	Description
liked_posts	Array	An array of post objects (posts liked by the user)
liked_count	Number	Total number of liked posts

/user/following – Retrieve the Blogs a User Is Following

Use this method to retrieve the blogs followed by the user whose OAuth credentials are submitted with the request.

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/following`	GET	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
limit	Number	The number of results to return: `1–20`, inclusive	20	No
offset	Number	Result number to start at	0 (first followee)	No

Responses

These fields are wrapped in a blog object:

Response Field	Type	Description
total_blogs	Number	The number of blogs the user is following
blogs	Array	Each item is a blog that's being followed, containing these fields: `name` – string: the user name attached to the blog that's being followed `url` – string: the URL of the blog that's being followed `updated` – number: the time of the most recent post, in seconds since the epoch

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
       "total_blogs": 259,
       "blogs": [
          {
             "name": "david",
             "url": "http:\/\/www.davidslog.com",
             "updated": 1308781073
          },
          {
             "name": "matthew",
             "url": "http:\/\/matthew.tumblr.com",
             "updated": 1306436424
          },
          ...
       ]
   }
}

/user/follow – Follow a blog

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/follow`	POST	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
url	String	The URL of the blog to follow	None	Yes

Responses

Returns 200: OK (blog successfully followed) or a 404 (blog was not found)

/user/unfollow – Unfollow a blog

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/unfollow`	POST	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
url	String	The URL of the blog to unfollow	None	Yes

Responses

Returns 200: OK (blog successfully unfollowed) or a 404 (blog was not found)

/user/like – Like a Post

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/like`	POST	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
id	Number	The ID of the post to like	None	Yes
reblog_key	String	The reblog key for the post id	None	Yes

Responses

Returns 200: OK (post successfully liked ) or a 404 (post id or reblog_key was not found)

/user/unlike – Unlike a Post

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/user/unlike`	POST	OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
id	Number	The ID of the post to unlike	None	Yes
reblog_key	String	The reblog key for the post id	None	Yes

Responses

Returns 200: OK (post successfully unliked ) or a 404 (post id or reblog_key was not found)

Tagged Method

/tagged – Get Posts with Tag

Examples

Method

URI	HTTP Method	Authentication
`api.tumblr.com/v2/tagged`	GET	API Key or OAuth

Request Parameters

Parameter	Type	Description	Default	Required?
tag	String	The tag on the posts you'd like to retrieve	None	Yes
before	Integer	The timestamp of when you'd like to see posts before. If the Tag is a "featured" tag, use the "featured_timestamp" on the post object for pagination.	Current timestamp	No
limit	Number	The number of results to return: `1–20`, inclusive	20	No
filter	String	Specifies the post format to return, other than HTML: `text` – Plain text, no HTML `raw` – As entered by the user (no post-processing); if the user writes in Markdown, the Markdown will be returned rather than HTML	None (HTML)	No

Responses

See the table of common response fields.

Tumblr

Contents

Tumblr API

What You Need

Overview

URI Structure

Blog Hostname

Response Format

Example

About the API Documentation

URI Conventions

Authentication

OAuth

Endpoints

API Clients

Blog Methods

/info — Retrieve Blog Info

Examples

Method

Request Parameters

Responses

Example

/avatar — Retrieve a Blog Avatar

Examples

Method

Request Parameters

Responses

/likes — Retrieve Blog's Likes

Method

Request Parameters

Responses

/followers — Retrieve a Blog's Followers

Method

Request Parameters

Responses

Example

/posts – Retrieve Published Posts

Examples

Method

Request Parameters

Responses

All Post Types

Text Posts

Photo Posts

Quote Posts

Link Posts

Chat Posts

Audio Posts

Video Posts

Answer Posts

/posts/queue — Retrieve Queued Posts

Method

Request Parameters

Responses

/posts/draft — Retrieve Draft Posts

Method

Request Parameters

Responses

/posts/submission — Retrieve Submission Posts

Method

Request Parameters

Responses

/post — Create a New Blog Post

Method

Request Parameters

All Post Types

Text Posts

Photo Posts

Quote Posts

Link Posts

Chat Posts

Audio Posts

Video Posts

Responses

/post/edit – Edit a Blog Post

Method

Request Parameters

Responses

/post/reblog – Reblog a Post

Method