Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


JavaScript client for the Tumblr API

Subscribe to updates I use tumblr.js

Statistics on tumblr.js

Number of watchers on Github 525
Number of open issues 4
Average time to close an issue 5 months
Main language JavaScript
Average time to merge a PR 25 days
Open pull requests 11+
Closed pull requests 6+
Last commit about 3 years ago
Repo Created over 7 years ago
Repo Last Updated over 2 years ago
Size 3.71 MB
Organization / Authortumblr
Latest Release1.1.0
Page Updated
Do you use tumblr.js? Leave a review!
View open issues (4)
View tumblr.js activity
View on github
Book a Mock Interview With Me (Silicon Valley Engineering Leader, 100s of interviews conducted)
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating tumblr.js for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Build Status

The official JavaScript client library for the Tumblr API. Check out the detailed documentation here.


Install this package from npm:

npm install --save tumblr.js



Different API methods use different kinds of authentication.

Most of them require at least an API key, which will require you to register an application. The OAuth Consumer Key is your API key.

For methods that require a fully signed request, you'll need OAuth tokens as well, which you get from authenticating as a Tumblr user and allowing access to your API application. Here's the easy way to do it with our own account:

  1. Visit the OAuth applications page
  2. Click Explore API on the application you want to authorize
  3. Click the Allow button, which will take you to the API console
  4. Click the Show keys button, which will show you the credentials you can use to make signed requests.

If you're building an application of your own for users out in the world, you'll need to go through the 3-legged OAuth flow. See the help docs for more info.

In Node.js

var tumblr = require('tumblr.js');
var client = tumblr.createClient({
  consumer_key: '<consumer key>',
  consumer_secret: '<consumer secret>',
  token: '<oauth token>',
  token_secret: '<oauth token secret>'

Or, if you prefer:

var tumblr = require('tumblr.js');
var client = new tumblr.Client({
  // ...

The request methods return Request objects by default, but you can have it return Promise objects instead, if that's more your thing. Pass returnPromises: true in the options to createClient:

var tumblr = require('tumblr.js');
var client = tumblr.createClient({
  credentials: {
    // ...
  returnPromises: true,

In the Browser

Due to CORS restrictions, you're going to have a really hard time using this library in the browser. Although GET endpoints on the Tumblr API support JSONP, this library is not intended for in-browser use. Sorry!


// Show user's blog names
client.userInfo(function(err, data) {
  data.user.blogs.forEach(function(blog) {

Supported Methods

Below is a list of available methods and their purpose. Available options are documented in the API Docs and are specified as a JavaScript object.

client.blogPosts('staff', {type: 'photo'}, function(err, resp) {
  resp.posts; // use them for something

In most cases, since options are optional (heh) they are also an optional argument, so there is no need to pass an empty object when supplying no options, like:

client.blogPosts('staff', function(err, resp) {
  resp.posts; // now we've got all kinds of posts

If you're using Promises, use then and/or catch instead of a callback:

  .then(function(resp) {
  .catch(function(err) {
    // oops

User Methods

// Get information about the authenticating user & their blogs

// Get dashboard for authenticating user
client.userDashboard(options, callback);

// Get likes for authenticating user
client.userLikes(options, callback);

// Get followings for authenticating user
client.userFollowing(options, callback);

// Follow or unfollow a given blog
client.followBlog(blogURL, callback);
client.unfollowBlog(blogURL, callback);

// Like or unlike a given post
client.likePost(id, reblogKey, callback);
client.unlikePost(id, reblogKey, callback);

Blog Methods

// Get information about a given blog
client.blogInfo(blogName, callback);

// Get a list of posts for a blog (with optional filtering)
client.blogPosts(blogName, options, callback);
client.blogPosts(blogName, callback);

// Get the avatar URL for a blog
client.blogAvatar(blogName, size, callback);
client.blogAvatar(blogName, callback);

// Get the likes for a blog
client.blogLikes(blogName, options, callback);
client.blogLikes(blogName, callback);

// Get the followers for a blog
client.blogFollowers(blogName, options, callback);
client.blogFollowers(blogName, callback);

// Get the queue for a blog
client.blogQueue(blogName, options, callback);
client.blogQueue(blogName, callback);

// Get the drafts for a blog
client.blogDrafts(blogName, options, callback);
client.blogDrafts(blogName, callback);

// Get the submissions for a blog
client.blogSubmissions(blogName, options, callback);
client.blogSubmissions(blogName, callback);

Post Methods

// Edit a given post
client.editPost(blogName, options, callback);

// Reblog a given post
client.reblogPost(blogName, options, callback);

// Delete a given post
client.deletePost(blogName, id, callback);

// Convenience methods for creating post types
client.createTextPost(blogName, options, callback);
client.createPhotoPost(blogName, options, callback);
client.createQuotePost(blogName, options, callback);
client.createLinkPost(blogName, options, callback);
client.createChatPost(blogName, options, callback);
client.createAudioPost(blogName, options, callback);
client.createVideoPost(blogName, options, callback);

Tagged Methods

// View posts tagged with a certain tag
client.taggedPosts(tag, options, callback);
client.taggedPosts(tag, callback);

Unsupported Methods

You can make GET and POST requests to any endpoint directly. These methods are used internally by the methods listed above:

// GET requests
client.getRequest(apiPath, params, callback);

// POST requests
client.postRequest(apiPath, params, callback);

In the unlikely event that we add a bunch of methods to the API docs and don't update this client, you can map new client methods to API endpoints. URL and query parameters are automatically turned into arguments to these methods. It's a little weird to explain, so just look at these examples:

// GET methods
  // creates client.userInfo(params, callback)
  userInfo: '/user/info',
  // client.blogInfo(blogIdentifier, params, callback)
  blogInfo: '/blog/:blogIdentifier/info',
  // Creates client.taggedPosts(tag, params, callback)
  taggedPosts: ['/tagged', ['tag']],

// POST methods
  // client.deletePost(blogIdentifier, id, params, callback)
  deletePost: ['/blog/:blogIdentifier/post/delete', ['id']],
  // Creates client.likePost(tag, id, reblog_key, params, callback)
  likePost: ['/user/like', ['id', 'reblog_key']],

Running Tests

npm test # linter and tests
gulp lint # linter
gulp test # just the tests

Copyright and license

Copyright 2013-2016 Tumblr, Inc.

Licensed under the Apache License, Version 2.0 (the License); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:


Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations.

tumblr.js open issues Ask a question     (View All Issues)
  • about 4 years BlogInfo response = null
  • about 4 years TypeScript definitions
  • about 5 years Tumblr.js Link posts API not the same as website
  • almost 6 years Multiple image posting support
tumblr.js open pull requests (View All Pulls)
  • chore(core): use https for api calls
  • Introducing default parameters for post creation and edit
  • returning the response object in callback
  • Request timeout
  • add browser-request dep
  • Support multi-image posting/external images with data field
  • Support for Buffer type of data parameter
  • Just added the missing photo parameter
  • tumblr.js v1.0.0
  • Add Promise support to requests
  • Start of typescript type definitions
tumblr.js questions on Stackoverflow (View All Questions)
  • Tumblr.js official javascript/node API "link" posts with image, title, body
  • Tumblr.js API -- require() fails
  • How to post Photo Blog to tumblr with the "tumblr.js" NodeJS module
tumblr.js list of languages used
tumblr.js latest release notes
1.1.0 v1.1.0
  • Support for passing options object instead of individual arguments
  • Promise support using returnPromises option (defaults to off)
1.0.0 v1.0.0

Substantial refactor of the tumblr.js library.

  • Naming of API method standardized. This is a breaking change, but switching to the new method names is straightforward!
  • Rewritten method implementation to make it easier to map methods to API endpoints
  • Tumblr API baseUrl is now customizable, if that's your jam
  • data64 support where it makes sense
  • Split tumblr.js REPL into a separate repository to keep dependency weight down
  • Oh yeah, we updated all the dependencies and devDependencies
  • Dropped Browserify support. Sorry, but you probably won't miss it.
  • Added eslint rules
  • New mocha tests
v0.0.7 v0.0.7

Previously forgot to increment version number in package.json. This release is otherwise identical to v0.0.6. Changeset of v0.0.6 release was:

  • Loose request version requirement
Other projects in JavaScript
Powered by Autocode - Instant Webhooks, Scripts and APIs
Autocode logo wordmark