# PostNinja developer docs

Source: https://postninja.app/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.

## Use these docs with your AI agent

Every docs page is also plain Markdown: add `.md` to its address (this page: https://postninja.app/docs/index.md), or use "Copy page as Markdown". All pages together are at https://postninja.app/llms-full.txt. Paste either into your agent, or tell it:

```text
Read https://postninja.app/llms-full.txt and set up PostNinja for me.
```

## 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 server | REST API |
| --- | --- | --- |
| For | AI agents: Claude, ChatGPT, Cursor, Codex, Gemini, Grok and others | Your code, scripts and automation tools (n8n, Make, Zapier) |
| Address | `https://postninja.app/api/mcp` | `https://postninja.app/api/v1` |
| Sign-in | Sign in with your account (OAuth), or an API key | An API key |
| Docs | [Connect an agent](https://postninja.app/docs/mcp), [Tools](https://postninja.app/docs/mcp/tools), [Recipes](https://postninja.app/docs/mcp/recipes) | [API reference](https://postninja.app/docs/api), [Webhooks](https://postninja.app/docs/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](https://postninja.app/docs/mcp). For Claude Code it's one command:

Terminal:

```bash
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](https://postninja.app/docs/mcp/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:

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

### 3. Schedule a post

POST /api/v1/posts:

```bash
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](https://postninja.app/docs/platforms).

## Where to next

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