Media

Upload a file and attach it to your post, or use a public HTTPS URL that meets the Media URL Requirements.

Upload a FileCopy Anchor Link

import { Configuration, MediaApi } from "@onepostly/sdk";

const mediaApi = new MediaApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

const response = await mediaApi.createMedia({
  createMediaBody: {
    "filename": "launch.mp4",
    "contentType": "video/mp4",
    "size": 48203776
  },
});
console.log(response);

{
  "id": "med_7f3a9c2e1b4d4e8f9a6b5c4d3e2f1a0b",
  "url": "https://cdn.onepostly.com/media/5b0e7c1a-2f4d-4c8e-9a3b-6d1f0e2c4a7b/7f3a9c2e-1b4d-4e8f-9a6b-5c4d3e2f1a0b.mp4",
  "contentType": "video/mp4",
  "sizeBytes": null,
  "filename": "launch.mp4",
  "status": "pending",
  "createdAt": "2027-03-15T09:00:00.000Z",
  "uploadUrl": "https://5d1e8a3c9f2b4e7a.r2.cloudflarestorage.com/onepostly-media/temp/5b0e7c1a-2f4d-4c8e-9a3b-6d1f0e2c4a7b/7f3a9c2e-1b4d-4e8f-9a6b-5c4d3e2f1a0b.mp4?X-Amz-Expires=3600&X-Amz-Date=20270315T090000Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLEKEY%2F20270315%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=content-length%3Bcontent-type%3Bhost&X-Amz-Signature=0f4c2b9e7a1d3f5b8c6e0a2d4f6b8e1c3a5d7f9b2e4c6a8d0f1b3e5c7a9d2f4b",
  "uploadExpiresIn": 3600
}

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

await fetch(uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "video/mp4" },
  body: await readFile("launch.mp4"),
});

import { Configuration, PostsApi } from "@onepostly/sdk";

const postsApi = new PostsApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

const response = await postsApi.createPost({
  createPostBody: {
    "text": "Launch day",
    "media": [
      {
        "id": "med_7f3a9c2e1b4d4e8f9a6b5c4d3e2f1a0b"
      }
    ],
    "accounts": [
      {
        "accountId": "acc_YOUR_X_ACCOUNT_ID"
      }
    ]
  },
});
console.log(response);

{
  "groupId": "grp_7d2e5b1a9c4f4a68b3e07f1c2d9a6e45",
  "data": [
    {
      "id": "pst_3c8a2d6e91b44f7a8e250d6b4c1f9a73",
      "groupId": "grp_7d2e5b1a9c4f4a68b3e07f1c2d9a6e45",
      "accountId": "acc_YOUR_X_ACCOUNT_ID",
      "platform": "x",
      "source": "onepostly",
      "status": "publishing",
      "text": "Launch day",
      "mediaKind": "video",
      "media": [
        {
          "url": "https://cdn.onepostly.com/media/5b0e7c1a-2f4d-4c8e-9a3b-6d1f0e2c4a7b/7f3a9c2e-1b4d-4e8f-9a6b-5c4d3e2f1a0b.mp4"
        }
      ],
      "thread": [],
      "scheduledFor": null,
      "timezone": null,
      "options": {},
      "platformPostId": null,
      "url": null,
      "error": null,
      "publishedAt": null,
      "metrics": null,
      "createdAt": "2027-03-15T10:00:00.000Z",
      "updatedAt": "2027-03-15T10:00:00.000Z"
    }
  ]
}

ExpiryCopy Anchor Link

An expired uploadUrl needs a new media item.

Media URL RequirementsCopy Anchor Link

Every media URL must meet these rules, uploaded or self-hosted.

• HTTPS to a public address.
• At most 2,048 characters.
• Returns the file with 200, Content-Length and the right Content-Type.
• At most 5 redirects, each to a public HTTPS address.
• No stall longer than 30 seconds.

Share links from Google Drive, Dropbox, OneDrive, SharePoint and iCloud fail. They return a web page, not the file. Open the URL in a private window to check it. If you see a page, upload the file to Onepostly.

The first two rules are checked when you create the post and return 400 VALIDATION_ERROR. The rest are checked at publish and fail the post with MEDIA_UNFETCHABLE. Uploaded files meet every rule once their status is ready.

Supported FormatsCopy Anchor Link

Onepostly accepts these files, and each platform adds its own limits. See the media requirements on each platform page, such as Instagram.

A larger size is refused with 400 MEDIA_TOO_LARGE before the upload starts.

Platform LimitsCopy Anchor Link

Each platform takes only some formats and sizes. They are in the Media Requirements on its page, such as Instagram.

• An uploaded file outside them returns 400 when you create or edit the post, and nothing is created. param names the file, such as media.0 or thread.1.media.0.
• A file sent by url is checked when the post publishes, and the post fails with the same code.

The Content-Type sets a file's format. When it is missing or application/octet-stream, the URL's extension sets it.

Media per PlatformCopy Anchor Link

The mediaKind values and the file count each platform takes.

Durations, sizes and dimensions are on each platform page, such as X. See Compare Platforms to view all platforms side by side.

List UploadsCopy Anchor Link

GET /v1/media lists the files you uploaded, newest first. Media items still waiting for their upload are not listed.

import { Configuration, MediaApi } from "@onepostly/sdk";

const mediaApi = new MediaApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

const response = await mediaApi.listMedia({
  limit: 20,
});
console.log(response);

{
  "data": [
    {
      "id": "med_7f3a9c2e1b4d4e8f9a6b5c4d3e2f1a0b",
      "url": "https://cdn.onepostly.com/media/5b0e7c1a-2f4d-4c8e-9a3b-6d1f0e2c4a7b/7f3a9c2e-1b4d-4e8f-9a6b-5c4d3e2f1a0b.mp4",
      "contentType": "video/mp4",
      "sizeBytes": 48203776,
      "filename": "launch.mp4",
      "status": "ready",
      "createdAt": "2027-03-15T09:00:00.000Z"
    },
    {
      "id": "med_7f3a9c2e1b4d4e8f9a6b5c4d3e2f1a02",
      "url": "https://cdn.onepostly.com/media/5b0e7c1a-2f4d-4c8e-9a3b-6d1f0e2c4a7b/7f3a9c2e-1b4d-4e8f-9a6b-5c4d3e2f1a02.jpg",
      "contentType": "image/jpeg",
      "sizeBytes": 482113,
      "filename": "spring.jpg",
      "status": "ready",
      "createdAt": "2027-03-14T16:30:00.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

You get 50 files per page by default and up to 100 with limit. Pass nextCursor as cursor to get the next page, until hasMore is false. Add include=total to get the total count. See Pagination.

Delete an UploadCopy Anchor Link

import { Configuration, MediaApi } from "@onepostly/sdk";

const mediaApi = new MediaApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

const response = await mediaApi.deleteMedia({
  id: "med_7f3a9c2e1b4d4e8f9a6b5c4d3e2f1a0b",
});
console.log(response);

This returns 204 and deletes the file for good. Published posts are not affected, because each platform keeps its own copy.

A scheduled post that still uses the file fails when it publishes, so delete files only once all their posts are live.

ErrorsCopy Anchor Link

These come back from a media request or POST /v1/posts.

File problems show up later, in the post's error.code. See Failed Posts.

Other codes are in Errors.