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. Drop a line in the GitHub Issues if you have ideas for what could be better, or want to discuss all the amazing things you're going to build with it. Follow our Engineering Blog for important news and announcements. Please use the API responsibly and read the Application Developer and API License Agreement. If you run into problems with the Tumblr API, please use our official support form to request help. Enjoy!

Tumblr also supports an API that delivers content according to the oEmbed standard. Our oEmbed API endpoint is https://www.tumblr.com/oembed, which supports post URLs in the format https://*.tumblr.com/post/*.

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

Table of Contents

• What You Need
• Console
• API Overview
  • URI Structure
  • Request User Agent
  • Request Content Types
  • Post Identifiers
  • Blog Identifiers
  • Response Format
  • Rate Limits
  • Reporting Issues
  • About the API Documentation
• Official Tumblr API Client Libraries
• Authentication
• OAuth1 Authorization
  • Temporary Credentials Endpoint
  • Resource Owner Authorization Endpoint
  • Access Token Endpoint
• OAuth2 Authorization
  • /oauth2/authorize - Authorization Request
  • /v2/oauth2/token - Authorization Code Grant Request
  • /v2/oauth2/token - Refresh Token Grant Request
  • /v2/oauth2/exchange - OAuth1 to OAuth2 Token Exchange
• Common Response Elements
  • Links
  • Tag Objects
  • Neue Post Format objects
• Blog Methods
  • /info - Retrieve Blog Info
  • /avatar — Retrieve a Blog Avatar
  • /blocks – Retrieve Blog's Blocks
  • /blocks – Block a Blog
  • /blocks/bulk – Block a list of Blogs
  • /blocks – Remove a Block
  • /likes — Retrieve Blog's Likes
  • /following — Retrieve Blog's following
  • /followers — Retrieve a Blog's Followers
  • /followed_by — Check If Followed By Blog
  • /posts – Retrieve Published Posts
  • /posts/queue — Retrieve Queued Posts
  • /posts/queue/reorder — Reorder Queued Posts
  • /posts/queue/shuffle — Shuffle Queued Posts
  • /posts/draft — Retrieve Draft Posts
  • /posts/submission — Retrieve Submission Posts
  • /notifications — Retrieve Blog's Activity Feed
  • /post — Create a New Blog Post (Legacy)
  • /post/edit – Edit a Blog Post (Legacy)
  • /post/reblog – Reblog a Post (Legacy)
  • /posts - Create/Reblog a Post (Neue Post Format)
  • /posts/{post-id} - Fetching a Post (Neue Post Format)
  • /posts/{post-id} - Editing a Post (Neue Post Format)
  • /post/delete – Delete a Post
  • /posts/{post-id}/mute - Muting a Post's Notifications
  • /notes - Get notes for a specific Post
• User Methods
  • /user/info – Get a User's Information
  • /user/limits – Get a User's Limits
  • /user/dashboard – Retrieve a User's Dashboard
  • /user/likes — Retrieve a User's Likes
  • /user/following – Retrieve the Blogs a User Is Following
  • /user/follow – Follow a blog
  • /user/unfollow – Unfollow a blog
  • /user/like – Like a Post
  • /user/unlike – Unlike a Post
  • /user/filtered_tags - Tag Filtering
  • /user/filtered_content - Content Filtering
• Tagged Method
  • /tagged – Get Posts with Tag
• Communities Methods
  • GET /v2/communities - List joined communities
  • GET /v2/communities/{community-handle} - Get info about a community
  • PUT /v2/communities/{community-handle} - Edit your community
  • GET /v2/communities/{community-handle}/timeline - Get posts from a community
  • GET /v2/communities/{community-handle}/members - Get community members
  • PUT /v2/communities/{community-handle}/members - Join a community
  • DELETE /v2/communities/{community-handle}/members/{blog-identifier} - Remove a member
  • PUT /v2/communities/{community-handle}/members/{blog-identifier} - Change a member's role
  • PUT /v2/communities/{community-handle}/invitations - Invite someone to the community
  • GET /v2/communities/{community-handle}/invitations - View pending invites
  • GET /v2/communities/{community-handle}/invitations/{blog-identifier} - Check invitation status
  • DELETE /v2/communities/{community-handle}/invitations/{blog-identifier} - Cancel an invitation
  • POST /v2/communities/{community-handle}/invite_hash - Regenerate the invite URL
  • PUT /v2/communities/{community-handle}/posts/{post-id}/reactions - Add reaction to post
  • DELETE /v2/communities/{community-handle}/posts/{post-id}/reactions/{reaction-id} - Remove reaction from post
  • PUT /v2/communities/{community-handle}/mute - Mute a community
  • DELETE /v2/communities/{community-handle}/mute - Unmute a community

What You Need

To get an OAuth key you must 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 our developer API console to test calls and see live examples of using our official clients.

API Overview

Before you dive in, review these essentials.

URI Structure

All Tumblr API requests start with https://api.tumblr.com.

The next segment of the URI path depends on the type of request you want to make. For example, getting blog data or to make a post on a blog uses the /v2/blog/{blog-identifier}/... endpoint, so the full URL would be https://api.tumblr.com/v2/blog/{blog-identifier}/...

See the different Methods sections below for complete details on the available routes.

Request User Agent

The User-Agent header is required and every application is expected to use a consistent value across requests. Your application may be suspended if it uses a variety of values for the User-Agent header.

Request Content Types

Unless otherwise noted, Tumblr API endpoints that accept body parameters expect the body parameters to be encoded using one of the following content types:

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

Note that the Content-Type header must be set accordingly, and the absence of a Content-Type header may result in unexpected behavior.

Post Identifiers

Please note that Tumblr's Post IDs are 64-bit integers. Some languages, like Javascript, don't handle 64-bit numbers very well. With that in mind, there is also an id_string field available so you can handle these safely.

Blog Identifiers

Each blog has a few different unique identifiers that can be used to reference that specific blog in the API payload. They are interchangeable and can be used in any place that {blog-identifier} appears in these API docs. The three types of blog identifiers are:

• Blog name: The name of the blog that appears in the URL. Examples:
  • staff for https://staff.tumblr.com/
  • changes for https://www.tumblr.com/changes or https://www.tumblr.com/@changes
• Hostname: The hostname that's used to access the blog, excluding www.tumblr.com. Examples:
  • staff.tumblr.com for https://staff.tumblr.com/
  • changes.tumblr.com for https://www.tumblr.com/changes (not www.tumblr.com)
  • www.davidslog.com for https://www.davidslog.com/
• Universally unique identifier: The UUID of the blog retrieved from the API. Examples:
  • t:0aY0xL2Fi1OFJg4YxpmegQ for staff, staff.tumblr.com, and even t:0aY0xL2Fi1OFJg4YxpmegQ
  • t:WX5xItRbCiJH_GJDsIdhAQ for changes, changes.tumblr.com, and even t:WX5xItRbCiJH_GJDsIdhAQ

Blog Unique Hostnames

Each blog has a unique hostname which can be used as its identifier. The hostname can be standard or custom.

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

Blog Unique Identifiers

Each blog also has a unique identifier that you can retrieve from any API response that includes a blog, in the uuid field (example: t:0aY0xL2Fi1OFJg4YxpmegQ). The {blog-identifier} placeholder can also be replaced by this unique identifier.

The benefits of using a unique identifier instead of a blog name or hostname are that the unique identifier will not change if the blog name or custom domain changes. It can be used as a stable, persistent identifier for a blog.

However, note that under exceptional circumstances, a unique identifier can change. Your own blog's unique identifier will only be changed with your knowing.

Response Format

Unless otherwise noted, the API returns JSON-encoded objects (Content-Type: application/json) and every response body includes these standard properties:

The meta object should always contain:

Even 4xx/5xx responses such as 400 Bad Request or 500 Internal Server Error should include this information, and the response may include more information about why you received the 4xx response.

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.

Rate Limits

Usage of the Tumblr API is rate limited in a few ways, but we respond with a 429 Limit Exceeded response whenever a consumer hits one of these limits. There is a global rate limit for all usage of the API per consumer, as well as a few per-feature rate limits, such as how many posts you can make per day. The error message or headers you receive with the 429 Limit Exceeded response should indicate what limit you've hit.

These rate limits include:

• 300 API calls per minute, per IP address.
• 18,000 API calls per hour, per IP address.
• 432,000 API calls per day, per IP address.
• 1,000 API calls per hour, per consumer key.
• 5,000 API calls per day, per consumer key.
• 250 new published posts (including reblogs) per day, per user.
• 250 images uploaded per day, per user.
• 200 follows per day, per user.
• 1,000 likes per day, per user.
• 10 new blogs per day, per user.
• 20 videos uploaded per day, per user.
• 60 minutes of total video uploaded per day, per user.

Note that these rate limits are based on the Tumblr servers' internal clocks and that the daily limits are per calendar day.

There are also overall limits to a few specific actions, including:

• A blog can only follow 5,000 other blogs at a time.
• A blog can only have 1,000 queued posts at a time.
• You can only filter up to 1,000 tags at a time.

Reporting Issues

If you run into problems with the Tumblr API, please use our official support form to request help.

About the API Documentation

These 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

Official Tumblr API Client Libraries

Here is a list of official API client which will help you get up and running with your favorite language in no time.

• Javascript
• Ruby
• PHP
• Java
• Python
• Objective-C
• Go

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 below includes a note about the authentication level.

OAuth1 Authorization

The API supports the OAuth 1.0a Protocol, accepting parameters via the Authorization header, with the HMAC-SHA1 signature method only.

Temporary Credentials Endpoint

This route is used to create a temporary oauth1 token to be used for oauth1 authorization. See https://tools.ietf.org/html/rfc5849#section-2.1 for further information.

Method

Request Parameters

None.

Response

Returns 200 OK or an error code. The response body parameters are url encoded (Content-Type: application/x-www-form-urlencoded), and the standard response properties are omitted.

Resource Owner Authorization Endpoint

After retrieving temporary credentials, redirect the user to this endpoint so they can authorize your app. See https://tools.ietf.org/html/rfc5849#section-2.2 for further information.

Method

Request Parameters

Include these parameters in the query string when you redirect the user.

Response

Upon successful authorization, the user is redirected to your callback url with the following parameters in the query string:

• oauth_token - The access token retrieved from the temporary credentials request
• oauth_verifier - The token required to retrieve an access token
• source - The optional identifier that indicates where the process started

Access Token Endpoint

The endpoint that is used to exchange an oauth_verifier token for an access token and secret for the user. See https://tools.ietf.org/html/rfc5849#section-2.3 for further information.

Method

Request Parameters

Response

Returns 200 OK or an error code. The response body parameters are url encoded (Content-Type: application/x-www-form-urlencoded), and the standard response properties are omitted.

OAuth2 Authorization

The API supports the OAuth 2.0 Protocol, accepting a bearer token via the Authorization header like so:

Authorization: Bearer {access_token}

API clients have access to Authorization Code, Client Credentials, and Refresh Token grants. Available scopes include basic, write, and offline_access. Note that you must specify a valid OAuth2 redirect URL for OAuth2 to be available to your application. You can find this field by editing one of your applications.

The OAuth2 Authorization flow

Step One: Redirect a user to Tumblr

Redirect the user to Tumblr's OAuth2 authorization endpoint. This will prompt the user to allow your application to access the Tumblr API on their behalf.

Step Two: Handle the callback request

Once a user decides to allow or disallow your application access to their account, Tumblr will redirect them to the OAuth2 redirect URL that you set when creating your application. If there was an error processing the request, the URL will contain an error query parameter. If the request was successful, the URL will contain code and state query parameters. You must verify the state value has the same value that you included when you redirected the user to Tumblr's OAuth2 authorization endpoint, and the code value can be used to retrieve an access token for the user.

Step Three: Retrieve an access token

Use your applications credentials and the code from the previous step to issue a request to Tumblr's OAuth2 access token endpoint. For example, using the curl command line tool:

curl -F grant_type=authorization_code -F code={code} -F client_id={Your OAuth consumer key} -F client_secret={Your OAuth secret key} https://api.tumblr.com/v2/oauth2/token

If you provided a redirect URI in the initial authorization request, you must provide the same redirect URI in the token request (as redirect_uri).

A successful request will yield a response that contains the following object:

{
    "access_token": "{access_token}",
    "expires_in": 2520,
    "id_token": false,
    "refresh_token": "{refresh_token}",
    "scope": "write offline_access",
    "token_type": "bearer"
}

Special tip: jq is a handy tool for formatting JSON on the command line, you can pipe the output of curl through jq to easily format the API response, like so:

curl -F ... https://api.tumblr.com/v2/oauth2/token | jq

You'll need to store this information somewhere so you can issue requests on behalf of the user, and so you can refresh the access token when it has expired.

Step Four: Make your API requests

Using the access_token, you can now talk directly to the Tumblr API. For example, this curl request will retrieve the user's account information:

curl -H 'Authorization: Bearer {access_token}' https://api.tumblr.com/v2/user/info

Step Five: Refresh an access token

Your application can use the expires_in property in the access token response to determine if the user's access token has expired. If it has, you can use the refresh token to retrieve a new access token and refresh token. For example, using curl again:

curl -F grant_type=refresh_token -F refresh_token={refresh_token} -F client_id={Your OAuth consumer key} -F client_secret={Your OAuth consumer secret} https://api.tumblr.com/v2/oauth2/token

/oauth2/authorize - Authorization Request

This request is used to request permission from a user to gain access to their account. Once a user grants your application access, they will be returned to your OAuth2 redirect Url as defined on your OAuth Application.

Method

Request Parameters

A redirect URI must be supplied when multiple redirect URIs are registered.

/v2/oauth2/token - Authorization Code Grant Request

This request allows you to exchange an authorization code for an access token.

Method

Request Parameters

Response

• 200 Operation was successful
• 401 Unauthorized

/v2/oauth2/token - Refresh Token Grant Request

This request is used to exchange an OAuth2 refresh token for a new OAuth2 access token and refresh token.

Method

Request Parameters

Example:

{
    "grant_type": "refresh_token",
    "client_id": "...",
    "refresh_token": "{refresh_token goes here}"
}

Response

• 200 Operation was successful
• 401 Unauthorized, refresh token has expired

/v2/oauth2/exchange - OAuth1 to OAuth2 Token Exchange

This route is used to exchange an OAuth1 access token for an OAuth2 access token and refresh token. Clients must expect the OAuth1 token to be invalidated if the exchange is successful.

Method

Request Parameters

None.

Response

• 200 Operation was successful
• 400 Incorrect authorization type (requests must use OAuth1)
• 401 Authentication failed

Common Response Elements

Beyond the overall response format described above, there are some elements that are common throughout the API responses.

Links

Links describe an in-app or navigation behavior. A response may contain one or more of these contained under the _links response object key.

An object in the _links hash will always contain type and href keys.

A _links object may be of type navigation or action.

• navigation: A reference to some external URI to which the user can go.
• action: A reference to some internal client state change in the application. The most common example would be to open a different view.

A navigation link will only contain a href to which the user should be directed. An action type link will contain details on what request method as well as what query or body parameters should be used to take the action.

Example:

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "_links": {
         "previous": {
            "type": "action",
            "method": "GET",
            "href": "https://api.tumblr.com/v2/endpoint",
            "query_params": {
               "page": 1,
            }
         },
         "next": {
            "type": "action",
            "method": "GET",
            "href": "https://api.tumblr.com/v2/endpoint",
            "query_params": {
               "page": 3,
            }
         },
         "terms_of_service": {
            "type": "navigation",
            "href": "https://www.tumblr.com/policy/terms-of-service",
         },
         ...
      }
   }
}

Tag Objects

A tag object represents a tag, and could have these fields:

Neue Post Format objects

Some routes will return Posts that have type: blocks and/or is_blocks_post_format: true, which means their content is available in the Neue Post Format. See the NPF specification docs for more info!

Also, when making any request to our API that returns Posts, you may supply a npf=true query parameter to specify that you'd like all of the Posts' content returned in the Neue Post Format rather than the legacy format.

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

• https://api.tumblr.com/v2/blog/scipsy.tumblr.com/info
• https://api.tumblr.com/v2/blog/good.tumblr.com/info

Method

Request Path Parameters

Query Parameters

Partial Responses

Note that blog objects via the Tumblr API support "partial responses", which allows the request to specify which fields are returned any time a blog object is present by using the fields query parameter.

For example, if you would like to always only see the name and updated fields in blog objects:

https://api.tumblr.com/v2/blog/david/info?fields[blogs]=name,updated

That will return only the name and updated fields in the blog object. You can use this in any API request that includes blog objects, not just this blog info endpoint. Some fields are also "optional", and are preceded in the list by a ? (encoded to %3F).

Those optional fields are only available upon request, such as:

To access these, specify them in the fields[blogs] query parameter list, like so:

https://api.tumblr.com/v2/blog/david/info?fields[blogs]=name,updated,%3Fis_following_you,%3Fduration_following_blog

Which will return a response like:

{
    "meta": {
        "status": 200,
        "msg": "OK"
    },
    "response": {
        "blog": {
            "name": "david",
            "updated": 1591035760,
            "is_following_you": false,
            "duration_following_blog": 123456
        }
    }
}

Omitting the fields query parameter will return the default set of fields below.

Response

Note: Field ordering below may differ from actual response. Also, any fields present that aren't included here are not officially supported for third-party use.

Specific fields inside of the theme object and what they mean:

Example

https://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": "https:\/\/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

• https://api.tumblr.com/v2/blog/david.tumblr.com/avatar/512
• https://api.tumblr.com/v2/blog/david.tumblr.com/avatar

Method

Request Path Parameters

Response

Requests that are not signed using OAuth1 will receive the requested avatar in PNG format, while requests that are signed will receive a response of the following form:

/blocks – Retrieve Blog's Blocks

Get the blogs that the requested blog is currently blocking. The requesting user must be an admin of the blog to retrieve this list.

Note that this endpoint is rate limited to 60 requests per minute.

Method

Request Path Parameters

Query Parameters

Response

Returns 200 OK or an error code.

Example response:

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blocked_tumblelogs": [
         {
            "name": "joe",
            "url": "http:\/\/www.spammyjoe.com",
            "updated": 1308797076,
            "title": "Spammy Joe",
            "description": "Posting things you don't really care for"
         },
         {
            "name": "harry",
            "url": "harryblog19.tumblr.com",
            "updated": 1808841333,
            "title": "The 19th Harry Blog",
            "description": ""
         },
         ...
      ],
      "_links": {
         "next": {
            "href": "/v2/blog/andysblog.tumblr.com/blocks?offset=20",
            "method": "GET",
            "query_params": {
               "offset": 20
            }
         }
      }
   }
}

/blocks – Block a Blog

Note that this endpoint is rate limited to 60 requests per minute.

Method

Request Path Parameters

Request Parameters

Response

Returns 201 Created or an error code.

/blocks/bulk – Block a list of Blogs

Note that this endpoint is rate limited to 60 requests per minute.

Method

Request Path Parameters

Request Parameters

Response

Returns 200 OK or an error code.

/blocks – Remove a Block

Note that this endpoint is rate limited to 60 requests per minute.

Method

Request Path Parameters

Request Parameters

• If you pass both params, anonymous_only is going to be ignored.
• Passing just anonymous_only=false is the equivalent of no params. A 404 response will be returned.

Response

Returns 200 OK if the block on the passed blocked_tumblelog parameter was successfully removed.

Returns 200 OK if all anonymous blocks were successfully removed when anonymous_only=true was passed without a blocked_tumblelog parameter in the path.

/likes — Retrieve Blog's Likes

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

Method

Request Path Parameters

Query Parameters

Notes

• You can only provide either before, after, or offset. If you provide more than one of these options together you will get an error.
• You can still use limit with any of those three options to limit your result set.
• When using the offset parameter the maximum limit on the offset is 1000. If you would like to get more results than that use either before or after.

Response

/following — Retrieve Blog's following

This method can be used to retrieve the publicly exposed list of blogs that a blog follows, in order from most recently-followed to first.

Method

Request Path Parameters

Query Parameters

Response

/followers — Retrieve a Blog's Followers

Method

Request Path Parameters

Query Parameters

Response

These fields are wrapped in a users object:

Example

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

/followed_by — Check If Followed By Blog

This method can be used to check if one of your blogs is followed by another blog.

Method

Request Path Parameters

Query Parameters

Example usage:

GET https://api.tumblr.com/v2/blog/YOUR-BLOG.tumblr.com/followed_by?query=staff

Response

/posts – Retrieve Published Posts

Examples

• https://api.tumblr.com/v2/blog/peacecorps.tumblr.com/posts/text?notes_info=true
• https://api.tumblr.com/v2/blog/pitchersandpoets.tumblr.com/posts/photo?tag=new+york+yankees
• https://api.tumblr.com/v2/blog/staff.tumblr.com/posts?before=1496289599

Method

Request Path Parameters

Query Parameters

By default, the list of posts on a blog is in reverse-chronological order, using the user-set publish time which allows backdating. Note that you cannot use before and offset in the same request; before is best used for paginating through posts. Also, using after is best used with sort set to asc.

Note that tag can either be a string or an array of strings:

Fetch posts using this one tag:
/v2/blog/{blog-identifier}/posts?tag=something
 or fetch posts using all of these tags:
/v2/blog/{blog-identifier}/posts?tag[0]=something&tag[1]=example

When given an array of tags, posts will be returned that have all of the provided tags (so in that example, posts with both "something" and "example" used on them). Also, a maximum of four tags can be provided for this use.

Response

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.

Important note: Post content can be in two formats: legacy or Neue Post Format (NPF). By default, posts returned from this endpoint (and any other endpoint that returns posts) will be in the legacy post-type-based content formats described below. NPF-created posts from the official Tumblr mobile apps will be returned as text/regular posts to maintain backwards compatibility. Note that this "backwards compatibility" from NPF to HTML is best effort. To help transition to an NPF-only world, you can pass along the npf=true query parameter to force all posts returned here to be in Neue Post Format (also described below). Eventually, all posts will be NPF, so we strongly encourage leveraging NPF JSON via npf=true for post content when consuming posts via the API.

Fields available for all Post types:

† The "genesis" ID for a post is only available and different than its current ID if that post had been drafted, queued, or scheduled, and is now published. In which case, the "genesis" ID will be the original post ID generated when drafting, queuing, or scheduling that post. You cannot use this ID to look up the post after it has been published, but it can be useful for tracking a post from its pre- to post-published state.

If muted: true and mute_end_timestamp: 0, then the post is muted forever. Otherwise, mute_end_timestamp is a unix timestamp of when the mute will end. If muted: false, then mute_end_timestamp will be 0, but doesn't matter since the post is not muted.

Fields available for posts from a community:

Reactions have a specific object for each reaction in the array:

Neue Post Format (NPF) Posts

Posts that have type: blocks and/or is_blocks_post_format: true will have three fields for the post's content:

The specification for what objects you can find in these fields is documented here.

Legacy Text Posts

Example

https://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,
            "id_string": "3507845453",
            "post_url": "https:\/\/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=\"https:\/\/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=\"https:\/\/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=\"https:\/\
               /twitter.com\/ngun\" target=\"_blank\">@ngun<\/a> I'm on
               twitter as well <a href=\"https:\/\/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
   }
}

Legacy Photo Posts

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

Example

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

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "blog": { ... },
      "posts": [
         {
            "blog_name": "derekg",
            "id": 7431599279,
            "id_string": "7431599279",
            "post_url": "https:\/\/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": "https:\/\/derekg.org\/photo\/1280\/7431599279\/1\/
                           tumblr_lo36wbWqqq1qanqww"
                     },
                     {
                        "width": 500,
                        "height": 282,
                        "url": "https:\/\/30.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_500.jpg"
                     },
                     {
                        "width": 400,
                        "height": 225,
                        "url": "https:\/\/29.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_400.jpg"
                     },
                     {
                        "width": 250,
                        "height": 141,
                        "url": "https:\/\/26.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_250.jpg"
                     },
                     {
                        "width": 100,
                        "height": 56,
                        "url": "https:\/\/24.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_100.jpg"
                     },
                     {
                        "width": 75,
                        "height": 75,
                        "url": "https:\/\/30.media.tumblr.com\/
                           tumblr_lo36wbWqqq1qanqwwo1_75sq.jpg"
                     }
                  ]
               }
            ]
         }
      ],
      "total_posts": 1
   }
}

Legacy Quote Posts

Example

https://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,
            "id_string": "4742980381",
            "post_url": "https:\/\/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
   }
}

Legacy Link Posts

Example

https://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,
            "id_string": "688472164",
            "post_url": "https:\/\/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": "https:\/\/blog.estadiezijn.nl\/post\/
               459075181\/faq-how-do-you-make-those-marker-doodles",
            "link_author": "Ester Aarts",
            "excerpt": "How I make marker doodles",
            "publisher": "blog.estadiezijn.nl",
            "photos": [
               {
                  "caption": "",
                  "original_size":
                     {
                        "width": 500,
                        "height": 500,
                        "url": "https:\/\/40.media.tumblr.com
                        \/1393850e5c331da2e3c9fb478a30310d
                        \/tumblr_inline_nm3lwntw8k1rplry2_500.jpg"
                     },
                  "alt_sizes": []
               }
            ],
            "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
   }
}

Legacy Chat Posts

Example

https://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,
            "id_string": "5845345725",
            "post_url": "https:\/\/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: https://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": "https://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
   }
}

Legacy Audio Posts

Example

https://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,
            "id_string": "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>",
            "embed": "<iframe class=\"tumblr_audio_player tumblr_audio_player_5578378101\" src=\"http:\/\/derekg.org\/post\/5578378101/otis-redding/audio_player_iframe" frameborder=\"0\" allowtransparency=\"true\" scrolling=\"no\" width=\"540\" height=\"85\"></iframe>",
            "plays": 1576
         }
      ],
      "total_posts": 1
   }
}

Legacy Video Posts

Example

https://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,
            "id_string": "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=\"https:\/\/foreverneilyoung.tumblr.com\/
               post\/6522738445\" target=\"_blank\">foreverneilyoung<\/a>:
               <\/p>\n<blockquote>\n<p><a href=\"https:\/\/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
   }
}

Legacy Answer Posts

Example

https://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,
            "id_string": "7504154594",
            "post_url": "https://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": "https://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

Gives you a list of the currently queued posts for the specified blog.

Method

Request Path Parameters

Query Parameters

/posts/queue/reorder — Reorder Queued Posts

This allows you to reorder a post within the queue, moving it after an existing queued post, or to the top.

Method

Request Path Parameters

Request Body Parameters

/posts/queue/shuffle - Shuffle Queued Posts

This randomly shuffles the queue for the specified blog.

Method

Request Path Parameters

/posts/draft — Retrieve Draft Posts

Method

Request Path Parameters

Request Parameters

/posts/submission — Retrieve Submission Posts

Method

Request Path Parameters

Request Parameters

Response

/notifications — Retrieve Blog's Activity Feed

Retrieve the activity items for a specific blog, in reverse chronological order.

Method

Request Path Parameters

Query Parameters

Available "types" include:

Response

Note that different activity item objects vary field schema by activity item type. Some common fields include:

• id -- The ID of the activity item.
• type -- The type of activity item, from the list above.
• timestamp -- A unix epoch timestamp of when the event happened.
• unread -- A boolean indicating whether this is new/unread as of the last activity read time.
• target_post_id -- If the activity has to do with one of your blog's posts, this will be its ID.
• from_tumblelog_name -- If the activity is coming from another blog, like a Like or Reblog, this will be its name.
• post_id -- For activity like Reblogs and Replies, this will be the relevant post's ID.
• post_tags -- An array of used in the reblog, if any.
• added_text -- For reblogs with comment, this will be a summary of the added content.
• reply_text -- For replies, this will be the text of the reply.

/post — Create a New Blog Post (Legacy)

These legacy posting flows are still available, but we encourage you to use the Neue Post Format creation route.

Method

Request Path Parameters

Request Parameters

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

Fields available for all Post types:

Text Posts

Photo Posts

Quote Posts

Link Posts

Chat Posts

Audio Posts

Video Posts

Response

Returns 201: Created or an error code.

/post/edit – Edit a Blog Post (Legacy)

Method

Request Path Parameters

Request Parameters

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

Response

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

/post/reblog – Reblog a Post (Legacy)

Method

Request Path Parameters

Request Parameters

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

Response

Returns 201: Created or an error code.

/posts - Create/Reblog a Post (Neue Post Format)

This route allows you to create posts (and reblogs) using the Neue Post Format. The specification for NPF is here.

Note about Post States

Posts can be in the following "states" as indicated in requests to the post creation/editing endpoints:

• "published" means the post should be publicly published immediately.
• "queue" means the post should be added to the end of the blog's post queue.
• "draft" means the post should be saved as a draft.
• "private" means the post should be privately published immediately.
• "unapproved" means the post is a new submission.

If omitted, the state parameter on a new post defaults to "published".

Method

Request Path Parameters

Request Parameters

If the post being created is a reblog, all of the above parameters are expected, along with:

Note that when making a reblog, the trail from the post you're reblogging is not required, and will be ignored if given. Any content you provide when making a reblog will be added at the end of the reblog trail, in your post.

User Uploaded Media

In order to support user uploaded media (photos, videos, etc.), the creation and edit routes also support a multi-part form request where the first part contains the JSON body and subsequent parts contain media data. The Content-Type: multipart/form-data header must be used in this case.

To specify which media data pertains to which block, we use a unique identifier in the JSON body and this identifier is used as the key in the form data.

{
    "content": [
        {
            "type": "image",
            "media": [
                {
                    "type": "image/jpeg",
                    "identifier": "some-identifier",
                    "width": 250,
                    "height": 200
                }
            ]
        }
    ]
}

--TumblrBoundary
Content-Disposition: form-data; name="json"
Content-Type: application/json

{JSON encoded parameters}
--TumblrBoundary
Content-Disposition: form-data; name="some-identifier"; filename="filename.jpg"
Content-Type: image/jpeg

{image data}
--TumblrBoundary--

Uploading a video for a video content block follows the same identifier pattern as above:

{
    "content": [
        {
            "type": "video",
            "media": {
                "type": "video/mp4",
                "identifier": "some-identifier",
                "width": 250,
                "height": 200
            }
        }
    ]
}

Normally we would require a provider field inside the video block, but on post creation this is assumed to be tumblr if none is provided.

Response

This returns a 201 Created on successful post creation, or an error code. The response JSON object will contain the id of the created post, which is intentionally a string instead of an integer for 32bit device compatibility.

Example response:

{
    "meta": {
        "msg": "Created",
        "status": 201
    },
    "response": {
        "id": "1234567891234567"
    }
}

Errors and Error Subcodes

The error codes here are the HTTP statuses that'll be returned in error states, the error subcodes are the specific subcodes also returned in some situations. The response should have an errors array at the top level alongside meta, containing what error(s) occurred.

• 400 Bad Request when the request has not provided the required data.
  • 400.8001 when an NPF JSON parameter is invalid or a bad format.
  • 400.8002 when the reblog parent post and/or blog is invalid or cannot be found or cannot be interacted with.
  • 400.8005 when the uploaded media is an invalid format we cannot accept.
  • 400.8016 when there is something invalid about the format of the answer content or layout.
• 401 Unauthorized when the requester is an unauthorized client.
• 403 Forbidden when the requester is not allowed to reblog the parent post they specified.
  • 403.8004 when the requesting user cannot upload more media today.
  • 403.8008 when trying to upload a video in reblog content, which is not allowed.
  • 403.8010 when there is a video upload still transcoding, so you can't upload another video yet.
  • 403.8011 when the requesting user cannot upload more videos today.
  • 403.8022 when the blog's queue limit has been reached.
  • 403.8023 when the blog's daily posting limit has been reached.
• 404 Not Found when the request is not HTTPS.
• 404 Not Found when the Tumblelog identifier in the path does not resolve to an existing blog.
• 404 Not Found when the given post ID for editing/fetching doesn't exist.
• 500 Internal Server Error when something has gone very wrong.
  • 500.8006 when there was an unknown upload error (not video related).
  • 500.8009 when there was an unknown upload error (video related).
• 503 Service Unavailable when all posting, or posting via the API, is disabled.

For example:

{
    "meta": {
        "msg": "Bad Request",
        "status": 400
    },
    "errors": [
        {
            "title": "'content' must be an array'",
            "code": 8001
        }
    ]
}

/posts/{post-id} - Fetching a Post (Neue Post Format)

This route can fetch a post, either legacy or NPF, and return it in either in the legacy or NPF format. The specification for NPF is here. Note that NPF to legacy conversion is not valid yet, so the available conversions are: NPF -> NPF, legacy -> legacy, and legacy -> NPF.

The intention of this route is to fetch a post for editing in either the NPF or legacy format.

Method

Request Path Parameters

Request Parameters

Response

This returns a 200 OK on successful post fetching, or an error code.

The response JSON object will contain:

Note about queued/scheduled posts: the queued_state field will only exist for a state: queued post, and will indicate either queued or scheduled. The scheduled_publish_time field will tell you when the post is currently scheduled for publishing, as a Unix epoch timestamp. These fields are read-only; to change post's state or scheduled publish time, please use the state and publish_on fields when editing the post.

Errors and Error Subcodes

See the notes from the NPF Post creation route for info about this.

/posts/{post-id} - Editing a Post (Neue Post Format)

This route allows you to edit posts using the Neue Post Format. Note that you can only edit posts in NPF if they were originally created in NPF, or are legacy text posts. The specification for NPF is here.

Method

Request Path Parameters

Request Parameters

For editing a post, all of the request parameters from the NPF Post Creation route are expected (depending on if it's an original post or reblog), along with the Post's ID in the query path. If you are editing a scheduled post, make sure to include its publish_on value.

Note that the exclude_trail_items parameter will edit the reblog's current trail at the time of editing, not the trail that existed when the reblog was created. So if you had created a reblog and excluded trail items at creation, then are editing it to exclude trail items again, you are now editing that reblog's trail, not the parent post's trail. Basically: you can't "bring back" trail items without reblogging the parent post all over again.

Response

This returns a 200 OK on successful post editing, or an error code. The response JSON object will contain the post_id of the edited post, which is intentionally a string instead of an integer for 32bit device compatibility.

Example response:

{
    "meta": {
        "msg": "OK",
        "status": 200
    },
    "response": {
        "id": "1234567891234567"
    }
}

Errors and Error Subcodes

See the notes from the NPF Post creation route for info about this.

/post/delete – Delete a Post

Method

Request Path Parameters

Request Parameters

Response

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

/posts/{post-id}/mute – Muting a Post's Notifications

Muting a post's notifications means the author of the post will no longer receive activity items or push notifications about the post, until the post is unmuted, or until the temporary mute expires.

Methods

The POST request mutes the given post, and the DELETE request can unmute a post.

Request Path Parameters

Body Parameters

To make the mute temporary, you can supply how long you want the mute to last.

Giving 0 or omitting mute_length_seconds entirely means the mute will last until the post is unmuted by the author.

Response

Returns 200 OK on successful muting or unmuting, or an error code.

Returns 400 Bad Request if the given mute_length_seconds is less than 0.

/notes - Get notes for a specific Post

Method

Request Path Parameters

Request Parameters

The mode field can be one of a few things, most of which act as filters for the types of notes returned. All return notes in reverse chronological order.

• "all" loads all notes for the post.
• "likes" loads only likes for the post.
• "conversation" loads only replies and reblogs with added text commentary, with the rest of the notes (likes, reblogs without commentary) in a rollup_notes field.
• "rollup" loads only like and reblog notes for the post in the notes array.
• "reblogs_with_tags" loads only the reblog notes for the post, and each note object includes a tags array field (which may be empty).

And different modes can cause the response to contain different things.

Example request:

GET https://api.tumblr.com/v2/blog/YOUR-BLOG.tumblr.com/notes?id=1234567890000&mode=all&before_timestamp=1234567890

Response

Returns 200: OK with an array of notes, along with more info, and a _links object to load more notes.

Example response:

{
    "meta": {
        "status": 200,
        "msg": "OK"
    },
    "response": {
        "notes": [
            {
                "type": "reblog",
                "timestamp": 1595527574,
                "blog_name": "test-blog",
                "blog_uuid": "t:abcd1234",
                "blog_url": "https://test-blog.tumblr.com/",
                "followed": false,
                "avatar_shape": "square",
                "post_id": "1123456688899000",
                "reblog_parent_blog_name": "other-test-blog"
            },
            {
                "type": "like",
                "timestamp": 1595527569,
                "blog_name": "test-blog",
                "blog_uuid": "t:abcd1234",
                "blog_url": "https://test-blog.tumblr.com/",
                "followed": false,
                "avatar_shape": "square"
            }
        ],
        "total_notes": 2
    }
}

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

Response

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": "https://derekg.org/",
                "tweet": "auto",
                "primary": true,
                "followers": 33004929,
            },
            {
                "name": "ihatehipstrz",
                "title": "I Hate Hipstrz",
                ...
            }
        ]
     }
  }
}

/user/limits – Get a User's Limits

Use this method to retrieve information about the various limits for the current user.

Method

Response

Example

{
    "meta": {
        "status": 200,
        "msg": "OK"
    },
    "response": {
        "user": {
            "blogs": {
               "description": "the number of secondary blogs you can create per day",
               "limit": 10,
               "remaining": 4,
               "reset_at": 1670043600
            },
            "follows": {
                "description": "the number of blogs you can follow per day",
                "limit": 200,
                "remaining": 199,
                "reset_at": 1670043600
            },
            ...
        }
    }
}

/user/dashboard – Retrieve a User's Dashboard

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

⚠️ Note: Please don't re-implement the Dashboard, and don't recreate complete Tumblr functions or clients on a platform where Tumblr already has an official client. See our API policies here.

Method

Request Parameters

Response

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.

Important note: Post content can be in two formats: legacy or Neue Post Format (NPF). By default, posts returned from this endpoint (and any other endpoint that returns posts) will be in the legacy post-type-based content formats described here. NPF-created posts from the official Tumblr mobile apps will be returned as text/regular posts to maintain backwards compatibility. To help transition to an NPF-only world, you can pass along the npf=true query parameter to force all posts returned here to be in Neue Post Format (also described here).

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
      "posts": [
         {
            "blog_name": "laughingsquid",
            "id": 6828225215,
            "id_string": "6828225215",
            "post_url": "https:\/\/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

Request Parameters

• You can only provide either before, after, or offset. If you provide more than one of these options together you will get an error.
• You can still use limit with any of those three options to limit your result set.
• When using the offset parameter the maximum limit on the offset is 1000. If you would like to get more results than that use either before or after.

Response

/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

Request Parameters

Response

These fields are wrapped in a blog object:

Example

{
   "meta": {
      "status": 200,
      "msg": "OK"
   },
   "response": {
       "total_blogs": 259,
       "blogs": [
          {
             "name": "david",
             "url": "https:\/\/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": "https:\/\/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

Request Parameters

Response

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

/user/unfollow – Unfollow a blog

Method

Request Parameters

Response

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

/user/like – Like a Post

Method

Request Parameters

Response

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

/user/unlike – Unlike a Post

Method

Request Parameters

Response

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

/user/filtered_tags - Tag Filtering

This endpoint lets you manage the tagged content you'd like covered on your dashboard. See more info about this feature here. Note that this filtering relies on the content being tagged, but also filters tag recommendations and other tag-based content. For filtering the text content of posts, see Content Filtering.

Methods

All of the endpoints require OAuth authentication.

Request Parameters

For adding new tag filters, you can add one at a time or many at once via the POST body:

Example:

POST https://api.tumblr.com/v2/user/filtered_tags
Content-Type: application/json
{ "filtered_tags": [ "something" ] }

POST https://api.tumblr.com/v2/user/filtered_tags
Content-Type: application/json
{ "filtered_tags": [ "something", "technology" ] }

For deleting a tag filter, pass along the tag string in the path:

Example:

DELETE https://api.tumblr.com/v2/user/filtered_tags/tag%20here

That would delete the tag "tag here".

Response

For GET requests, the endpoint will return a 200 OK on success, along with the list of tags:

{
    "meta": {
        "status": 200,
        "msg": "OK"
    },
    "response": {
        "filtered_tags": [
            "technology",
            "something",
            "and something else"
        ]
    }
}

For POST requests, the endpoint will return a 201 Created on success, with an empty response object.

For DELETE requests, the endpoint will return a 200 OK on success, with an empty response object.

Errors

• 400 Bad Request if given an invalid/empty tag to filter or delete.

/user/filtered_content - Content Filtering

This endpoint lets you manage the plain text content you'd like covered on your dashboard, including blog names in the reblog trail. See more info about this feature here. For filtering based on tags, see Tag Filtering.

Limits

• Each user can have a maximum of 200 filtered strings.
• Each filtered string cannot be more than 250 characters in length.
• Filtered strings can contain any characters that are valid UTF-8.

Methods

All of the endpoints require OAuth authentication.

Request Parameters

For adding new content filters, you can add one at a time or many at once via the POST body:

Example:

POST https://api.tumblr.com/v2/user/filtered_content
Content-Type: application/x-www-form-urlencoded
filtered_content=something

POST https://api.tumblr.com/v2/user/filtered_content
Content-Type: application/json
{ "filtered_content": [ "something", "technology" ] }

For deleting a content filter, pass along the string in the query params:

Example:

DELETE https://api.tumblr.com/v2/user/filtered_content?filtered_content=something

Response

For GET requests, the endpoint will return a 200 OK on success, along with the list of strings:

{
    "meta": {
        "status": 200,
        "msg": "OK"
    },
    "response": {
        "filtered_content": [
            "technology",
            "something",
            "and something else"
        ]
    }
}

For POST requests, the endpoint will return a 201 Created on success, with an empty response object.

For DELETE requests, the endpoint will return a 200 OK on success, with an empty response object.

Errors

• 400 Bad Request if given an invalid/empty string to filter or delete, or if given an already-filtered string.
• 403 Forbidden if at the maximum number of allowed filters.

Tagged Method

/tagged – Get Posts with Tag

Examples

• https://api.tumblr.com/v2/tagged?tag=gif
• https://api.tumblr.com/v2/tagged?tag=lol

Method

Request Parameters

Communities Methods

⚠️ NOTE: Communities is a brand new beta feature that's under active development. These endpoints may change in backwards-incompatible ways until the feature is fully released.

Communities endpoints often require a "community handle" path parameter, which can be given in one of a few different forms:

• The name of the community, without the double-@ prefix, i.e. communities-feedback.
• The community's unique Tumblr UUID, like blog unique identifiers. Community objects will include this.

GET /v2/communities - List joined communities

Method

Response

The response field is an array of your joined communities. See the next endpoint for the community object definition.

{
	"meta": {
		"status": 200,
		"msg": "OK"
	},
	"response": [
        { ... }, // community object
        { ... }, // community object
    ]
}

GET /v2/communities/{community-handle} - Get info about a community

Method

Request Path Parameters

Request Query Parameters

The context request parameter can be set to edit (i.e. ?context=edit) to get additional editable parts of the community, like its settings.

Response

Community objects contain these fields in the "full" version of the object. Some of them are only visible to certain roles or specific situations.

The "short" abbreviated version of the community object contains only name, uuid, title, member_count, mention_tag, can_view, and avatar_image.

For those who can edit the community, the settings object contains:

{
	"meta": {
		"status": 200,
		"msg": "OK"
	},
	"response": {
        "name": "community-name",
        "uuid": "t:abcd123",
        "title": "Community Title",
        "description": "A description of the community",
        "about": "Nothing here yet",
        "guidelines": [],
        "visibility": "public",
        "member_count": 12,
        "members_online_count": 10,
        "mention_tag": "@@community-name",
        "is_member": true,
        "can_view": true,
        "can_post": true,
        "can_edit": true,
        "can_interact": true,
        "can_invite": true,
        "can_view_comments": true,
        "post_count": 8,
        "unread_post_count": 1,
        "tags": ['tumblr communities'],
        "created_ts": 1709221499,
        "invitation": {
            "type": "direct",
            "sender": { ... } // blog info object
        },
        "handle_can_change": false,
        "handle_next_change_ts": 1234567890,
        "settings": {}, // settings object
        "avatar_image": [
            {
                "width": 512,
                "height": 512,
                "url": "https://64.media.tumblr.com/bac5b311618185a605d83e7244bfdec3/b26b33c94f644486-87/s512x512u_c1/39187fb2bbf11f92e91f40ca9a15f92041149ee6.pnj"
            },
            {
                "width": 128,
                "height": 128,
                "url": "https://64.media.tumblr.com/bac5b311618185a605d83e7244bfdec3/b26b33c94f644486-87/s128x128u_c1/424063b0e2e23d9060dedb40428e05402bfc0078.pnj"
            },
            {
                "width": 96,
                "height": 96,
                "url": "https://64.media.tumblr.com/bac5b311618185a605d83e7244bfdec3/b26b33c94f644486-87/s96x96u_c1/25bfccd20b0777a82aa8cb201b6e3d48714a2c41.pnj"
            },
            {
                "width": 64,
                "height": 64,
                "url": "https://64.media.tumblr.com/bac5b311618185a605d83e7244bfdec3/b26b33c94f644486-87/s64x64u_c1/a2ed9c2bec1c1c9e39d53fc5df564467dd01f7be.pnj"
            }
        ],
        "population_cap": 9001,
        "join_type": "invite",
        "invite_link": "https://www.tumblr.com/join/abcd123",
        "header_image": [
            {
                "type": "image/jpeg",
                "width": 2048,
                "height": 1542,
                "url": "https://64.media.tumblr.com/2ad713f0fa15a3f0517e7c5b217b4c54/32cbed0b10ff7b6c-23/s2048x3072/dad0b45b4740f15510fcb0373b52ecf6a2f7ddee.jpg"
            },
            {
                "type": "image/jpeg",
                "width": 1280,
                "height": 963,
                "url": "https://64.media.tumblr.com/2ad713f0fa15a3f0517e7c5b217b4c54/32cbed0b10ff7b6c-23/s1280x1920/7eb927d8f7e3a563c05e1ba39f3a24c3b1913791.jpg"
            },
            {
                "type": "image/jpeg",
                "width": 640,
                "height": 482,
                "url": "https://64.media.tumblr.com/2ad713f0fa15a3f0517e7c5b217b4c54/32cbed0b10ff7b6c-23/s640x960/4a7d164a3d0e2bffc1225489217e4d172c5f4822.jpg"
            }
        ],
        "pending_invitations_count": 2
	}
}

Errors

• 403 Forbidden if you are not allowed to view this:
  • Error code 23020 signifies that you have been banned from the community.
  • Error code 23001 signifies that the community is private and you are not a member.
  • Error code 23002 signifies that you are not a member and you need to be to see the content.
• 404 Not Found if the community was not found.

PUT /v2/communities/{community-handle} - Edit your community

Method

Request Path Parameters

Request Body Parameters

The different community fields that are editable:

Note that the handle can only be edited once every 7 days. When reading a community object, the handle_can_change and handle_next_change_ts fields will tell you if you can edit this.

Also note that updating the handle will invalidate the previous community URL and free up that handle to be taken by another community.

Also note that content_label_categories can include sexual_themes, violence, and/or drug_use specific labels.

Response

200 OK on successful save, along with the JSON object for your community, including the additional fields as if context=edit had been passed.

Errors

• 400 Bad Request when you've provided an invalid parameter. Error code 23025 means you cannot edit the content label.
• 403 Forbidden when you do not have permission to edit this community.
• 503 Service Unavailable when we've encountered a problem saving your community.

GET /v2/communities/{community-handle}/timeline - Get posts from a community

Method

Request Path Parameters

Request Query Parameters

We currently support timelines of type recent, polls, and discover.

Response

200 OK with a standard timeline response

Errors

• 403 Forbidden when you do not have permission to view this community, see the info endpoint for specific error codes.

GET /v2/communities/{community-handle}/members - Get community members

The list of all members can only be fetched by members, those with a pending invite, an invite code, or if the community is free-to-join and public.

The lists of admins and moderators is always accessible for public communities.

Method

Request Path Parameters

Request Query Parameters

The filter field, if provided, can have one of these values:

• 'all' for all members.
• 'admin' to list only admins.
• 'moderator' to list only moderators.
• 'following' to list any blogs the requesting user is following.
• 'mutual' to list any blogs the requesting user has a mutual following relationship with.

Response

200 OK on success. The response will have a members array, which contains standard blog info objects for each member.

Each member blog object will also contain additional fields:

Errors

• 403 Forbidden with all the error codes from the "get info" endpoint.

PUT /v2/communities/{community-handle}/members - Join a community

Users can join a maximum of 25 communities per hour and 100 per day via free-to-join or invite link.

Method

Request Path Parameters

Request Body Parameters

To join, the request must have one of the following:

• The correct invite_hash,
• or the community is free-to-join,
• or the requesting user must have a pending invitation.

Response

200 OK on successful join.

Errors

• 403 Forbidden with all the error codes from the "get info" endpoint, but also:
  • Error code 23003 if the community is already at capacity.
  • Error code 23015 if the pending invitation no longer exists or was already declined.
• 400 Bad Request with error code 23014 if the given invite hash is invalid.
• 429 Limit Exceeded when too many joins have happened too quickly. See note above.

DELETE /v2/communities/{community-handle}/members/{blog-identifier} - Remove a member

Remove another member from the community, if you have permission, or your own blog

Method

Request Path Parameters

Request Body Parameters

The reason value can be:

• community_guidelines for community guidelines violations.
• off_topic if their content is off topic.
• spam if their content is considered spam.
• inappropriate_behavior for inappropriate behavior in the community.
• tumblr_guidelines for violating Tumblr's user guidelines.
• other for another reason -- this requires the "note" parameter to be used as well

Response

200 OK on success.

Errors

• 403 Forbidden for anyone trying to do this who isn't an admin of the community, or not trying to remove their own blog
• 400 Bad Request if an invalid reason is given, or if a note wasn't given when reason = 'other'

PUT /v2/communities/{community-handle}/members/{blog-identifier} - Change a member's role

Method

Request Path Parameters

Request Body Parameters

Response

200 OK on success.

Errors

• 400 Bad Request if you provided an invalid role, or are trying to demote yourself as the last admin.
• 403 Forbidden for anyone trying to do this who isn't an admin of the community.

PUT /v2/communities/{community-handle}/invitations - Invite someone to the community

Admins can send invites at a maximum rate of 1 per second and 250 per day across all their communities.

Method

Request Path Parameters

Request Body Parameters

Response

200 OK on success.

Errors

• 400 Bad Request if you're missing a receipient blog in the request.
  • with error code 5041 if the message is too long.
• 403 Forbidden for anyone trying to do this who isn't an admin of the community. Various error codes:
  • 23003 if the community is at capacity already.
  • 23008 if the recipient blog, or its owner, has been banned from the community, or otherwise cannot join.
  • 23009 if the recipient blog is actually already a member.
  • 23011 if the recipient blog already has an invitation.
• 429 Limit Exceeded if sending invites too fast. See note above.

Limits

Admins can send 250 invites per day, at a maximum rate of 1 per second, across all of their communities.

GET /v2/communities/{community-handle}/invitations - View pending invites

Method

Request Path Parameters

Response Query Parameters

Response

200 OK on success.

The response will have a invitations array of invitations, sorted in reverse chronological order, each with fields:

• sender -- a blog object representing who sent the invite.
• recipient -- a blog object representing who was invited.
• sent_on -- the unix timestamp of when the invite was sent.

If there are more than 20 invitations, a _links object alongside the invitations array will provide the next page info.

GET /v2/communities/{community-handle}/invitations/{blog-identifier} - Check invitation status

This allows you to check the invitation status for a specific blog recipient belonging to the current user.

Method

Request Path Parameters

Response

200 OK on success, with a sender object with a name field indicating who sent the invite.

Errors

• 404 Not Found if the given blog does not have an invitation to the community.

DELETE /v2/communities/{community-handle}/invitations/{blog-identifier} - Cancel an invitation

This allows an admin to cancel a pending invitation to a specific blog, and it allows a receipient of an invitation to decline the invite, and disallow future invitations.

Method

Request Path Parameters

Response Query Parameters

Response

200 OK on success.

POST /v2/communities/{community-handle}/invite_hash - Regenerate the invite URL

Allows admins to regenerate the invite URL with a new hash. Note that this invalidates the previous invite link.

Method

Request Path Parameters

Response

200 OK on success, with a invite_link field containing the new invite link.

Errors

• 403 Forbidden with error code 23017 if invite links have been disabled for the community.
  • ... or error code 23012 if the user trying to regenerate the link is not allowed to do so.

PUT /v2/communities/{community-handle}/posts/{post-id}/reactions - Add reaction to post

React to a specific post in a community.

Method

Request Path Parameters

Request Body Parameters

The client must supply one of these two body parameters, and slug will take precedence if both are provided:

When using grapheme, we'll make a best effort to use that specific unicode character, if we support it.

Response

200 OK on successful save. The API may return a timeline response with a celebration banner on the first reaction used, or nothing.

Errors

• 400 Bad Request with subcode 22001 - when the post has reached its overall reaction limit.
• 400 Bad Request with subcode 22002 - when the current user has reached their reaction limit on this post.
• 403 Forbidden with subcode 23002 - when you're trying to react to a post in a community you're not a member of.

DELETE /v2/communities/{community-handle}/posts/{post-id}/reactions/{reaction-id} - Remove reaction from post

Remove your reaction from a specific post in a community.

Method

Request Path Parameters

Response

200 OK on successful removal.

PUT /v2/communities/{community-handle}/mute - Mute a community

Mute the community. Note that this only hides the unread count right now.

Method

Request Path Parameters

Response

200 OK on successful save.

Errors

• 403 Forbidden when you're trying to mute a community you're not a member of.

DELETE /v2/communities/{community-handle}/mute - Unmute a community

Method

Request Path Parameters

Response

200 OK on successful save.

Errors

• 403 Forbidden when you're trying to unmute a community you're not a member of.

Note that these docs are generated from our public documentation on Github.