Let your agent upload, schedule and post.

utsk_live_xxxxxxxxxxxx.your-secret-here

---
name: pulsarsocial
description: Schedule and publish social media posts through PulsarSocial (getpulsarsocial.com) — Instagram posts/reels/stories, Facebook Pages, TikTok videos, X/Twitter tweets, YouTube videos and Shorts, and Pinterest pins — from one content calendar. Use when asked to draft, schedule, queue, plan, publish, reschedule, cancel or audit social posts, build a content calendar or posting plan, check which social accounts are connected, upload or ingest media for a post, or check posting quota. Covers the PulsarSocial MCP tools (list_accounts, validate_post, create_post, …) and the REST API at https://getpulsarsocial.com/api/v1.
---

# PulsarSocial

PulsarSocial schedules one post to many platforms at once. You write the content, pick which connected accounts it goes to, give it a time, and PulsarSocial publishes it.

Everything below assumes you have the PulsarSocial MCP tools available. If you don't, the same operations exist as REST at `https://getpulsarsocial.com/api/v1` with an `Authorization: Bearer utsk_live_…` header, and the shapes are identical.

## The one workflow that works

```
list_accounts  →  validate_post  →  create_post
```

Do not skip steps. Each one exists because the step after it fails without it.

### 1. `list_accounts` — always first

Every target in a post needs a real `social_account_id`. These are opaque ids belonging to the user's workspace; you cannot guess them, derive them from a handle, or reuse one from an earlier conversation. Call `list_accounts` at the start of any posting task, even if the user only mentioned one platform.

It also tells you what is *possible*. If the user says "post this to LinkedIn" and `list_accounts` returns no LinkedIn account, say so immediately rather than constructing a payload that will 404.

**Connecting an account is not something you can do.** It is an interactive OAuth flow in a browser — the user has to visit getpulsarsocial.com and click through the platform's consent screen. There is no API for it, by design. If an account is missing, tell the user to connect it in the dashboard and stop.

### 2. `validate_post` — use it constantly

`validate_post` takes the exact payload you would pass to `create_post` and tells you whether it would succeed. It is a dry run:

- writes nothing
- consumes no quota
- never touches a live social account
- returns per-target errors and warnings, not one generic "invalid"

This is the single most useful tool in the set. Platform rules are fiddly and inconsistent, and the cost of guessing wrong on `create_post` is a real post on a real account. So: **build a payload, validate it, fix what it complains about, validate again, and only then create.** Two or three validate round-trips before a create is normal and correct, not wasteful.

Validate again after any edit, including ones that look harmless. Adding a link to an X post can push it over the limit on its own (see below).

### 3. `create_post`

Only after a clean validate. Pass an `Idempotency-Key` (see below). Then **read the response** — do not assume what happened.

## Scheduling, and how to post right now

`scheduled_at` is an ISO timestamp with an offset, and it is the publish moment — there is no separate "post now" flag.

**To publish immediately, pass the current time.** A timestamp slightly in the past is accepted and treated as due now (there is a few-minutes' grace, which also absorbs clock skew between you and the server); anything older than that is rejected as `SCHEDULED_AT_IN_PAST`. Do not try to fake immediacy by scheduling a minute or two ahead — that just makes the user wait.

Two things worth telling the user rather than letting them discover:
- Staging starts about **8 minutes before** `scheduled_at`, so a post scheduled sooner than that begins uploading right away. This is normal, not an early publish.
- "Immediately" still means *seconds to minutes*, not instant. The media has to be validated, uploaded to the platform and encoded by it before it goes live. A large video takes longer.

When the user gives a wall-clock time ("post at 11:30"), resolve **AM vs PM explicitly** and echo the full resolved timestamp back to them. Getting this wrong silently schedules a post 12 hours away, which reads to the user as a stuck upload rather than a mistake.

## Draft scope: read the response

API keys carry one of three scope presets: `read`, `draft`, `write`. `draft` is the default and the safe one.

With a **`draft`-scoped key, `create_post` saves a DRAFT and does not schedule it.** The post sits in the workspace for a human to review and approve. The response says so explicitly — its status is a draft status and there is no scheduled publish.

This means: never report "scheduled for 9am Tuesday" because you called `create_post` and got a 200. Read the returned status and tell the user what actually happened — "saved as a draft in PulsarSocial, approve it in the dashboard to schedule it." Getting this wrong makes the user think something is queued when it isn't.

A `write`-scoped key schedules and publishes for real. If the user's key is `write`, treat `create_post` as an irreversible action against their audience and confirm before firing.

## Per-platform rules that will bite you

`validate_post` enforces all of these. This list is here so you can get it right on the first attempt instead of the third.

### X (Twitter)
The limit is **280 weighted characters**, not 280 characters:
- Every URL counts as **23** characters regardless of its actual length. A long tracking URL and a short link cost exactly the same.
- CJK characters (Chinese, Japanese, Korean) and most emoji count as **2**.
- Latin text counts as 1.

So a 250-character draft plus one link is 273 and fits; plus two links it is 296 and does not. Never estimate this by eye — validate.

### YouTube
- Descriptions cap at **5,000 UTF-8 bytes**, not 5,000 characters. Emoji are 4 bytes each and accented Latin is 2, so a description that is comfortably under 5,000 characters can still be rejected. If a description is emoji-heavy, assume the byte count is much higher than the character count.
- Titles cap at 100 characters.

### Instagram
- Captions cap at **2,200 characters**.
- `post_and_story` is not one publish — it **forks into two independent targets**. Either can fail on its own, so the result can be partial: the feed post lands and the story doesn't. Report per-target results, not a single verdict.

### TikTok
- Requires an explicit **music-usage agreement flag** on the payload. There is no sensible default for it because it is a legal acknowledgement — if the user has not given it, ask, don't assume.
- If the workspace's TikTok app is **unaudited**, posts are restricted to **`SELF_ONLY` visibility**. Anything else is rejected. This is a TikTok platform restriction, not a PulsarSocial one, and it cannot be worked around.
- **`post_mode`** picks what "posting" means, and the two are genuinely different outcomes:
  - `"direct"` (default) publishes to the profile.
  - `"draft"` uploads the media to the creator's **TikTok inbox** and posts nothing. They get a notification, open the TikTok app, and finish the post themselves — choosing the caption, sound and privacy in TikTok's own editor.
- In `draft` mode TikTok **ignores** `privacy_level`, `disable_comment`, `disable_duet`, `disable_stitch`, `auto_add_music` and both brand toggles, because the creator sets all of that themselves. Sending them is harmless but they will not take effect — so never tell the user you set a privacy level on a TikTok draft.
- A TikTok draft reaches `PUBLISHED` in PulsarSocial once the media is **delivered to the inbox**, which is not the same as being live on TikTok. There is no permalink, because no post exists yet. Say "sent to your TikTok drafts — open TikTok to finish it", never "posted".
- `post_mode: "draft"` is unrelated to `is_draft` and to the `draft` key scope. `is_draft` parks a post inside PulsarSocial; `post_mode` decides what TikTok does once it *is* sent. A post can be one, both or neither.

### Pinterest
- Requires a **`board_id`**. A pin with no board has nowhere to go. Get valid boards from the account's entry in `list_accounts` before building the payload.

### Facebook
- Page posts only. Personal profiles are not publishable via the platform API.

## Quota is per post, not per target

One post fanned out to six platforms is **one** unit of quota. Six separate single-platform posts are six.

So when a user wants the same content on Instagram, TikTok, X, YouTube, Pinterest and Facebook, put all six targets in **one** `create_post` call. Splitting it into six calls costs 6× the quota for an identical outcome, and gives the user six calendar entries to manage instead of one.

Split into separate posts only when the *content itself* genuinely differs per platform — a different caption for X than Instagram, say. Per-target caption overrides are usually the better answer even then; check `validate_post` output before deciding you need separate posts.

Use `get_usage` to check remaining quota before a large batch.

## Idempotency: reuse the key on retry

Mutating calls accept an `Idempotency-Key`.

- Generate one fresh UUID per **logical** post.
- On a retry — timeout, 5xx, network error, tool error you're unsure about — **send the exact same key again**. The server recognises it and returns the original result instead of creating a second post.
- Generating a new key on retry is how you double-post to someone's real audience. This is the most damaging mistake available in this API, and it is entirely avoidable.

If a `create_post` fails ambiguously and you did not set an idempotency key, do **not** blindly retry. Call `list_posts` first and check whether it actually landed.

## Media

Two paths:

- **`ingest_media`** — hand it a public URL and PulsarSocial fetches it server-side. Cap is 100 MB. This is the easy path and covers most cases.
- **Upload URL flow** (`/media/upload-url` then `/media/register` in REST) — for larger files or bytes you hold locally.

`list_media` shows what is already in the workspace library. Check there before re-ingesting the same asset.

Media has its own per-platform constraints (aspect ratio, duration, codec). `validate_post` checks these too, which is another reason to validate before creating.

## Reading and fixing posts

- `list_posts` — keyset paginated. Responses are `{ data: [...], next_cursor, has_more }`. Follow `next_cursor` while `has_more` is true; do not assume page numbers.
- `get_post` — full detail including per-target status.
- `reschedule_post` — move a scheduled post. Prefer this over delete-and-recreate; it keeps history and costs no extra quota.
- `cancel_post` — stop a scheduled post from publishing, keep the record.
- `delete_post` — remove it entirely.

## Errors

Errors come back as `{ error, code, request_id }`. Quote the `request_id` to the user when reporting a failure they may need support for.

| Status | Meaning | What to do |
| --- | --- | --- |
| 401 | Key invalid or revoked | Stop. The user needs a new key from Settings → API keys. |
| 402 `PLAN_REQUIRED` | Plan limit or key cap hit | Stop. Retrying will not help. |
| 403 `INSUFFICIENT_SCOPE` | Key's scope doesn't cover this | Stop. Do not try a different tool to get around it — tell the user their key is read/draft scoped. |
| 404 | Unknown id, or an id from another workspace | Re-run `list_accounts` / `list_posts`; a stale id from earlier in the conversation is the usual cause. |
| 422 | Validation failed | Fix the payload and `validate_post` again. |
| 429 | Rate limited | Back off for `Retry-After` seconds. Limits are per key per minute: 20 / 60 / 120 / 300 by plan. |

401, 402 and 403 are terminal. Report them and stop; they will not resolve by trying again.

## Things to just know

- A key is scoped to **one workspace**. `organization_id` is never a request parameter — the key determines the workspace, and you cannot address another one.
- Times: always confirm the user's intended timezone before scheduling. "Tuesday at 9" is ambiguous and a wrong timezone means a post at 3am.
- API access is on every plan, free included. Plans differ by rate limit: 20/min on Hobby, then 60 / 120 / 300.
- Full docs: <https://getpulsarsocial.com/docs>

curl https://getpulsarsocial.com/api/v1/accounts \
  -H "Authorization: Bearer utsk_live_xxxxxxxxxxxx.your-secret-here"

curl https://getpulsarsocial.com/api/v1/posts/validate \
  -H "Authorization: Bearer utsk_live_xxxxxxxxxxxx.your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Launching Tuesday. Here is what changed.",
    "scheduled_at": "2026-08-04T09:00:00-05:00",
    "targets": [
      { "social_account_id": "acc_2f9…", "kind": "post" },
      { "social_account_id": "acc_7c1…", "kind": "post" }
    ]
  }'

curl https://getpulsarsocial.com/api/v1/posts \
  -H "Authorization: Bearer utsk_live_xxxxxxxxxxxx.your-secret-here" \
  -H "Idempotency-Key: 6f1c9e2a-4b77-4a10-9d3e-8f2b5c0a71de" \
  -H "Content-Type: application/json" \
  -d @post.json