# PostLake API reference

> Markdown version of https://postlake.dev/docs/api — canonical page for humans.
> Machine-readable spec: https://api.postlake.dev/openapi.json

Base URL: `https://api.postlake.dev` — every request needs `Authorization: Bearer <api_key>`.

## GET /v1/me

Get current account. Validate API key and echo account info

## GET /v1/account/export

Export account data. GDPR data export. All data for the account (no secrets).

## GET /v1/audit

Get audit log. Security audit trail (logins, key creation, disconnects). Returns up to 100 events.

## POST /v1/social-accounts/connect

Connect social account. Connect a social account to PostLake

Request body (JSON):

- `platform` (object, required)
- `profile` (string) — Optional profile username to attach to
- `handle` (string) — Platform-specific handle
- `appPassword` (string) — Platform-specific password (e.g. for Bluesky)

## GET /v1/social-accounts

List social accounts. List connected social accounts. Cursor-paginated.

Parameters:

- `profile` (query) — Filter by profile username
- `limit` (query) — Page size, 1-100 (default 50).
- `cursor` (query) — Opaque cursor from the previous response's `nextCursor`.

## GET /v1/social-accounts/{id}/targets

List social account targets. List postable destinations within an account (Pinterest boards, FB Pages)

Parameters:

- `id` (path, required)

## POST /v1/profiles

Create profile. Create a named profile

Request body (JSON):

- `username` (string, required)

Returns: `Profile`.

## GET /v1/profiles

List profiles. List profiles

## GET /v1/platforms

Platform capabilities (public). Machine-readable capabilities per platform: character limits, media rules (required / video-only / max images / formats / sizes), whether publishing is asynchronous, and every platformOptions field with its valid values. No authentication required.

## GET /v1/platforms/{platform}

One platform's capabilities (public).

Parameters:

- `platform` (path, required)

Returns: `PlatformCapabilities`.

## POST /v1/posts/validate

Validate a post (dry run). Runs the exact validation a publish would run — account resolution, media resolution, capability-registry rules — without touching any platform. Returns per-target errors (blocking) and warnings (advisory). Free to call before POST /v1/posts.

Request body (JSON):

- `text` (string, required)
- `profile` (string) — A profile name — resolves to every account it owns. The simple way to address accounts; combine with `platforms` to narrow it. Provide `profile`, `accounts`, or both.
- `platforms` (array) — Optional filter — keep only these networks from the resolved set.
- `accounts` (array) — Connected account ids (acc_…). An alternative (or addition) to `profile`.
- `media` (array)
- `scheduledAt` (string)
- `platformOptions` (object)

## GET /v1/social-accounts/{id}/publish-info

Creator-level publish constraints. Live constraints for one connected account (TikTok creator_info): available privacy options, whether comments/duet/stitch are allowed, and this creator's max video duration. Render post UIs from this. 404 for platforms without creator-level constraints.

Parameters:

- `id` (path, required)

## POST /v1/posts

Publish or schedule post. Publish or schedule a post

Request body (JSON):

- `text` (string, required)
- `profile` (string) — A profile name — resolves to every account it owns. The simple way to address accounts; combine with `platforms` to narrow it. Provide `profile`, `accounts`, or both.
- `platforms` (array) — Optional filter — keep only these networks from the resolved set (e.g. profile "my-brand" + platforms ["bluesky"]).
- `accounts` (array) — Connected account ids (acc_…). An alternative (or addition) to `profile`.
- `media` (array)
- `scheduledAt` (string)
- `platformOptions` (object)

Returns: `Post`.

## GET /v1/posts

List posts. List posts (most recent first)

Parameters:

- `state` (query)
- `limit` (query)
- `cursor` (query)

## GET /v1/posts/{id}

Get post. Get a single post by id

Parameters:

- `id` (path, required)

Returns: `Post`.

## PATCH /v1/posts/{id}

Edit scheduled post. Edit a scheduled post's text and/or fire time

Parameters:

- `id` (path, required)

Request body (JSON):

- `text` (string)
- `scheduledAt` (string)

Returns: `Post`.

## DELETE /v1/posts/{id}

Cancel scheduled post. Cancel a scheduled post

Parameters:

- `id` (path, required)

## GET /v1/posts/{id}/analytics

Get post analytics. Per-post normalised analytics

Parameters:

- `id` (path, required)

## GET /v1/analytics

Get cross-platform analytics. Cross-platform analytics over a period

Parameters:

- `period` (query)

## POST /v1/media

Upload media. Upload media. Request body must be raw binary with Content-Type set.

Returns: `MediaAsset`.

## POST /v1/webhooks

Register webhook. Register a webhook endpoint

Request body (JSON):

- `url` (string, required)
- `events` (array)

Returns: `WebhookEndpoint`.

## GET /v1/webhooks

List webhooks. List webhook endpoints

## DELETE /v1/webhooks/{id}

Delete webhook. Delete a webhook endpoint

Parameters:

- `id` (path, required)

## POST /v1/credentials

Save credentials. Save BYO platform app credentials (BYOK)

Request body (JSON):

- `platform` (object, required)
- `clientId` (string, required)
- `clientSecret` (string, required)

## GET /v1/credentials

List credentials. List BYO credentials

## DELETE /v1/credentials/{platform}

Delete credentials. Delete BYO credentials for a platform

Parameters:

- `platform` (path, required)

## POST /v1/connect-link

Mint connect link. Mint a short-lived link to the hosted connect/manage page

Request body (JSON):

- `profile` (string)

## POST /v1/app-link

Mint app link. Mint a session link to the full app dashboard

## POST /v1/mcp

MCP Endpoint. Model Context Protocol JSON-RPC endpoint. A focused, agent-facing toolset to publish, schedule, validate, upload media and read analytics.

Request body (JSON):

- `jsonrpc` (string, required)
- `method` (string, required)
- `params` (object)
- `id` (object)

## GET /openapi.json

OpenAPI Specification. Returns this OpenAPI specification