# Postlia agent reference

This is the complete machine-readable reference for the Postlia REST API and
MCP server. It is written for AI agents and developers. Everything documented
here is checked against the live implementation.

- MCP server: https://postlia.com/api/mcp
- Short index: https://postlia.com/llms.txt
- Setup page for humans: https://postlia.com/mcp
- Agent skill source: https://github.com/mertkodzhaaslan/postlia-skills

## What Postlia is

Postlia is a social media publishing product. You write a post once and
Postlia publishes it to LinkedIn, Bluesky, Instagram, TikTok, Pinterest,
YouTube Shorts, and Mastodon, either immediately (within a few minutes), at a
chosen time, or in the next open slot of a posting queue. Every post gets a
per-platform delivery receipt with the platform's real error message when
something fails. Postlia also ships 25+ free social media tools.

## Getting an API key

1. Sign up free at https://postlia.com.
2. Go to Settings > Developers in the dashboard.
3. Create an API key. Keys start with `plk_`. You can hold up to 5 active
   keys. The full key is shown once at creation.

Send the key as a Bearer token on every request:

```
Authorization: Bearer plk_your_key_here
```

## Access model

Every plan, including the free tier, has full API and MCP access to every
endpoint and every tool. There are no per-endpoint scopes. What your plan
meters is POSTING VOLUME:

- Free (no card): 3 posts total, a lifetime taste.
- Trial (card on file, 7 days): 100 posts per month while the trial runs.
- Creator: 100 posts per month.
- Pro: unlimited posts.

A "post" is one piece of content, published or scheduled, regardless of how
many platforms it targets. Drafts cost no quota. When the quota is exhausted,
creating a post returns 402 with `upgrade: true` and an exact human-readable
message. Check your numbers any time with the get_posting_quota MCP tool.

## Error shapes

All error bodies are `{"error": string}` plus optional boolean flags:

- 401 `{"error": "Invalid API key"}` for ANY authentication failure (missing
  header, malformed key, unknown key, revoked key, lookup error). One uniform
  message on purpose.
- 402 quota exhausted, with `upgrade: true`.
- 409 `{"error": "Set up a posting schedule first.", "needsSchedule": true}`
  when queue mode is used without a posting schedule.
- 422 with `code: "char_limit"` and `platform` when content exceeds a target
  platform's character limit. The message states the platform and the limit.
- 429 `{"error": "Rate limit exceeded. Try again later."}`.

## Rate limits

120 requests per hour per key owner, shared across all authenticated v1
endpoints and MCP tool calls.

## Platform constraints

- Text posts publish via the API to: linkedin, bluesky, mastodon.
- instagram, tiktok, pinterest, youtube require media and are currently
  published from the Postlia app, not the API. Sending them to create_post
  returns 400 with a clear message. Their delivery, history and analytics are
  still fully readable through the API and MCP.
- Character limits are enforced per platform before any quota is spent.

## REST API v1

Base URL: `https://postlia.com`. All bodies are JSON.

### GET /api/v1/me
Sanity check for a key. Returns the key owner's plan context.

### GET /api/v1/accounts
Connected social accounts: `{"accounts": [{"id", "platform", "username"}]}`.
Post only to platforms that appear here.

### GET /api/v1/posts
Upcoming scheduled posts (status pending), ordered by time:
`{"posts": [{"id", "content", "platforms", "scheduled_at", "via_queue", "tag_ids"}]}`.

### POST /api/v1/posts
Create a post. Body:

```
{
  "content": "text of the post",        // required, 1-65000 chars
  "platforms": ["linkedin", "bluesky"], // required, text-capable + launched
  "scheduledAt": "2026-08-12T09:00:00Z",// optional ISO datetime, future
  "queue": true,                        // optional, next open queue slot
  "tagIds": ["uuid"]                    // optional, up to 5 owned tag ids
}
```

`scheduledAt` and `queue` are mutually exclusive. With neither, the post
publishes within about 5 minutes. Response: `{"id", "scheduledAt"}`. Keep the
id: it is how you verify delivery later.

### DELETE /api/v1/posts/{id}
Cancel a scheduled post (pending, failed or retrying). A post that is
mid-publish returns 409 and cannot be cancelled.

## MCP server

Endpoint: `https://postlia.com/api/mcp` (JSON-RPC 2.0 over streamable HTTP).
`initialize` and `tools/list` work without authentication (discovery);
`tools/call` requires the Bearer key. 14 tools:

### Posting
- `create_post` {content, platforms, scheduledAt?, queue?}: same semantics as
  POST /api/v1/posts above.
- `cancel_post` {id}: cancel a scheduled post.
- `reschedule_post` {id, scheduledAt}: move a PENDING post to a new future
  time.
- `update_post_content` {id, content}: rewrite a PENDING post's text; the
  same per-platform character limits are enforced.

### Verification (the part most social APIs do not have)
- `get_post_receipt` {id}: the delivery receipt. Accepts the id from
  create_post or from list_published_posts. Returns the post's status plus
  the append-only delivery event log: per platform, per attempt, the outcome
  (published, failed, retrying, pending), the platform's own post id when it
  landed, and the platform's real error text when it failed. Use this to
  VERIFY a post went live instead of assuming; report failures with the
  platform's own message, do not invent reasons.
- `list_published_posts` {limit?}: recent post history with per-post status
  (published, partial, failed) and any platform errors. limit 1-50,
  default 20.
- `get_posting_quota` {}: the exact quota the posting gates enforce: tier,
  used, limit, remaining. Check this BEFORE composing a batch.

### Workspace
- `list_accounts` {}: connected accounts and ids.
- `list_scheduled_posts` {}: upcoming pending posts.
- `get_queue_info` {}: the posting schedule (timezone, weekly slots) and the
  next open queue slots, i.e. when a queued post would actually publish.
- `list_drafts` {} / `create_draft` {content, platforms} / `delete_draft`
  {id}: drafts cost no posting quota; use them to stage ideas.

### Insight
- `get_analytics_summary` {days?}: post outcomes over the window (1-90 days,
  default 30): totals, published/partial/failed counts, per-platform volume,
  and recent platform errors.

Tool errors come back as MCP tool results with `isError: true` and the exact
human-readable message as text, never as JSON-RPC transport errors.

## Recommended agent workflow

1. `list_accounts` to learn what is connected. If a platform the user wants
   is missing, tell them to connect it at https://postlia.com/settings.
2. `get_posting_quota` before composing a batch.
3. `create_post` (queue: true for hands-off cadence, scheduledAt for exact
   times).
4. After the publish time, `get_post_receipt` with the returned id. Confirm
   per-platform success, or relay the platform's real error.
5. `get_analytics_summary` weekly to report outcomes.

## Setup snippets

Claude Code:

```
claude mcp add --transport http postlia https://postlia.com/api/mcp --header "Authorization: Bearer YOUR_KEY"
```

Any MCP client config:

```
{
  "mcpServers": {
    "postlia": {
      "type": "http",
      "url": "https://postlia.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}
```

OpenClaw skill:

```
clawhub skill install postlia
```

## Contact

- Support: https://postlia.com/contact
- Product: https://postlia.com