PostNinja
Docs menu · Overview

Get started

PostNinja developer docs

Schedule and publish posts to X, Instagram, Threads, Facebook, TikTok, YouTube and Pinterest from an AI agent over MCP, or from your own code with the REST API. Both run the same rules as the app, so a post they accept is a post that can go out.

View as Markdown

Use these docs with your AI agent

Every page here is also plain Markdown. Paste /llms-full.txt (all pages in one file) or a page's Markdown into your agent, or just tell it:

Read https://postninja.app/llms-full.txt and set up PostNinja for me.
Open llms-full.txtThis page as Markdown

What you can do

  • Create posts for any mix of connected accounts: schedule them, publish now, save drafts, or drop them into the next free slot of your posting queue.
  • Write per platform: one text for every platform, or a different version for each (a short X post, hashtags on Instagram).
  • Use every format: photo and video uploads, X threads with their own photos, Instagram Stories, TikTok privacy and disclosure settings, YouTube titles and thumbnails, and first comments.
  • Work as a team: profiles (one per client or brand) with their own brand voice, post templates, and approvals for members' posts.
  • See results: analytics for a date range, an inbox of comments and Instagram and Facebook direct messages you can reply from, and webhooks that tell your systems when posts go out or fail.

Two ways in

MCP serverREST API
ForAI agents: Claude, ChatGPT, Cursor, Codex, Gemini, Grok and othersYour code, scripts and automation tools (n8n, Make, Zapier)
Addresshttps://postninja.app/api/mcphttps://postninja.app/api/v1
Sign-inSign in with your account (OAuth), or an API keyAn API key
DocsConnect an agent, Tools, RecipesAPI reference, Webhooks

Quick start: AI agent

1. Get access

Apps that sign in (ChatGPT, Claude.ai and Claude Desktop connectors, the Gemini and Grok apps) only need the server URL, https://postninja.app/api/mcp: you log in and click Allow. For everything else, create an API key under Settings → API in PostNinja.

2. Add the server to your agent

The setup for each agent is on Connect an AI agent. For Claude Code it's one command:

Terminal
claude mcp add --transport http postninja https://postninja.app/api/mcp \
  --header "Authorization: Bearer $POSTNINJA_API_KEY"

3. Ask

Start with "List my connected accounts", then try "Schedule a post about our launch for tomorrow at 9am on X and Threads, with a shorter X version." More ideas: Recipes.

Quick start: REST API

1. Create an API key

Under Settings → API in PostNinja (owners and admins can). It's shown once; keep it secret, e.g. in POSTNINJA_API_KEY.

2. Get your account ids

GET /api/v1/accounts
curl "https://postninja.app/api/v1/accounts" \
  -H "Authorization: Bearer $POSTNINJA_API_KEY"

3. Schedule a post

POST /api/v1/posts
curl -X POST "https://postninja.app/api/v1/posts" \
  -H "Authorization: Bearer $POSTNINJA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Dark mode is here. Turn it on in Settings.",
    "accountIds": [
      "3f2c8a10-6d1e-4b7a-9c55-1e2f3a4b5c6d",
      "8b7e1d22-0c4f-4e8a-a1b2-9d8c7b6a5f40"
    ],
    "mediaIds": [
      "5b9d1c2e-3f4a-4b5c-9d6e-7f8a9b0c1d2e"
    ],
    "scheduledAt": "2026-10-12T09:00:00Z"
  }'

Note: Instagram, TikTok, YouTube and Pinterest posts need a photo or video. Upload it first with POST /api/v1/media and pass its id in mediaIds. See Platform rules.

Where to next

Connect an AI agent →Setup for Claude, ChatGPT, Cursor, Codex, Gemini, Grok, Windsurf and more.MCP tools →Every tool with its parameters, an example call and its result.Recipes →Copy-paste prompts for a week of posts, threads, approvals, reports and more.REST API →Authentication, errors and every endpoint with curl examples.Webhooks →Events, payloads and signature checks for your automations.Platform rules →Text limits, media rules and the options each platform takes.Plans, credits and limits →What each plan includes, what X posts cost, and rate limits.