Contents

What You Need
Overview
Console
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.

Console

Check out or developer console to test calls, and see live examples of using our official clients: API Console

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)
responseAPI-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

NotationMeaningExample
Curly brackets { }Required itemapi.tumblr.com/v2/blog/
{base-hostname}/posts

The blog hostname is required.
Square brackets [ ]Optional itemapi.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.

  1. None: No authentication. Anybody can query the method.
  2. API key: Requires an API key. Use your OAuth Consumer Key as your api_key.
  3. 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 URLhttp://www.tumblr.com/oauth/request_token
Authorize URLhttp://www.tumblr.com/oauth/authorize
Access-token URLhttp://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

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/info?api_key={key}GETAPI key

Request Parameters

ParameterTypeDescriptionDefaultRequired?
base-hostnameString The standard or custom blog hostname
See the Overview for more details.
N/AYes
api_keyString Your OAuth Consumer Key
See Authentication for more details.
N/AYes

Responses

Response FieldTypeDescriptionNotes
titleStringThe display title of the blogCompare name
postsNumberThe total number of posts to this blog 
nameStringThe short blog name that appears before tumblr.com in a standard blog hostname (and before the domain in a custom blog hostname)Compare title
updatedNumberThe time of the most recent post, in seconds since the epoch 
descriptionStringYou guessed it! The blog's description 
askBooleanIndicates whether the blog allows questions 
ask_anonBooleanIndicates whether the blog allows anonymous questionsReturned only if ask is true
likesNumberNumber of likes for this userReturned only if this is the user's primary blog and sharing of likes is enabled

Example

{
   "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

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/avatar[/size]GETNone

Request Parameters

ParameterTypeDescriptionDefaultRequired?
base-hostnameString The standard or custom blog hostname
See the Overview for more details.
N/AYes
sizeNumber 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
64No

Responses

Response FieldTypeDescriptionNotes
avatar_urlStringThe 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

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/likes?api_key={key}GETAPI Key

Request Parameters

ParameterTypeDescriptionDefaultRequired?
limitNumberThe number of results to return: 1–20, inclusive20No
offsetNumberLiked post number to start at0 (first post)No

Responses

Response FieldTypeDescription
liked_postsArrayAn array of post objects (posts liked by the user)
liked_countNumberTotal number of liked posts

/followers — Retrieve a Blog's Followers

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/followersGETOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
base-hostnameString The standard or custom blog hostname
See the Overview for more details.
N/AYes
limitNumberThe number of results to return: 1–20, inclusive20No
offsetNumberResult to start at0 (first follower)No

Responses

These fields are wrapped in a users object:

Response FieldTypeDescription
total_usersNumberThe number of users currently following the blog
usersArrayEach item is a follower, containing these fields:
nameStringThe user's name on tumblr
followingBooleanWhether the caller is following the user
urlStringThe URL of the user's primary blog
updatedNumberThe 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",
               "following": true,
               "url": "http:\/\/www.davidslog.com",
               "updated": 1308781073
            },
            {
               "name": "ben",
               "following": true,
               "url": "http:\/\/bengold.tv",
               "updated": 1308841333
            },
            ...
         ]
   }
}

/posts – Retrieve Published Posts

Examples

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/posts[/type]?api_key={key}&[optional-params=]GETAPI key

Request Parameters

ParameterTypeDescriptionDefaultRequired?
base-hostnameString The standard or custom blog hostname
See the Overview for more details.
N/AYes
api_keyString Your OAuth Consumer Key
See Authentication for more details.
N/AYes
typeString The type of post to return. Specify one of the following:  text, quote, link, answer, video, audio, photo, chatNone – return all typesNo
idNumber A specific post ID. Returns the single post specified or (if not found) a 404 error. NoneNo
tagStringLimits the response to posts with the specified tagNoneNo
limitNumberThe number of posts to return: 1–20, inclusive20No
offsetNumberPost number to start at0 (first post)No
reblog_infoBoolean Indicates whether to return reblog information (specify true or false). Returns the various reblogged_ fields. FalseNo
notes_infoBoolean Indicates whether to return notes information (specify true or false). Returns note count and note metadata. FalseNo
filterString 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 FieldTypeDescriptionNotes
blog_nameStringThe short name used to uniquely identify a blog 
idNumberThe post's unique ID 
post_urlStringThe location of the post 
typeStringThe type of postSee the type request parameter
timestampNumberThe time of the post, in seconds since the epoch 
dateStringThe GMT date and time of the post, as a string 
formatStringThe post format: html or markdown 
reblog_keyStringThe key used to reblog this postSee the /post/reblog method
tagsArray (string)Tags applied to the post 
bookmarkletBooleanIndicates whether the post was created via the Tumblr bookmarkletExists only if true
mobileBooleanIndicates whether the post was created via mobile/email publishingExists only if true
source_urlStringThe URL for the source of the content (for quotes, reblogs, etc.)Exists only if there's a content source
source_titleStringThe title of the source siteExists only if there's a content source
likedBooleanIndicates if a user has already liked a post or notExists only if the request is fully authenticated with OAuth.
stateStringIndicates the current state of the postStates are published, queued, draft and private
total_postsNumberThe total number of post available for this request, useful for paginating through results 

Text Posts

Response FieldTypeDescription
titleStringThe optional title of the post
bodyStringThe full post body
{
   "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 FieldTypeDescription
photosArray 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)
captionStringThe user-supplied caption
widthNumberThe width of the photo or photoset
heightNumberThe height of the photo or photoset

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

{
   "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 FieldTypeDescriptionNotes
textStringThe text of the quote (can be modified by the user when posting) 
sourceString Full HTML for the source of the quote
Example: <a href="...">Steve Jobs</a>
See also the table of common response fields
{
   "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
   }
}
Response FieldTypeDescription
titleStringThe title of the page the link points to
urlStringThe link
descriptionStringA user-supplied description
{
   "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 FieldTypeDescription
titleStringThe optional title of the post
bodyStringThe full chat body
dialogueArray Array of objects with the following properties:
  • name – string: name of the speaker
  • label – string: label of the speaker
  • phrase – string: text
{
   "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 FieldTypeDescription
captionStringThe user-supplied caption
playerStringHTML for embedding the audio player
playsNumberNumber of times the audio post has been played
album_artStringLocation of the audio file's ID3 album art image
artistStringThe audio file's ID3 artist value
albumStringThe audio file's ID3 album value
track_nameStringThe audio file's ID3 title value
track_numberNumberThe audio file's ID3 track value
yearNumberThe audio file's ID3 year value
{
   "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 FieldTypeDescriptionNotes
captionStringThe user-supplied caption 
playerArray 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
{
   "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 FieldTypeDescription
asking_nameStringThe blog name of the user asking the question
asking_urlStringThe blog URL of the user asking the question
questionStringThe question being asked
answerStringThe answer given
{
   "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

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/posts/queueGETOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
offsetStringPost number to start at0 (first post)No
limitNumberThe number of results to return: 1–20, inclusive20No
filterString 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

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/posts/draftGETOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
before_idNumber 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.
0No
filterString 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/submission — Retrieve Submission Posts

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/posts/submissionGETOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
offsetStringPost number to start at0 (first post)No
filterString 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

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/postPOSTOAuth

Request Parameters

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

All Post Types

ParameterTypeDescriptionDefaultRequired?
typeString The type of post to create. Specify one of the following:  text, photo, quote, link, chat, audio, videotextYes
stateString The state of the post. Specify one of the following:  published, draft, queue, private publishedNo
tagsStringComma-separated tags for this postNoneNo
tweetStringManages the autotweet (if enabled) for this post: set to off for no tweet, or enter text to override the default tweetNoneNo
dateStringThe GMT date and time of the post, as a stringThe date and time of the POST requestNo
formatStringSets the format type of post. Supported formats are: html & markdownhtmlNo
slugStringAdd a short text summary to the end of the post URLDynamically generated if enabled on the blogNo

Text Posts

ParameterTypeDescriptionDefaultRequired?
titleStringThe optional title of the post, HTML entities must be escapedNoneNo
bodyStringThe full post body, HTML allowedNoneYes

Photo Posts

ParameterTypeDescriptionDefaultRequired?
captionStringThe user-supplied caption, HTML allowedNoneNo
linkStringThe "click-through URL" for the photoNoneNo
sourceStringThe photo source URLNoneYes, 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)NoneYes, either source or data

Quote Posts

ParameterTypeDescriptionDefaultRequired?
quoteStringThe full text of the quote, HTML entities must be escpaedNoneYes
sourceStringCited source, HTML allowedNoneNo
ParameterTypeDescriptionDefaultRequired?
titleStringThe title of the page the link points to, HTML entities should be escapedNoneNo
urlStringThe linkNoneYes
descriptionStringA user-supplied description, HTML allowedNoneNo

Chat Posts

ParameterTypeDescriptionDefaultRequired?
titleStringThe title of the chatNoneNo
conversationStringThe text of the conversation/chat, with dialogue labels (no HTML)NoneYes

Audio Posts

ParameterTypeDescriptionDefaultRequired?
captionStringThe user-supplied captionNoneNo
external_urlStringThe URL of the site that hosts the audio file (not tumblr)NoneYes, either external_url or data
data String
(URL-encoded binary contents)
Limit: 10 MB
An audio fileNoneYes, either external_url or data

Video Posts

ParameterTypeDescriptionDefaultRequired?
captionStringThe user-supplied captionNoneNo
embedStringHTML embed code for the videoNoneYes, either embed or data
data String
(URL-encoded binary contents)
Limit: 100 MB
A video fileNoneYes, either embed or data

Responses

Returns 201: Created or an error code.

/post/edit – Edit a Blog Post

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/post/editPOSTOAuth

Request Parameters

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

ParameterTypeDescriptionDefaultRequired?
idNumberThe ID of the post to editNoneYes

Responses

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

/post/reblog – Reblog a Post

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/post/reblogPOSTOAuth

Request Parameters

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

ParameterTypeDescriptionDefaultRequired?
idNumberThe ID of the reblogged post on tumblelogNoneYes
reblog_keyNumberThe reblog key for the reblogged post – get the reblog key with a /posts requestNoneYes
commentStringA comment added to the reblogged postNoneNo

Responses

Returns 201: Created or an error code.

/post/delete – Delete a Post

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/blog/{base-hostname}/post/deletePOSTOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
idNumberThe ID of the post to deleteNoneYes

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

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/infoGETOAuth

Responses

Response FieldTypeDescription
followingNumberThe number of blogs the user is following
default_post_formatStringThe default posting format - html, markdown or raw
nameStringThe user's tumblr short name
likesNumberThe total count of the user's likes
blogsArray 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

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/dashboardGETOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
limitNumberThe number of results to return: 1–20, inclusive20No
offsetNumberPost number to start at0 (first post)No
typeString The type of post to return. Specify one of the following:  text, photo, quote, link, chat, audio, video, answerNone – return all typesNo
since_idNumber 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.
0No
reblog_infoBoolean Indicates whether to return reblog information (specify true or false). Returns the various reblogged_ fields. FalseNo
notes_infoBoolean Indicates whether to return notes information (specify true or false). Returns note count and note metadata. FalseNo

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

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/likesGETOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
limitNumberThe number of results to return: 1–20, inclusive20No
offsetNumberLiked post number to start at0 (first post)No

Responses

Response FieldTypeDescription
liked_postsArrayAn array of post objects (posts liked by the user)
liked_countNumberTotal 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

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/followingGETOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
limitNumberThe number of results to return: 1–20, inclusive20No
offsetNumberResult number to start at0 (first followee)No

Responses

These fields are wrapped in a blog object:

Response FieldTypeDescription
total_blogsNumberThe number of blogs the user is following
blogsArray 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
  • title – string: the title of the blog
  • description – string: the description of the blog

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
       "total_blogs": 259,
       "blogs": [
          {
             "name": "david",
             "url": "http:\/\/www.davidslog.com",
             "updated": 1308781073"title": "David’s Log""description": "“Mr. Karp is tall and skinny, with unflinching blue eyes and a mop of brown hair. He speaks incredibly fast and in complete paragraphs.” – NY Observer"
          },
          {
             "name": "matthew",
             "url": "http:\/\/matthew.tumblr.com",
             "updated": 1306436424"title": "Matt Hackett""description": " I obsess over the engineering and dissemination of technology for creative people. 

\nI'm happily torn between work on the visible (marketing) and the invisible (architecture, management) components of media-product-making machinery.\n

\nMost recently, I saw as Tumblr's team grew from 10 to 110 and monthly audience from 25 million to 150 million from my vantage point as VP Engineering and later Head of Brand Strategy.

\nMore about Matt Hackett"
}, ... ] } }

/user/follow – Follow a blog

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/followPOSTOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
urlStringThe URL of the blog to followNoneYes

Responses

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

/user/unfollow – Unfollow a blog

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/unfollowPOSTOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
urlStringThe URL of the blog to unfollowNoneYes

Responses

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

/user/like – Like a Post

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/likePOSTOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
idNumberThe ID of the post to likeNoneYes
reblog_keyStringThe reblog key for the post idNoneYes

Responses

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

/user/unlike – Unlike a Post

Method

URIHTTP MethodAuthentication
api.tumblr.com/v2/user/unlikePOSTOAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
idNumberThe ID of the post to unlikeNoneYes
reblog_keyStringThe reblog key for the post idNoneYes

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

URIHTTP MethodAuthentication
api.tumblr.com/v2/taggedGETAPI Key or OAuth

Request Parameters

ParameterTypeDescriptionDefaultRequired?
tagStringThe tag on the posts you'd like to retrieveNoneYes
beforeIntegerThe 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 timestampNo
limitNumberThe number of results to return: 1–20, inclusive20No
filterString 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.

Texto
Fotografia
Citação
Link
Diálogo
Áudio
Vídeo