# PostLake

> PostLake is the social media API for AI agents. One integration publishes,
> schedules, and measures posts across every major network (X, LinkedIn, Instagram,
> TikTok, Facebook, Threads, Bluesky, YouTube, Pinterest) and returns one
> normalised response shape an agent can reason over — never per-platform
> branching. Base URL: https://api.postlake.dev — Auth: Bearer <api_key>.

Three ways to use PostLake, all sharing the same accounts and responses:
1. **Agent skills** — `npx skills add postlake/postlake-mcp --all` drops
   five ready skills (accounts, publish, schedule, media, analytics) into a
   coding agent. Set `POSTLAKE_API_KEY` and it can post.
2. **Hosted MCP server** — point any MCP client at `https://api.postlake.dev/mcp`
   and approve once over OAuth. Tools: `whoami`, `list_social_accounts`,
   `list_account_targets`, `list_profiles`, `get_platform_capabilities`,
   `get_publish_info`, `validate_post`, `upload_media`, `create_post`,
   `get_post`, `list_posts`, `edit_post`, `cancel_post`, `get_post_analytics`,
   `get_analytics`.
3. **REST API** — call `https://api.postlake.dev/v1` from any language with a
   Bearer key.

## Rules an agent should know
- Every request needs `Authorization: Bearer <api_key>`. Keys are secret
  (`sk_live_…`), server-side only.
- One `POST /v1/posts` call fans out to many accounts. The response has one
  post `id`, a post-level `state` (`queued`, `scheduled`, `processing`,
  `partial`, `published`, `failed`) and a `targets[]` array — one entry per
  account with its own `state` and live `url`. Always check per-target state:
  one target can fail while the others publish (post state `partial`).
- Address destinations the simple way: `"profile": "my-brand"` posts to every
  account in that profile; add `"platforms": ["bluesky", "x"]` to narrow it.
  Or pass explicit `"accounts": ["acc_…"]` ids. Provide either or both.
- Validate before you publish: `POST /v1/posts/validate` runs the exact
  pre-publish checks (caption limits, media rules, option values) without
  touching any platform and returns per-target warnings. It is free.
- Don't hard-code platform limits: `GET /v1/platforms` (or `/{platform}`)
  returns each network's current max characters, media rules, and the valid
  `platformOptions` — validate against that.
- Async platforms (e.g. TikTok, Instagram Reels) return `processing` first and
  flip to `published` shortly after; poll `GET /v1/posts/{id}` or register a
  webhook rather than treating `processing` as failure.
- Send an `Idempotency-Key` header on writes; retries with the same key are
  safe and return the original post instead of double-posting.
- Errors always come as `{ "error": { "type", "message", "retryable",
  "platform"? } }`. If `retryable` is true, back off and retry; publishing is
  rate-limited to 60 requests/minute per account (429 + `Retry-After`).
- Credits: 1 credit per published platform post; X costs 5 (55 if the caption
  contains a link). Only posts that actually publish are charged — a failed
  target costs nothing. The free tier has 20 credits/month; on free, X and
  TikTok post ONLY from purchased credit packs (free monthly credits never
  fund them) — any paid plan lifts the restriction. Paid plans start at
  $13/month for 2,000 credits; one-time credit packs never expire.

## Composing posts (POST /v1/posts)
- `text` is the master caption. `textOverrides` swaps it per platform
  (e.g. a short X version) while every other network keeps `text`.
- `media` is a list of uploaded `med_…` ids shared by all targets;
  `mediaOverrides` gives one platform its own media (e.g. a vertical video for
  TikTok). `mediaAlt` / `mediaAltOverrides` carry accessibility alt text.
- `firstComment` posts a reply the moment the post is live (X, Bluesky,
  LinkedIn, Threads, Facebook, YouTube) — the classic place for hashtags and
  links. Platforms that don't support it (including Instagram) simply skip it.
  `firstCommentOverrides` varies it per platform.
- `scheduledAt` (ISO-8601 UTC) schedules instead of publishing now. Edit a
  scheduled post with `PATCH /v1/posts/{id}`, cancel with `DELETE`.
- `platformOptions` carries per-network settings. TikTok direct posts REQUIRE
  `tiktok.privacyLevel` (no default — TikTok's rule; valid values come from
  `GET /v1/social-accounts/{id}/publish-info`). Pinterest takes `boardId`,
  `link`, `altText`.

## Docs as markdown
Every documentation page has a plain-markdown twin — append `.md` to its path.
Fetch these directly; they are token-cheap and served as text/plain:
- https://postlake.dev/docs/quickstart.md — create a key, connect, publish, schedule
- https://postlake.dev/docs/authentication.md — API keys and auth
- https://postlake.dev/docs/publishing.md — posts, fan-out, per-target results
- https://postlake.dev/docs/scheduling.md — scheduledAt, editing, cancelling
- https://postlake.dev/docs/media.md — uploads, images, video rules
- https://postlake.dev/docs/analytics.md — post + cross-platform analytics
- https://postlake.dev/docs/webhooks.md — events and signature verification
- https://postlake.dev/docs/errors.md — error envelope and retries
- https://postlake.dev/docs/platforms.md — per-network capabilities and limits
- https://postlake.dev/docs/mcp.md — the hosted MCP server and client setup
- https://postlake.dev/docs/agent-skills.md — drop-in skills for coding agents
- https://postlake.dev/docs/api.md — endpoint reference generated from the OpenAPI spec
- https://postlake.dev/docs/faq.md — common questions

## Getting started
- [Introduction & first post](https://postlake.dev/docs/quickstart.md): create a key, list accounts, publish, add media, schedule — the whole REST flow with curl.
- [API keys & auth](https://postlake.dev/docs/authentication.md): how keys work and how to authenticate a request.
- [OpenAPI spec](https://api.postlake.dev/openapi.json): the full machine-readable API description.

## Endpoints
- `GET  /v1/me`: validate a key, see the account.
- `GET  /v1/platforms` · `GET /v1/platforms/{platform}`: live capabilities per network — limits, media rules, valid options.
- `GET  /v1/social-accounts`: list connected accounts (each has an `id` and `platform`).
- `GET  /v1/social-accounts/{id}/targets`: sub-destinations within one account (Pinterest boards, Facebook pages).
- `GET  /v1/social-accounts/{id}/publish-info`: creator-level constraints (e.g. a TikTok creator's allowed privacy levels).
- `GET  /v1/profiles` · `POST /v1/profiles`: named groups of accounts ("my-brand") you can post to by name.
- `POST /v1/posts`: publish now, or schedule with `scheduledAt`. Fans out to profile/accounts.
- `POST /v1/posts/validate`: dry-run the exact publish validation — free, no platform calls.
- `GET  /v1/posts` · `GET /v1/posts/{id}`: list posts / fetch one with per-target state.
- `PATCH /v1/posts/{id}` · `DELETE /v1/posts/{id}`: edit / cancel a scheduled post.
- `POST /v1/media`: upload an image or video, get a `med_…` id to attach to a post.
- `GET  /v1/posts/{id}/analytics`: normalised metrics for one post, per target.
- `GET  /v1/analytics?period=30d`: cross-platform analytics (`7d`/`30d`/`90d`) in one normalised response.
- `POST /v1/webhooks` · `GET /v1/webhooks` · `DELETE /v1/webhooks/{id}`: register endpoints for `post.published`, `post.partial`, `post.failed`, `post.processing`, `account.connected`. Deliveries are HMAC-signed (`postlake-signature`).
- `POST /v1/credentials` · `GET /v1/credentials` · `DELETE /v1/credentials/{platform}`: bring your own platform app keys (BYOK / white-label).

## AI agents
- [Connect an agent (MCP)](https://postlake.dev/docs/mcp.md): add `https://api.postlake.dev/mcp` as an MCP server; per-client setup for Claude, ChatGPT, Cursor, Gemini, Copilot.
- [Agent skills](https://postlake.dev/agents/): the drop-in skills and the one-command install.
- [Skills source](https://github.com/postlake/postlake-mcp): the public SKILL.md files behind `npx skills add postlake/postlake-mcp --all`.

## Platform support
- [What each platform supports](https://postlake.dev/docs/platforms.md): text/media/limits and live-vs-rolling-out status per network.
- Connectable today: Bluesky, LinkedIn, YouTube. The remaining networks are
  rolling out as each completes its platform review — the platforms page tracks
  status.
- X and TikTok publishing need a paid plan or a purchased credit pack; every other network works on free credits.

## Reference
- [Pricing](https://postlake.dev/pricing): credit model, tiers, and packs. Free 20 credits/mo; paid from $13/mo (2,000 credits); annual saves 25%.
- [Full API documentation](https://postlake.dev/docs/): human-readable guides plus the generated endpoint reference.