Posts and Media - Social media studio

Posts belong to an end user and must target one of that end user’s social connections. The connectionId platform must match socialMedia.

Create a text post

Omit scheduledAt to queue the post immediately:

const post = await soMe.posts.create(
  endUser.id,
  {
    connectionId: connection.id,
    socialMedia: "THREADS",
    postType: "TEXT",
    text: "Published through our app",
  },
  { idempotencyKey: "customer_123:post_456" },
);

To schedule it, pass an ISO 8601 timestamp:

const post = await soMe.posts.create(
  endUser.id,
  {
    connectionId: connection.id,
    socialMedia: "THREADS",
    postType: "TEXT",
    text: "See you tomorrow",
    scheduledAt: "2026-08-20T10:00:00Z",
  },
  { idempotencyKey: "customer_123:post_457" },
);

Use a stable, unique idempotency key for every logical post. If your request times out, retry with the same key. Keys must contain 1–255 characters and are scoped to the end user’s workspace.

List and retrieve posts

const page = await soMe.posts.list(endUser.id, {
  page: 1,
  limit: 20,
});

const post = await soMe.posts.get(endUser.id, "post_uuid");

limit is constrained to 1–100. The list response contains data, page, limit, and total.

Upload media

Media uploads use a three-step flow:

Request a presigned upload URL from Social media studio.
Upload the raw file bytes directly to that URL with HTTP PUT. Send a Content-Type header equal to the mimetype you declared: the URL is signed with it, so a PUT without it, or with another value, fails with 403 SignatureDoesNotMatch.
Attach the returned file information when creating the post.

import { readFile, stat } from "node:fs/promises";

const filename = "launch.jpg";
const mimetype = "image/jpeg";
const size = (await stat(filename)).size;

const [media] = await soMe.posts.presignMedia(endUser.id, {
  postType: "IMAGE",
  socialMedia: "THREADS",
  files: [{ filename, mimetype, size }],
});

const upload = await fetch(media.uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": mimetype },
  body: await readFile(filename),
});

if (!upload.ok) {
  throw new Error(`Media upload failed: ${upload.status}`);
}

const post = await soMe.posts.create(
  endUser.id,
  {
    connectionId: connection.id,
    socialMedia: "THREADS",
    postType: "IMAGE",
    text: "Our launch is live",
    files: [
      {
        id: media.fileId,
        filename,
        mimetype,
        size,
        s3Prefix: media.s3Prefix,
        fileSrc: media.fileSrc,
      },
    ],
  },
  { idempotencyKey: "customer_123:post_458" },
);

For videos, include duration in seconds when requesting the URL and attaching the file. Upload URLs are temporary; request a new one if an upload has expired.

Post status

The create response confirms that the post was accepted and queued; it does not guarantee that the social platform published it. Use post.status, poll posts.get, or subscribe to post.published and post.failed webhooks for the final result.

​Create a text post

​List and retrieve posts

​Upload media

​Post status

Create a text post

List and retrieve posts

Upload media

Post status