# Postcrow

> Postcrow schedules and publishes social media posts for one or many brands, from a web app or from any AI assistant through MCP or plain HTTP.

Each brand is a project with its own connected accounts, posts, brand voice, timezone and posting slots. Connecting a social account happens in the browser at https://postcrow.app/app/accounts; everything else can be done by an assistant.

## Connect an assistant

- MCP server (Streamable HTTP): https://postcrow.app/api/mcp
- Authentication: `Authorization: Bearer <API key>` (create a key at https://postcrow.app/app/settings), or OAuth 2.1 with dynamic client registration for clients that cannot send headers (discovery: https://postcrow.app/.well-known/oauth-protected-resource/api/mcp)
- Plain HTTP: POST https://postcrow.app/api/v1/tools/<tool name> with the arguments as a JSON body
- OpenAPI 3.1: https://postcrow.app/openapi.json (tools as paths, outgoing webhooks under `webhooks`)
- MCP server card: https://postcrow.app/.well-known/mcp/server-card.json
- API catalog (RFC 9727): https://postcrow.app/.well-known/api-catalog
- Setup for each client (Claude, ChatGPT, Codex, Cursor, VS Code, Gemini CLI and more): https://postcrow.app/mcp
- Retries: send `Idempotency-Key: <uuid>` on a write call to /api/v1/tools. A retry with the same key within 24 hours returns the first answer (header `Idempotent-Replayed: true`) instead of scheduling twice; the same key with another body is refused (422).
- Media: `media_urls` take public https URLs. To host a file on Postcrow first, POST it as multipart/form-data (fields `file` and `project_id`) to https://postcrow.app/api/social/upload with the same Bearer key; the answer's `url` goes in `media_urls`. Images up to 10 MB, videos up to 50 MB.

The MCP server and the HTTP API are part of every paid plan: Pro, Agency and Platform (the 14-day trial counts). Platform raises the request ceiling to 600 a minute per key and 1,200 per account (120 and 240 on the other plans). On Free, tool calls return an error with an upgrade link; the web app itself has a free plan.

## Webhooks (Platform plan)

Register an https URL with `postcrow_webhooks` (action create; the signing secret is returned once). Postcrow then POSTs a JSON event `{ id, event, created_at, data }` to it:

- `post.published`: a post went out on every network it targeted. `data.post` and `data.networks` (per network: success, url, post_id, error).
- `post.partial`: some networks published, some failed.
- `post.failed`: every network failed, after the automatic retries.
- `account.disconnected`: an account needs reconnecting (`data.account`, `data.reconnect_url`).
- `webhook.test`: sent by action test.

Verify each request: `X-Postcrow-Signature` is `v1=` followed by the hex HMAC-SHA256 of `<X-Postcrow-Timestamp>.<raw body>` with the secret; reject a timestamp more than 5 minutes old. Answer 2xx within 5 seconds. Timeouts, 408, 429 and 5xx are retried with backoff (7 attempts over about 33 hours); other 4xx are not. Delivery is at least once: dedupe on `X-Postcrow-Event-Id`. Action deliveries lists recent attempts and redeliver sends one again. After 20 failed deliveries in a row an endpoint is switched off until it is turned back on.

## Networks

Open to everyone today (14): YouTube, LinkedIn, Bluesky, Telegram, Dailymotion, Mastodon, Discord, DEV, Hashnode, PeerTube, Kick, Tumblr, WordPress.com and DeviantArt. Facebook, Instagram, X, Pinterest, TikTok and Reddit open once each platform has approved Postcrow; the other networks the tools mention (self-hosted WordPress, Ghost, Blogger, Hatena Blog, Vimeo, SoundCloud, Flickr and more) are not open yet. `postcrow_network_rules` gives the live status for the caller.

Postcrow's own AI writing (AI captions, brand voice training, cross-brand campaigns, auto-recycle) is not switched on yet. Write the posts yourself and send them with the posting tools.

## Tools

- `postcrow_network_rules`: Network rules. Every network Postcrow can publish to, in short: whether it is open for connection on this server, its text limit (and the shorter limit with media), how many images and videos it takes, whether it requires a video, and whether the first line becomes the title.
- `postcrow_platform_constraints`: Platform constraints. Read this before adapting content.
- `postcrow_publish_article`: Publish an article. Publish one long article to blogs (WordPress.com, self-hosted WordPress, Ghost, Blogger, Hatena Blog): title, body in Markdown or HTML, excerpt, featured image, tags, and whether the blog publishes it, keeps it as a draft, or publishes it at publish_at.
- `postcrow_publish_media`: Publish a video, track or image. Upload one file to media networks (Vimeo and SoundCloud: a video, MP4 for SoundCloud; Flickr: a photo or a video; DeviantArt: an image) with a title, description, tags and privacy.
- `postcrow_list_projects`: List brands. List the user's projects.
- `postcrow_list_accounts`: List connected accounts. List the social accounts connected to a project: network, account name, active status and token health.
- `postcrow_list_posts`: List posts. List posts in a project, optionally filtered by status (draft, scheduled, publishing, published, failed).
- `postcrow_get_post`: Get a post. One post by id: status (draft, scheduled, publishing, published, failed), content, networks, scheduled_at, published_at, and per network whether it went out, its link and the error if it failed.
- `postcrow_validate_post`: Validate a post. Check a post before saving it, without saving or counting anything: every problem that would stop it from being scheduled (text too long, missing video or image, a field a network requires, a network not connected on the brand, a time in the past, no posting slots for queue), all at once, per network.
- `postcrow_create_draft`: Create a draft. Save a post as a draft, without scheduling it.
- `postcrow_schedule_post`: Schedule a post. Schedule a post for an exact future time.
- `postcrow_queue_post`: Queue a post. Add a post to a brand's queue: the server picks the next free slot from the project's posting schedule, so several posts queued in a row land on consecutive slots.
- `postcrow_update_post`: Update a post. Change a draft or scheduled post: content, networks, media or time.
- `postcrow_publish_now`: Publish now. Publish a draft or scheduled post right now, on every selected network.
- `postcrow_delete_post`: Delete a post. Delete a post from Postcrow.
- `postcrow_reorder_queue`: Reorder the queue. Move a scheduled post one place up or down in its brand's queue.
- `postcrow_recycle_post`: Recycle a post. Copy a published post to a new date (or to drafts with scheduled_at null).
- `postcrow_top_posts`: Top posts. The best published posts of a project by engagement (likes + 2 x comments + 3 x shares), from the figures Postcrow already collected.
- `postcrow_cross_project_overview`: All brands overview. Everything scheduled across ALL the user's projects in a date window, as one timeline.
- `postcrow_bulk_schedule`: Bulk schedule. Schedule up to 200 posts for one project, spread evenly between from and to.
- `postcrow_ai_compose`: Write drafts with Postcrow AI. Postcrow's own writer: one brief in, one draft per network out, each fitted to that network's tone and limit, in the project's trained brand voice when project_id is given. Not switched on yet: it cannot write anything for now.
- `postcrow_smart_recycle`: Rewrite top posts. Take a project's best published posts and write one fresh variation of each, in the brand voice. Not switched on yet: it cannot write anything for now.
- `postcrow_campaign`: Cross-brand campaign. One brief, many brands: for each project the post is written in that project's brand voice and scheduled (or saved as drafts with dry_run). Not switched on yet: it cannot write anything for now.
- `postcrow_campaign_status`: Campaign status. Progress and per-brand results of a campaign, or the list of recent campaigns when job_id is omitted.
- `postcrow_connect_link`: Link to connect an account. Connect a social account to a brand.
- `postcrow_create_project`: Create a brand. Create a project (a brand).
- `postcrow_project_settings`: Brand settings. Read (only project_id) or change a project's name, description, timezone and weekly posting slots.
- `postcrow_next_slots`: Next free slots. The next free posting slots of a project (taken slots skipped), as ISO timestamps.
- `postcrow_client_report`: Brand report. A project's report over a window: totals, per-network split, publishing rhythm, top posts and what is scheduled next.
- `postcrow_client_link`: Client report links. Read-only report links for a client, no account needed.
- `postcrow_webhooks`: Outgoing webhooks. Outgoing webhooks (Platform plan): Postcrow POSTs a signed JSON event to your https URL when a post is published (post.published), partly published (post.partial) or failed (post.failed), or when an account needs reconnecting (account.disconnected).

## Pages

- Plans and prices (Free $0, Pro $19, Agency $79, Platform $199 a month, same figures in EUR): https://postcrow.app/pricing
- For agencies and anyone running many clients (flat price, compared with Buffer and Metricool): https://postcrow.app/agencies
- Each open network, its limits and how to connect it: https://postcrow.app/integrations
- Comparisons with Buffer, Hootsuite, Later, Publer, Metricool and Postiz (sourced, dated): https://postcrow.app/compare
- Free post length checker for the 14 open networks: https://postcrow.app/tools/post-length-checker

## Rules for writing posts

- Before scheduling, `postcrow_validate_post` returns every problem at once without saving anything; `postcrow_get_post` follows a post afterwards.
- Call `postcrow_platform_constraints` first: for each network the brand has connected, the text limit and how it is counted, media formats and sizes, and the fields it accepts or requires.
- Write one version per network and send them together: `per_network` on the posting tools; `postcrow_publish_article` for WordPress, Ghost, Blogger and Hatena Blog (title, Markdown or HTML body, excerpt, featured image, tags, draft or scheduled on the blog; only WordPress.com is open today); `postcrow_publish_media` for Vimeo, SoundCloud, Flickr and DeviantArt (file, title, description, tags, privacy; only DeviantArt is open today).
- A post can only target networks connected on its project (`postcrow_list_accounts`).
- Prefer drafts or scheduling; confirm with the user before `postcrow_publish_now`.
- Times are ISO 8601; read the project's timezone before turning "tomorrow 9am" into a timestamp.
