Complete setup flow

This guide walks you from zero → REST API ready:

Sign up / log in at postsiva.com
Create a workspace
Connect accounts (Settings → Integrations)
Create API key (Settings → API Keys) — use all REST APIs
Post / automate via REST or MCP

API keys and Unified MCP require the Pro plan (api_keys_enabled + mcp_enabled). See Plans.

Part 1 — What to do in the Postsiva UI

Complete these in the web app at postsiva.com (or your workspace URL).

Go to postsiva.com — sign up or log in.
Create a workspace (or accept an invite).
Confirm the correct workspace in the switcher. All OAuth tokens, posts, and API keys are scoped to it.

2. Upgrade if you need API / MCP

Go to Settings → Billing (or Pricing).
Subscribe to Pro (or higher) so API Keys and MCP are unlocked.
After upgrade, refresh Settings — API Keys and MCP should no longer show a plan gate.

Open Settings → Integrations (or Connect accounts).
Click each network you need: LinkedIn, Facebook, Instagram, TikTok, YouTube, Threads, Pinterest, Bluesky.
Finish the OAuth popup (grant all requested permissions).
For Facebook: pick the Pages you want to manage.
For LinkedIn: enable company / org pages if you will post as pages (not only personal).
For Pinterest: note which boards exist (you need board IDs when posting).
For Bluesky: enter handle + app password (no OAuth redirect).
Confirm each site shows Connected.

If a platform is not connected in this workspace, posting and analytics return NOT_CONNECTED (or empty slices). Connect in the UI or via OAuth API below.

4. Create a workspace API key (use REST APIs)

Open Settings → API Keys (under Integrations / developer settings in the app).
Click Create API Key.
Set:
- Name — e.g. n8n production
- Scope — see IDs and scopes:
  - full — all platforms (best for most integrations)
  - linkedin,instagram — only those platforms for connect/post
  - linkedin_only — LinkedIn only (default in some setups)
  - linkedin_posts — read-only GET /unified/posts (LinkedIn)
Copy the secret once: psk_live_… — it is not shown again.
Store it in your password manager / secrets store (never in git).

Use this key as X-API-Key: psk_live_… on every REST request to https://backend.postsiva.com. See API Overview.

5. (Optional) Copy MCP URL for Cursor / Claude

Open Settings → MCP (or Integrations → MCP).
Use endpoint: https://mcp.postsiva.com/mcp
Header: X-API-Key: psk_live_YOUR_KEY
Follow Connect MCP and Cursor.

6. Smoke-test in the UI (recommended)

Before scripting:

Use the Composer to publish a small test post to one connected account.
Open Inbox / Comments and Analytics once so data exists in the DB for API reads.

Part 2 — Connect accounts programmatically

Use these when building onboarding into your product (users never touch Postsiva UI for linking).

Auth for OAuth routes

Mode	Headers
API key	`X-API-Key: psk_live_…` (workspace from key)
JWT	`Authorization: Bearer <token>` + `X-Workspace-Id: <uuid>`

Key scope restricts which platforms you may connect (e.g. linkedin_only cannot start Instagram OAuth).

A) Start OAuth / get connect URL

POST /unified/oauth/url

curl -X POST "https://backend.postsiva.com/unified/oauth/url" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{"platform":["linkedin","instagram","facebook","tiktok","youtube","pinterest","threads"]}'

Body

Field	Type	Required	Description
`platform`	`string` or `string[]`	Yes	Platforms to connect (comma-separated strings split).
`handle`	string	Bluesky only	e.g. `you.bsky.social`
`app_password`	string	Bluesky only	Bluesky app password

Response (OAuth platforms)

{
  "results": {
    "linkedin": {
      "success": true,
      "message": "Open URL to connect LinkedIn",
      "auth_url": "https://www.linkedin.com/oauth/v2/authorization?..."
    },
    "instagram": {
      "success": true,
      "message": "",
      "auth_url": "https://api.instagram.com/oauth/authorize?..."
    }
  }
}

Open each auth_url in the browser (or redirect the end user). After callback, Postsiva stores tokens on the workspace.

B) Bluesky connect (no redirect)

curl -X POST "https://backend.postsiva.com/unified/oauth/url" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "platform": ["bluesky"],
    "handle": "you.bsky.social",
    "app_password": "xxxx-xxxx-xxxx-xxxx"
  }'

auth_url is null on success — connect completes in this call.

C) Check connection status

GET /unified/oauth/token

# All platforms (respects key scope)
curl "https://backend.postsiva.com/unified/oauth/token" \
  -H "X-API-Key: psk_live_YOUR_KEY"

# Specific platforms
curl "https://backend.postsiva.com/unified/oauth/token?platform=linkedin&platform=facebook" \
  -H "X-API-Key: psk_live_YOUR_KEY"

Look for "connected": true per platform. Token payloads may include platform user/page ids — treat access tokens as secrets.

D) Disconnect

DELETE /unified/oauth/token?platform=linkedin&platform=instagram

curl -X DELETE \
  "https://backend.postsiva.com/unified/oauth/token?platform=linkedin" \
  -H "X-API-Key: psk_live_YOUR_KEY"

E) Same flow via MCP

Tool: manage_platform_connection

Argument	Values
`action`	`connect` → returns OAuth URL; `disconnect` → unlinks
`platform`	`linkedin`, `instagram`, `facebook`, `tiktok`, `youtube`, `pinterest`, `threads`, `bluesky`

Tool: get_accounts — list connections / profile metadata.

Part 3 — After connect: automate with the API key

Always send:

X-API-Key: psk_live_YOUR_KEY
Content-Type: application/json

Workspace is taken from the key — X-Workspace-Id is optional (must match if sent).

Typical automation sequence

Confirm accounts

GET /unified/oauth/token or MCP get_accounts.

Upload media (if needed)

POST /media/upload → save media_id / public_url. See Media.

Optional AI draft

POST /unified/content/generate or MCP idea_to_content. See AI Content.

Publish, draft, or schedule

POST /unified/post/text|image|carousel|video — see Posting and the full Posting parameters reference.

Read back

GET /unified/posts, GET /unified/analytics, GET /unified/comments.

Minimal first post (LinkedIn personal)

curl -X POST "https://backend.postsiva.com/unified/post/text" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "platforms": ["linkedin"],
    "default_text": "Hello from the Postsiva API!"
  }'

Facebook Page (required `facebook_page_ids`)

curl -X POST "https://backend.postsiva.com/unified/post/text" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "platforms": ["facebook"],
    "default_text": "Hello on my Facebook Page",
    "facebook": {
      "facebook_page_ids": ["YOUR_FACEBOOK_PAGE_ID"]
    }
  }'

Page IDs appear in the UI after connecting Facebook, or in OAuth token / account profile responses.

LinkedIn company page + optional personal

curl -X POST "https://backend.postsiva.com/unified/post/text" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "platforms": ["linkedin"],
    "default_text": "Update from our company",
    "linkedin": {
      "linkedin_page_ids": ["12345"],
      "post_to_personal": false
    }
  }'

Image post using media_id

# 1) Upload
curl -X POST "https://backend.postsiva.com/media/upload" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_UUID" \
  -F "[email protected]" \
  -F "media_type=image"

# 2) Post with returned media_id
curl -X POST "https://backend.postsiva.com/unified/post/image" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "platforms": ["linkedin", "instagram"],
    "default_image_id": "MEDIA_UUID_FROM_UPLOAD",
    "default_text": "Caption for all platforms"
  }'

Part 4 — Checklist

Done?	Step
☐	Account + workspace
☐	Pro plan for API / MCP
☐	Social accounts connected (UI or OAuth API)
☐	Facebook Pages / LinkedIn orgs selected where needed
☐	API key created (`psk_live_…`) with correct scope
☐	Secrets stored securely
☐	Test `GET /unified/oauth/token` → `connected: true`
☐	Test `POST /unified/post/text`
☐	(Optional) MCP client configured

Posting parameters

Every unified + per-platform field for text, image, carousel, video.

OAuth API

Full request/response for connect, status, disconnect.

Authentication

Headers, scopes, plan gates.

MCP tools

Agent tools including manage_platform_connection and publish.

​Part 1 — What to do in the Postsiva UI

​1. Sign up or log in

​2. Upgrade if you need API / MCP

​3. Connect social accounts (Integrations)

​4. Create a workspace API key (use REST APIs)

​5. (Optional) Copy MCP URL for Cursor / Claude

​6. Smoke-test in the UI (recommended)

​Part 2 — Connect accounts programmatically

​Auth for OAuth routes

​A) Start OAuth / get connect URL

​B) Bluesky connect (no redirect)

​C) Check connection status

​D) Disconnect

​E) Same flow via MCP

​Part 3 — After connect: automate with the API key

​Typical automation sequence

​Minimal first post (LinkedIn personal)

​Facebook Page (required facebook_page_ids)

​LinkedIn company page + optional personal

​Image post using media_id

​Part 4 — Checklist

​Next pages

Posting parameters

OAuth API

Authentication

MCP tools

Part 1 — What to do in the Postsiva UI

1. Sign up or log in

2. Upgrade if you need API / MCP

3. Connect social accounts (Integrations)

4. Create a workspace API key (use REST APIs)

5. (Optional) Copy MCP URL for Cursor / Claude

6. Smoke-test in the UI (recommended)

Part 2 — Connect accounts programmatically

Auth for OAuth routes

A) Start OAuth / get connect URL

B) Bluesky connect (no redirect)

C) Check connection status

D) Disconnect

E) Same flow via MCP

Part 3 — After connect: automate with the API key

Typical automation sequence

Minimal first post (LinkedIn personal)

Facebook Page (required `facebook_page_ids`)

LinkedIn company page + optional personal

Image post using media_id

Part 4 — Checklist

Next pages