Node.js SDK

@postqueen/node is a small typed client for the PostQueen API. It sends your API key and calls five endpoints for you: list channels, create a post, list posts, upload a file and delete a post. Everything else in the API is a plain HTTPS call, shown below. This page describes version 1.0.7. Run npm ls @postqueen/node to see yours.

Before you start

Node.js 20.19 or newer. On Node.js 22, use 22.12 or newer. The package loads its HTTP library with require, which older versions refuse.
A PostQueen workspace on a trial or a paid plan, with at least one connected channel.
The API key, from the box below.

Where the API key is: in the app, open Connections > API Keys. Only a workspace Admin or Super Admin can reveal or rotate it; other members see it masked. A workspace has one key, and each agent card on Connections shows your MCP address with the key already filled in.

Install and schedule a first post

Install the package

npm install @postqueen/node

pnpm add @postqueen/node

Set your key

export POSTQUEEN_API_KEY=your_api_key

The client takes the key as its first argument. Reading it from the environment keeps it out of your code.

Schedule a post

This finds your Bluesky channel and schedules a text post on it.

schedule.ts

import PostQueen from '@postqueen/node';

type Channel = { id: string; name: string; identifier: string; disabled: boolean };

async function main() {
  const postqueen = new PostQueen(process.env.POSTQUEEN_API_KEY!);

  // The channels you can post to. The API calls them integrations.
  const channels = (await postqueen.integrations()) as Channel[];
  const bluesky = channels.find((c) => c.identifier === 'bluesky');
  if (!bluesky) throw new Error('Connect a Bluesky channel first');

  // Schedule a text post
  const created = await postqueen.post({
    type: 'schedule',
    date: '2026-10-01T09:00:00.000Z',
    posts: [
      {
        integration: { id: bluesky.id },
        value: [{ content: 'Shipping the new calendar today.' }],
      },
    ],
  });
  console.log(created); // [{ postId, integration }]
}

main();

Check it

The post appears on the calendar in the app, and created holds one { postId, integration } per channel.

The SDK fills in shortLink, tags and each part’s image when you leave them out. Fields you can leave out lists the rest.

In an ES module

In a CommonJS project, or in TypeScript compiled to CommonJS with esModuleInterop, the default import above works. In an ES module ("type": "module", a .mjs file, or TypeScript with "module": "nodenext"), the class is on .default:

import pkg from '@postqueen/node';

const PostQueen = pkg.default;
const postqueen = new PostQueen(process.env.POSTQUEEN_API_KEY!);

The client

new PostQueen(apiKey, baseUrl?)

Argument	What it is
`apiKey`	Your workspace API key, or an OAuth access token that starts with `pos_`. The SDK sends either as it is in the `Authorization` header, so a product your users sign in to with OAuth can use the SDK with their token.
`baseUrl`	Optional. The API’s address without `/public/v1`: the SDK adds `/public/v1/...` to it. Left out, or `undefined`, it is the `POSTQUEEN_API_URL` environment variable when that is set, and otherwise `https://api.postqueen.ai`.

On PostQueen Cloud, leave baseUrl out. If you run PostQueen on your own server, pass your backend’s address, or set POSTQUEEN_API_URL to it:

const postqueen = new PostQueen(process.env.POSTQUEEN_API_KEY!, 'https://postqueen.example.com/api');

The default is read when you create the client, so set POSTQUEEN_API_URL before that. An empty string is used as it is, not replaced by the default, and every call then fails.

Fields you can leave out

From 1.0.5 the types follow what the API needs, so the smallest post is a channel, a date and some text.

Field	When you leave it out
`shortLink`, `tags`	The SDK sends `false` and `[]`. PostQueen has no link shortener set up today, so `shortLink: true` would change nothing either.
`posts[].value[].image`	The SDK sends `[]`.
`posts[].group`	PostQueen creates new posts. A group id that already exists replaces the posts that have it, so never reuse an old one by accident.
`posts[].settings`	Fine for a network with no required settings. PostQueen sets `__type` from the channel.
`posts[].value[].id`	PostQueen creates a new post. The id of an existing post changes that post instead.
`posts[].value[].delay`	No wait after the previous entry of a thread. The value is in minutes.

postList() still takes the API’s filter type, which asks for customer: send '' to list the posts of every channel. Version 1.0.4 also asked for group: '', id: '' and delay: 0; update with npm install @postqueen/node@latest. Which settings each network takes is on Posting settings by network.

Methods

Method	Endpoint	Returns
`integrations()`	`GET /integrations`	The parsed JSON body
`post(body)`	`POST /posts`	The parsed JSON body
`postList(filters)`	`GET /posts`	The parsed JSON body
`upload(file, extension)`	`POST /upload`	The parsed JSON body
`deletePost(id)`	`DELETE /posts/{id}`	The raw `Response`, not parsed

Every method but deletePost() is typed as returning unknown. Cast the result to the shape you expect, as the examples do.

Post with an image and a thread

Upload the file first, then put its id and path on the post. The second entry goes out 5 minutes after the first.

upload.ts

import { readFile } from 'node:fs/promises';
import PostQueen from '@postqueen/node';

type Media = { id: string; path: string; status: 'ready' | 'processing' | 'failed' };

async function main() {
  const postqueen = new PostQueen(process.env.POSTQUEEN_API_KEY!);

  const media = (await postqueen.upload(await readFile('launch.png'), 'png')) as Media;

  await postqueen.post({
    type: 'schedule',
    date: '2026-10-01T09:00:00.000Z',
    posts: [
      {
        integration: { id: 'YOUR_CHANNEL_ID' },
        value: [
          { content: 'The new calendar is live.', image: [{ id: media.id, path: media.path }] },
          { content: 'Drag a post to move it.', delay: 5 },
        ],
      },
    ],
  });
}

main();

upload() sends the file with a content type taken from the extension you pass: png, jpg, jpeg, gif, webp, mp4 and mov are mapped, anything else is sent as JPEG. PostQueen reads the real type from the file itself either way. A video comes back with status: "processing". An MP4 can go into a post right away; a MOV has to reach ready in Get media status first, since a post takes no MOV.

One post on two networks with settings

WordPress and DEV each need a title. WordPress also needs the post type, here posts.

settings.ts

import PostQueen from '@postqueen/node';

async function main() {
  const postqueen = new PostQueen(process.env.POSTQUEEN_API_KEY!);

  await postqueen.post({
    type: 'schedule',
    date: '2026-10-01T09:00:00.000Z',
    posts: [
      {
        integration: { id: 'YOUR_WORDPRESS_CHANNEL_ID' },
        settings: { __type: 'wordpress', title: 'A calendar that shows everything', type: 'posts', status: 'publish' },
        value: [{ content: '<p>Drafts now sit next to scheduled posts.</p>' }],
      },
      {
        integration: { id: 'YOUR_DEV_CHANNEL_ID' },
        settings: { __type: 'devto', title: 'Why we rebuilt the calendar', tags: [] },
        value: [{ content: '## Why we rebuilt the calendar\n\nThree things changed.' }],
      },
    ],
  });
}

main();

List and delete posts

list-delete.ts

import PostQueen from '@postqueen/node';

type ListedPost = { id: string; content: string; publishDate: string; state: string; group: string };

async function main() {
  const postqueen = new PostQueen(process.env.POSTQUEEN_API_KEY!);

  const { posts } = (await postqueen.postList({
    startDate: '2026-10-01T00:00:00.000Z',
    endDate: '2026-10-31T23:59:59.000Z',
    customer: '',
  })) as { posts: ListedPost[] };

  const res = await postqueen.deletePost(posts[0].id);
  if (res.status === 404) console.log('Already gone');
  else if (!res.ok) throw new Error(`Delete failed: ${res.status}`);
}

main();

A delete answers { "error": true } when it works. Judge it by the status code, as above.

Errors

The client does not throw when PostQueen answers with an error. It hands back the error body instead, such as { "msg": "Invalid API key" }, or a 400 with provider and message when a post breaks a network’s rules. Check the shape before you use a result:

errors.ts

import PostQueen from '@postqueen/node';

async function main() {
  const postqueen = new PostQueen(process.env.POSTQUEEN_API_KEY!);

  const result = await postqueen.post({
    type: 'schedule',
    date: '2026-10-01T09:00:00.000Z',
    posts: [
      {
        integration: { id: 'YOUR_CHANNEL_ID' },
        value: [{ content: 'Shipping the new calendar today.' }],
      },
    ],
  });

  // The SDK returns the body of an error answer instead of throwing.
  if (!Array.isArray(result)) {
    throw new Error(`PostQueen refused the post: ${JSON.stringify(result)}`);
  }
}

main();

post() counts against the 30 POST /posts requests a workspace can send in an hour, except calls refused during validation, and upload() against 300 uploads an hour. Put several channels in one post() call rather than one call per channel. What each status code means is on Limits and errors.

Calls the SDK does not wrap

Every other endpoint is a plain HTTPS call with the same header. Send the key as it is, with no Bearer prefix. This one checks whether an uploaded video is ready:

media-status.ts

const API = 'https://api.postqueen.ai/public/v1';

type MediaStatus = { id: string; path: string; status: 'ready' | 'processing' | 'failed'; processingError: string | null };

async function mediaStatus(id: string): Promise<MediaStatus> {
  const res = await fetch(`${API}/media/${id}/status`, {
    headers: { Authorization: process.env.POSTQUEEN_API_KEY! },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  return (await res.json()) as MediaStatus;
}

mediaStatus('YOUR_MEDIA_ID').then(console.log);

The endpoints are listed in the sidebar under Endpoints, each with its request, responses and a playground.

Next steps

Schedule a post with the API

From listing your channels to checking that the post went out.

Posting settings by network

The settings each network needs in a post, and which fields are required.

Limits and errors

The hourly limits, and the status codes the API returns.

Call the API from JavaScript or TypeScript with @postqueen/node.

Get started

Endpoints

Posting settings by network

Build on PostQueen

SDK and no-code

Node.js SDK

Before you start

Install and schedule a first post

In an ES module

The client

Fields you can leave out

Methods

Post with an image and a thread

One post on two networks with settings

List and delete posts

Errors

Calls the SDK does not wrap

Next steps

Schedule a post with the API

Posting settings by network

Limits and errors

Node.js SDK

​Before you start

​Install and schedule a first post

​In an ES module

​The client

​Fields you can leave out

​Methods

​Post with an image and a thread

​One post on two networks with settings

​List and delete posts

​Errors

​Calls the SDK does not wrap

​Next steps

Schedule a post with the API

Posting settings by network

Limits and errors

Node.js SDK

Before you start

Install and schedule a first post

In an ES module

The client

Fields you can leave out

Methods

Post with an image and a thread

One post on two networks with settings

List and delete posts

Errors

Calls the SDK does not wrap

Next steps