# Recipes for AI agents

Source: https://postninja.app/docs/mcp/recipes

Copy-paste prompts for the things people do most with PostNinja and an AI agent, with the tools each one uses. Replace the [brackets] with your details.

> **Tip:** Agents do better when they show you the plan before scheduling. Ending a prompt with "Show me first, then schedule it" costs one message and saves fixing posts later.

## Plan and schedule a week of posts

Turn a few notes into a full week across every account, with each platform's own version.

Prompt:

```text
Here's what we have going on next week: [notes]. Plan one post a day, Monday to Friday at 9am my time, for all my accounts. Use our brand voice. Write a short version for X (under 280 characters), add 3-5 hashtags on Instagram, and keep Threads conversational. Show me the plan first, then schedule it.
```

**Tools:** `list_accounts`, `get_workspace`, `create_post`

- Instagram, TikTok, YouTube and Pinterest need a photo or video. Text-only posts can go to X, Threads and Facebook; ask the agent to leave the others out or to wait for images.
- Times are sent as ISO 8601 with a time zone, so tell the agent your time zone if it doesn't know it.

## Fill the posting queue

Write a batch of posts and let the queue spread them over your weekly time slots, instead of picking times.

Prompt:

```text
Check my posting queue. If it has no slots, set Monday, Wednesday and Friday at 09:00 and Tuesday and Thursday at 17:30. Then write 8 evergreen tips about [topic] and add each one to the queue for my X and Threads accounts.
```

**Tools:** `get_queue`, `update_queue`, `list_accounts`, `create_post` (queue: true)

- Each queued post takes the next free slot of its accounts' profile, or the workspace's slots. Only owners, admins and API keys can change the slots.
- Changing a queued post keeps it in the queue (it can move up to an earlier free slot) unless you give it a time.

## Repurpose one video into Reels, TikTok and Shorts

Post one vertical video everywhere video works, with a caption written for each platform.

Prompt:

```text
I uploaded a video (media id [id]). Post it tomorrow at 6pm to Instagram as a Reel, to TikTok and to YouTube Shorts. Write a punchy Instagram caption with hashtags, a short TikTok caption, and a YouTube title under 100 characters with a 2-line description. For TikTok, ask me who can see it and whether it promotes my own brand.
```

**Tools:** `list_accounts`, `create_post` (platformContent, youtubeTitle, tiktok)

Upload the video first:

```bash
curl "https://postninja.app/api/v1/media?width=1080&height=1920&durationMs=42000" \
  -H "Authorization: Bearer $POSTNINJA_API_KEY" \
  -H "Content-Type: video/mp4" \
  --data-binary @reel.mp4
```

- Upload the video with `POST /api/v1/media` (the MCP `upload_image` tool takes images only) and pass `?width=&height=&durationMs=` so length and shape are checked up front.
- YouTube Shorts need exactly one vertical or square video up to 3 minutes; TikTok videos run 3 seconds to 10 minutes; a single Instagram video is published as a Reel (3 seconds to 15 minutes).
- Add `youtubeThumbnailId` (an uploaded photo under 2 MB) for a custom thumbnail, and `tiktok.coverTimestampMs` to choose the TikTok cover frame.

## Write an X thread with images

Turn an article or announcement into a thread, with photos on the posts that need them.

Prompt:

```text
Turn this blog post into an X thread of 5-7 posts, each under 280 characters, and schedule it for Thursday at noon on my X account. Attach the chart I uploaded (media id [id]) to the third post. [paste the article]
```

**Tools:** `upload_image`, `create_post` (xThread)

- The first post is the X text (`platformContent.x` or `content`); `xThread` holds the follow-ups. Give a follow-up its own photos with `{ "text": "…", "mediaIds": ["…"] }`.
- Every post in a thread costs credits like a single X post (more if it has a link). See [Plans, credits and limits](https://postninja.app/docs/limits).

## Add first comments

Keep links and hashtags out of the caption by posting them as the first comment.

Prompt:

```text
Schedule this Instagram and Facebook post for Saturday at 10am, and put the shop link and our hashtags in the first comment instead of the caption: [text]
```

**Tools:** `create_post` (firstComment)

- First comments are posted on X (as a reply, billed like a post), Instagram (not Stories), Facebook, Threads and YouTube. Other platforms skip it.

## Instagram Story tonight

Post a single photo or short video as a Story.

Prompt:

```text
Post this photo to my Instagram as a Story tonight at 7pm.
```

**Tools:** `upload_image`, `create_post` (instagramFormat: story)

- Stories take exactly one photo or a 3-60 second video. Instagram doesn't show captions on Stories.

## Bulk-create posts from a list

Schedule many posts at once from a spreadsheet, a list of products or a content calendar.

Prompt:

```text
Here's a list of 20 products with names, prices and links: [list]. For each one, write a short post and schedule them one a day at 11am starting Monday on X, Threads and Facebook. Skip weekends. Save any you're unsure about as drafts instead.
```

**Tools:** `list_accounts`, `create_post` (one call per post)

- There's no batch endpoint: the agent calls `create_post` once per post. Each key or app can make 120 calls a minute.
- Prefer a file? The **Import posts** page in PostNinja (`/posts/import`) creates posts from a CSV.

## Write in a profile's brand voice with templates

Use a ready-made template and the right brand voice for each client or brand.

Prompt:

```text
Find a template for a restock announcement. Fill it in for Fern & Clay's speckled mugs (40 made, link fernandclay.com/mugs) in that profile's brand voice, and schedule it for Friday at 9am on Fern & Clay's accounts.
```

**Tools:** `list_templates`, `list_profiles`, `get_workspace`, `create_post`

- A profile's brand voice wins for its accounts; otherwise use the workspace's (`get_workspace`). Drop lines whose optional blanks you leave empty.

## Agency: work client by client

Keep every client's posts, voice and queue separate.

Prompt:

```text
List my profiles. For each client, tell me what's scheduled next week and flag any day with nothing planned. Then draft two posts for each empty day in that client's brand voice, and save them as drafts for review.
```

**Tools:** `list_profiles`, `list_posts` (profileId), `create_post` (draft: true)

- Give each client's automation an API key limited to that profile: it only sees and posts to that client's accounts.
- Each profile can have its own queue slots (`update_queue` with its `profileId`).

## Review and approve what the team submitted

Go through posts waiting for approval, approve the good ones and send the rest back with notes.

Prompt:

```text
Show me every post waiting for approval with its text, accounts and time. I'll tell you which to approve. For the others, ask for changes with my notes.
```

**Tools:** `list_posts` (status: awaiting_approval), `get_post`, `approve_post`, `request_changes`

- Only owners and admins can approve or ask for changes (API keys count as admins). The author is emailed the note.
- Approving a post whose time has passed sends it right away.

## Weekly analytics report

A short report of what worked, what didn't, and what to post next.

Prompt:

```text
Give me a report for the last 7 days compared with the week before: impressions, engagements, engagement rate and follower growth per account, the top 3 posts and why they might have worked, and 3 ideas for next week based on them.
```

**Tools:** `get_analytics`, `get_post`

- Dates are UTC days (`YYYY-MM-DD`); without them you get the last 30 days. Up to 366 days at a time.
- X posts have no stats in PostNinja. Ask the agent to note that rather than read zeros as a bad week.
- For the best times to post, look at the **Best time** card on the dashboard; there's no API for it yet. The `publishedAt` of top posts is a useful hint.

## Reply to comments

Clear the comments that need an answer, in your voice.

Prompt:

```text
Show me Instagram and Facebook comments that need a reply. Draft an answer for each in our brand voice. Send the ones I approve.
```

**Tools:** `list_comments` (filter: needs_reply), `list_comments` (commentId), `reply_to_comment`

- The inbox covers Instagram, Facebook Pages, Threads and YouTube. Replies are public and sent as the account the comment was left on.
- Have the agent show you replies before sending: replying can't be undone from here.

## Answer direct messages

Answer the Instagram and Facebook messages that are waiting, before the reply window closes.

Prompt:

```text
Show me Instagram and Facebook messages that need a reply, soonest-closing reply window first. Draft an answer for each in our brand voice and send the ones I approve.
```

**Tools:** `list_messages` (filter: needs_reply), `list_messages` (conversationId), `get_workspace`, `reply_to_message`

- Instagram and Messenger only let businesses answer within 24 hours of the person's last message. `window.closesAt` says when; after that `reply_to_message` is refused until they write again.
- Messages are private and sent as the account they were sent to. Instagram messages can be up to 1,000 bytes (emoji count as several).
- For automation, subscribe a webhook to `message.received` and answer from your own code with `POST /api/v1/inbox/messages/:id/reply`.

## Check failed posts and fix them

Find out what didn't go out and why, then get it out.

Prompt:

```text
Which posts failed or only partly went out this week? For each, tell me the account and the error in plain words, and suggest a fix. If the fix is in the post itself, create a corrected post for the accounts that failed.
```

**Tools:** `list_posts` (status: failed / partial), `get_post`, `list_accounts`, `create_post`

- Each target has its own `error`. `needs_reconnect` on an account means it has to be reconnected in the app first.
- There's no retry tool yet: either create a corrected post for the failed accounts, or open the post in PostNinja and click **Retry**. Original files are kept for 30 days after a failure.

## Set up webhooks for automation

Get a signed request in n8n, Zapier, Make or your own server whenever something happens.

Prompt:

```text
I want a Slack message whenever a post fails or an account needs reconnecting. Write an n8n workflow with a Webhook trigger that checks the PostNinja-Signature header, then posts to Slack.
```

**Tools:** REST API: POST /api/v1/webhooks

Create the endpoint:

```bash
curl -X POST "https://postninja.app/api/v1/webhooks" \
  -H "Authorization: Bearer $POSTNINJA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://n8n.example.com/webhook/postninja",
    "description": "Slack alerts",
    "events": [
      "post.failed",
      "account.needs_reconnect"
    ]
  }'
```

- Webhooks are managed with the REST API or under **Settings → API → Webhooks**, not over MCP. The signing secret is shown once.
- See [Webhooks](https://postninja.app/docs/webhooks) for events, the payload and signature checks.

## Announce releases from your repo

From a coding agent (Claude Code, Cursor, Codex), post about what you just shipped.

Prompt:

```text
Read CHANGELOG.md and schedule a launch post for tomorrow at 9am on X and Threads, with a shorter X version. Save a longer Facebook version as a draft.
```

**Tools:** `list_accounts`, `create_post`