Docs/API Reference/Tumblr

Tumblr API

Use the Crosspostify API to publish image, multi-image and video posts to Tumblr blogs — the creative platform built for long-form expression and niche communities.

Post Types
Image · Multi-image · Video
Title
Supported (optional)
Tags
Not set (hashtags stay as text)
Audience
Creative & niche communities

Tumblr is a long-form blogging and microblogging platform with a passionate creative community. Discovery on Tumblr is largely tag-driven — users follow tags, not just blogs. The API does not set Tumblr tags (see Tags & Discovery below), so add tags in Tumblr itself if reach through tags matters to you.

The Crosspostify Tumblr integration supports three post types: image, multi-image photosets and video. Text-only posts are not available for Tumblr (/post/text only accepts Facebook and Threads). Tumblr is one of the few platforms where title is genuinely useful — on image and photoset posts it renders as a styled heading above the post body; on video posts it becomes the first line of the caption.

This page covers everything specific to Tumblr when using the Crosspostify API. For general authentication, rate limits, and error handling, see the full API Reference.

Tumblr-Specific Parameters

Tumblr uses the common parameter set with no platform-exclusive fields. title, caption and link are all used on Tumblr. Posts are always published publicly to the primary blog of the connected Tumblr account.

accountId✓ AppliesRequired. The id of the Tumblr account from GET /social-accounts. Posts go to the primary blog of that account.
title✓ AppliesOptional. Max 90 characters (longer titles are cut, no error). Heading on image and photoset posts; first line of the caption on video posts.
caption✓ AppliesThe post body text. Max 2,200 characters (cut, no error). Hashtags stay as plain text; no Tumblr tags are set.
link✓ AppliesSource URL shown on the post.
boardId✗ IgnoredPinterest only — Tumblr posts go to your blog directly.
is_aigc✗ IgnoredTikTok, Instagram and Facebook only — ignored for Tumblr.
thumbnailTimestamp✗ IgnoredTikTok only — ignored for Tumblr.
facebookFirstComment✗ IgnoredFacebook only — ignored for Tumblr.
textFormatPresetId✗ IgnoredFacebook text posts only — ignored for Tumblr.
tiktok / instagram / facebook✗ IgnoredSettings for those platforms — ignored for Tumblr.
Tumblr tags are not set by the API

Hashtags in caption (e.g. #photography) are posted as plain text in the post body and do not add Tumblr tags. If you want tags on a post, add them in Tumblr itself.

Supported Endpoints

Tumblr supports three Crosspostify post types: image, multi-image photosets (a native Tumblr format) and video. Text-only posts (/post/text) are not available for Tumblr.

POST/post/imagePhoto Post

Publish a single image to a Tumblr blog as a photo post. Tumblr usually shows the image at post width with the caption below. Ideal for photography, illustration, and visual art.

Image Post Notes

  • title renders as a heading above the image — useful for named series (e.g. "Daily Sketch #42"). Max 90 characters.
  • Hashtags in caption stay as plain text; no Tumblr tags are set
  • link sets the source URL shown on the post
  • Upload your image first via POST /media and pass the returned id as mediaId
  • scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.
  • Omit scheduledDate to post immediately

Request Body

mediaIdstringrequired

The ID of the uploaded image file. Obtain this from POST /media.

scheduledDatestringoptional

ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets are converted to UTC). Omit to post immediately.

postsarrayrequired

Array of post objects. One object per connected Tumblr account.

posts[].accountIdstringrequired

The id of the Tumblr account from GET /social-accounts. Posts go to the primary blog of that account.

posts[].titlestringoptional

Optional post heading, rendered above the image. Max 90 characters (longer titles are cut, no error).

posts[].captionstringoptional

Post body text. Max 2,200 characters (longer text is cut, no error). Hashtags stay as plain text.

posts[].linkstringoptional

Source URL shown on the Tumblr post.

Response

202 Accepted. status is SCHEDULED when scheduledDate is set, otherwise QUEUED. The post is published afterwards; check the result with GET /posts?id=<id>.

{ "mediaId": "img_12345", "message": "Image post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "tumblr", "socialAccountId": "acc_tumblr_456", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_tumblr_456",
        "title": "Neon Cityscapes at 3am",
        "caption": "There is something about empty streets and wet pavement that hits different. Shot on a Ricoh GR IIIx. #photography #nightphotography #streetphotography #filmlook",
        "link": "https://example.com/neon-cityscapes"
      }
    ]
  }'
POST/post/imagesPhotoset

Publish 1 to 10 images to a Tumblr blog as a photoset — Tumblr's native multi-image format and a staple of Tumblr's visual culture.

Photoset Notes

  • 1 to 10 images per post. More than 10 returns 400 "Too many images" ("Tumblr supports a maximum of 10 images per post")
  • Images are posted in mediaIds order as one photoset row; Tumblr decides the final display
  • Photosets are a core Tumblr format — great for photo series, mood boards, and travel dumps
  • A single shared caption appears below the entire photoset; title appears as a heading above it
  • scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdsarrayrequired

Ordered array of 1 to 10 image media IDs. Images appear in this order in the photoset. More than 10 returns 400.

scheduledDatestringoptional

ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets are converted to UTC). Omit to post immediately.

postsarrayrequired

Array of post objects. One object per connected Tumblr account.

posts[].accountIdstringrequired

The id of the Tumblr account from GET /social-accounts. Posts go to the primary blog of that account.

posts[].titlestringoptional

Optional post heading, rendered above the photoset. Max 90 characters (longer titles are cut, no error).

posts[].captionstringoptional

Shared caption for the entire photoset. Max 2,200 characters (longer text is cut, no error). Hashtags stay as plain text.

posts[].linkstringoptional

Source URL shown on the Tumblr post.

Response

202 Accepted. status is SCHEDULED when scheduledDate is set, otherwise QUEUED.

{ "mediaIds": ["img_001", "img_002", "img_003", "img_004"], "message": "Multiple images post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "tumblr", "socialAccountId": "acc_tumblr_456", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/images" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": ["img_001", "img_002", "img_003", "img_004"],
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_tumblr_456",
        "title": "Tokyo Photo Dump — Spring 2025",
        "caption": "A week of wandering. Cherry blossoms, convenience stores, and too much matcha. #japan #tokyo #travel #photography"
      }
    ]
  }'
POST/post/videoVideo Post

Publish a native video to a Tumblr blog. The video is embedded directly in the post. Popular for short films, process videos, and creative clips.

Video Post Notes

  • Videos are embedded natively in the post; Tumblr decides how they play in the dashboard
  • Upload your video first via POST /media (MP4 or MOV, max 100 MB) and pass the returned id as mediaId
  • On video posts, title becomes the first line of the caption text (plain text, not a heading)
  • Tumblr's video audience skews toward creative and artistic content
  • scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdstringrequired

The ID of the uploaded video file. Obtain this from POST /media.

scheduledDatestringoptional

ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets are converted to UTC). Omit to post immediately.

postsarrayrequired

Array of post objects. One object per connected Tumblr account.

posts[].accountIdstringrequired

The id of the Tumblr account from GET /social-accounts. Posts go to the primary blog of that account.

posts[].titlestringoptional

Optional. On video posts the title becomes the first line of the caption text (plain text, not a heading). Max 90 characters.

posts[].captionstringoptional

Post body text below the video. Max 2,200 characters (longer text is cut, no error). Hashtags stay as plain text.

posts[].linkstringoptional

Source URL shown on the Tumblr post.

Response

202 Accepted. status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Tumblr may still reject the video after this; GET /posts then shows status FAILED with an error.

{ "mediaId": "vid_12345", "message": "Video post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "tumblr", "socialAccountId": "acc_tumblr_456", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_tumblr_456",
        "title": "Making a Zine from Scratch",
        "caption": "Full process video — from blank paper to finished zine. Tools used: X-Acto knife, bone folder, saddle stitch binding. #zine #diy #bookbinding #printmaking"
      }
    ]
  }'

Tags & Discovery

Discovery on Tumblr is largely tag-driven: users actively follow and browse specific tags. The Crosspostify API does not set Tumblr tags, so posts published through the API have no tags unless you add them in Tumblr.

How Tags Work

  • Crosspostify does not set Tumblr tags
  • Hashtags in caption are posted as plain text in the post body
  • Plain-text hashtags do not add Tumblr tags
  • To tag a post, add the tags in Tumblr after it is published
  • Users who follow a tag see posts with that tag
  • Tags also appear in Tumblr search results

If You Add Tags in Tumblr

  • Use niche tags — they have dedicated followers
  • Mix broad tags (#photography) with specific ones (#filmphotography)
  • Tumblr communities are tag-based — research your niche
  • Avoid tag spam — quality over quantity
Post to several Tumblr accounts in one call

Each connected Tumblr account posts to its primary blog. Add one entry per connected account to the posts array — each with a different accountId — to post to several accounts in one call. Secondary blogs of the same Tumblr login cannot be targeted.

Content Guidelines

Tumblr's audience is creative, niche-focused, and highly engaged within specific communities. Content that feels authentic and community-native performs far better than polished brand content.

Image Requirements

  • Format: JPG, PNG or WEBP (converted to JPEG on upload)
  • Max file size: 20MB per image (Crosspostify upload limit)
  • GIF and HEIC files are rejected at upload
  • Tumblr shows images at post width, so wide images look sharpest
  • Photosets: up to 10 images per post

Video Requirements

  • Format: MP4 or MOV
  • Max file size: 100MB via Crosspostify
  • Tumblr limits video length; check the current Tumblr limits
  • No specific aspect ratio requirement

Text & Caption Tips

  • Caption max 2,200 characters, title max 90 (longer text is cut, no error)
  • title renders as a styled heading on image and photoset posts
  • Hashtags stay as plain text in the caption
  • Reblog culture rewards authentic, relatable content
  • Avoid overly promotional or corporate tone

Scheduling

  • Omit scheduledDate to post immediately
  • Any ISO 8601 time; offsets are converted to UTC, no offset = UTC
  • Must be in the future (past = 400); no minimum lead time
  • Published within about 1 minute of the scheduled time
  • Best times: evenings and late nights (Tumblr skews night-owl)