Quickstart

Get started with the MyPostShare API: authenticate requests, create an end user, connect social accounts, and publish your first post through a production-ready hosted OAuth flow.

MyPostShare is a social publishing platform for SaaS products. It provides hosted account connection, end-user social profiles, immediate publishing, scheduled publishing, and per-platform delivery results behind one API.

Base URL: https://mypostshare.com/api

LLM documentation files

Give these plain-text files to ChatGPT, Claude, Cursor, Windsurf, n8n agents, or any AI coding tool when you want it to implement MyPostShare directly. Use the full file when the agent needs endpoint details and request examples.

LLMs index

Short discovery file for AI tools. Use this when an agent asks for the canonical LLM docs entry point.

Open

https://mypostshare.com/llms.txt

Full LLM docs

Full implementation reference with endpoints, examples, auth rules, error handling, and AI-agent guidance.

Open

https://mypostshare.com/llms-full.txt

Suggested prompt

Read https://mypostshare.com/llms-full.txt, I want to ask questions about it.

Open in AI chat

These links open a new chat with the LLM docs question in the URL prompt parameter.

ChatGPT

Open

Opens ChatGPT with the LLM docs prompt.

Gemini

Open

Opens Gemini with a best-effort prompt parameter.

Claude

Open

Opens a new Claude chat with the prompt prefilled.

Authentication

API requests require an API key from your MyPostShare dashboard. Send the key as a bearer token on every request.

Authorization header

Authorization: Bearer YOUR_API_KEY

Setup flow

Step 1: Create an app and API key

Use the dashboard to create an app, issue an API key, and configure redirect URLs.

Step 2: Create an end user

Upsert the customer user with a stable externalUserId before connecting accounts.

Step 3: Start hosted OAuth

Create a connect session and send the user to the returned connectUrl.

Step 4: Publish or schedule posts

Call immediate or scheduled post endpoints and track request-level delivery status.

Detailed setup checklist

Create an app in the dashboard and issue an API key.
Choose whether the app uses customer-owned credentials or your managed provider credentials.
Register the generated fixed provider callback URL in the provider developer console when using customer-owned credentials.
Allowlist every customer redirect URL that should receive the final OAuth callback.
Create or upsert an end user with `/v1/end-users`.
Create a hosted connect session and send the user to the returned `connectUrl`.
Poll connection and post request status from the customer product as needed.

Available platforms

The current API surface supports these provider keys for connection and posting workflows.

X / Twitter

Facebook

Instagram

YouTube

Threads

Guide of platform implementation

Use this guidance when deciding how platform selection, account state, and reconnect flows should behave in your product.

Use stable platform keys

Store provider choices as API keys such as linkedin, twitter, instagram, youtube, threads, pinterest, and reddit.

Check connection state before publishing

List end-user connections and confirm the target platform status is connected before creating a post request.

Design for provider differences

Not every provider supports the same media, title, thumbnail, or account type behavior, so keep customer UI validation platform-aware.

Handle reconnects clearly

If token status or connection status indicates an issue, create a new connect session and send the user through hosted OAuth again.

Guides

Practical implementation notes for common production workflows.

Connecting Accounts

Create the end user first, then create a connect session for one platform and redirect the user to connectUrl. After callback, poll the connect session or list connections.

Media Uploads

Send public mediaUrl and optional thumbnailUrl values on post requests. Keep media validation in your product because provider media support varies by platform.

Error Handling

Treat 400 errors as validation/configuration issues, 401/403 as API key or permission problems, 404 as missing records, and 5xx as retryable platform or infrastructure failures.

Rate Limits

Use queueing and backoff in your backend for repeated polling or bulk posting workflows. Avoid tight loops; poll post status on a sensible interval.

Platform Settings

Configure app credentials, managed credential usage, and redirect allowlists in the dashboard before creating connect sessions for production users.

API Reference

POST/v1/end-users

Create or upsert end user

Creates a tenant-scoped end user or updates the existing record for the same external user ID.

Use this route before creating connect sessions or publishing posts so the platform has a stable customer user mapping.

Authentication

Bearer API key required

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY` for the current customer app.

Request body

externalUserIdstringRequired

Unique user ID from the customer product.

displayNamestringOptional

Human-readable label shown in dashboard inventory.

emailstringOptional

Optional email for operator visibility.

metadataobjectOptional

Free-form customer metadata stored with the end user.

POST request

curl -X POST "https://mypostshare.com/api/v1/end-users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "displayName": "Alex Morgan",
    "email": "alex@example.com",
    "metadata": { "plan": "pro", "source": "web-app" }
  }'

200 Upserted

{
  "id": "4ea64e37-6c19-43a0-8ef5-1a7e7e2b0b89",
  "externalUserId": "user_123",
  "displayName": "Alex Morgan",
  "email": "alex@example.com",
  "metadata": { "plan": "pro", "source": "web-app" },
  "createdAt": "2026-03-21T08:00:00.000Z",
  "updatedAt": "2026-03-21T08:00:00.000Z"
}

GET/v1/end-users/:externalUserId

Get end user

Returns the stored end user profile and a high-level connection summary.

Use this route when the customer product needs to know whether a user has already been onboarded in the current app.

Authentication

Bearer API key required

Path parameters

externalUserIdstringRequired

Customer-defined end user identifier.

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

GET request

curl -X GET "https://mypostshare.com/api/v1/end-users/user_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 Retrieved

{
  "id": "4ea64e37-6c19-43a0-8ef5-1a7e7e2b0b89",
  "externalUserId": "user_123",
  "displayName": "Alex Morgan",
  "email": "alex@example.com",
  "connectionSummary": { "total": 2, "connected": 1, "failed": 0 }
}

GET/v1/end-users/:externalUserId/connections

List end user connections

Lists connected social accounts for the end user, including platform and account metadata.

Use this route to show connection status in the customer app or to confirm a platform is ready before publishing.

Authentication

Bearer API key required

Path parameters

externalUserIdstringRequired

Customer-defined end user identifier.

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

GET request

curl -X GET "https://mypostshare.com/api/v1/end-users/user_123/connections" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 Retrieved

[
  {
    "id": "7c7f00f5-3412-4546-8cb7-3f095b16fe49",
    "platform": "linkedin",
    "status": "connected",
    "remoteAccountId": "H8a9UFibz4",
    "remoteUsername": "ALEX_MORGAN",
    "accountType": "person"
  }
]

DELETE/v1/end-users/:externalUserId/connections/:platform

Disconnect a platform

Removes a linked social connection for a specific end user and platform.

Use this when a customer wants to revoke the local platform linkage or force a reconnect for a specific provider.

Authentication

Bearer API key required

Path parameters

externalUserIdstringRequired

Customer-defined end user identifier.

platformstringRequired

Provider key. Supported values: `linkedin`, `facebook`, `instagram`, `twitter`, `youtube`, `threads`, `pinterest`, `reddit`.

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

DELETE request

curl -X DELETE "https://mypostshare.com/api/v1/end-users/user_123/connections/linkedin" \
  -H "Authorization: Bearer YOUR_API_KEY"

204 Deleted

{}

POST/v1/connect-sessions

Create connect session

Creates a hosted OAuth session and returns the `connectUrl` the customer frontend should open.

This is the main entry point for hosted account linking. The platform binds provider callback state to this session and safely redirects back later.

Authentication

Bearer API key required

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

Request body

externalUserIdstringRequired

End user identifier already created for the current app.

platformstringRequired

Provider to connect. Supported values: `linkedin`, `facebook`, `instagram`, `twitter`, `youtube`, `threads`, `pinterest`, `reddit`.

redirectUristringRequired

Customer redirect URL that must already be allowlisted.

displayobjectOptional

Optional metadata used to personalize the hosted connect screen.

POST request

curl -X POST "https://mypostshare.com/api/v1/connect-sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "platform": "linkedin",
    "redirectUri": "https://client.example.com/oauth/callback"
  }'

201 Created

{
  "id": "9469c610-999a-4cb0-9807-a7037947d6b5",
  "status": "pending",
  "platform": "linkedin",
  "connectUrl": "https://mypostshare.com/connect/9469c610-999a-4cb0-9807-a7037947d6b5"
}

GET/v1/connect-sessions/:id

Get connect session status

Returns the latest status for a hosted OAuth session.

Use this route to poll for completion after redirecting the end user to the hosted connect flow.

Authentication

Bearer API key required

Path parameters

idstringRequired

Connect session ID returned from `POST /v1/connect-sessions`.

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

GET request

curl -X GET "https://mypostshare.com/api/v1/connect-sessions/9469c610-999a-4cb0-9807-a7037947d6b5" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 Retrieved

{
  "id": "9469c610-999a-4cb0-9807-a7037947d6b5",
  "status": "connected",
  "platform": "linkedin",
  "externalUserId": "user_123",
  "errorCode": null,
  "updatedAt": "2026-03-21T06:58:48.753Z"
}

POST/v1/posts

Publish immediately

Creates a direct publish request and attempts delivery right away.

Use this route when the customer app wants an immediate publish action against one or more connected platforms.

Authentication

Bearer API key required

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

Request body

externalUserIdstringRequired

Connected end user to publish on behalf of.

titlestringOptional

Optional title or headline used by supported providers.

contentstringRequired

Main post content.

platformsstring[]Required

List of provider keys to deliver to. Supported values: `linkedin`, `facebook`, `instagram`, `twitter`, `youtube`, `threads`, `pinterest`, `reddit`.

mediaUrlstringOptional

Optional media URL for supported providers.

thumbnailUrlstringOptional

Optional thumbnail asset URL.

metadataobjectOptional

Optional customer metadata attached to the request.

POST request

curl -X POST "https://mypostshare.com/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "title": "Launch update",
    "content": "Testing mypostshare direct posting from docs.",
    "platforms": ["linkedin"],
    "metadata": { "source": "api-docs" }
  }'

201 Created

{
  "id": "e3143cd2-fb9e-42cf-aa45-f7e711d4823d",
  "mode": "immediate",
  "status": "published",
  "externalUserId": "user_123",
  "platformResults": [
    { "platform": "linkedin", "status": "published", "externalId": "urn:li:share:7441018768555757568" }
  ]
}

POST/v1/posts/scheduled

Schedule a post

Creates a scheduled publish request for a future time.

Use this route when the customer app wants the platform worker to execute publishing later.

Authentication

Bearer API key required

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

Request body

externalUserIdstringRequired

Connected end user to schedule a post for.

contentstringRequired

Main post content.

platformsstring[]Required

Providers that should receive the scheduled post. Supported values: `linkedin`, `facebook`, `instagram`, `twitter`, `youtube`, `threads`, `pinterest`, `reddit`.

scheduleAtstringRequired

Future ISO 8601 UTC timestamp when the job should run.

metadataobjectOptional

Optional customer metadata attached to the request.

POST request

curl -X POST "https://mypostshare.com/api/v1/posts/scheduled" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "content": "Scheduled via mypostshare docs page.",
    "platforms": ["linkedin", "twitter"],
    "scheduleAt": "2026-03-22T09:30:00.000Z",
    "metadata": { "campaign": "launch-week" }
  }'

201 Scheduled

{
  "id": "40bb5e88-4868-4336-af0c-f18dd7a5eb45",
  "mode": "scheduled",
  "status": "scheduled",
  "externalUserId": "user_123",
  "scheduleAt": "2026-03-22T09:30:00.000Z",
  "platformResults": []
}

GET/v1/posts/:id

Get post request

Returns a single publish or schedule request with per-platform delivery results.

Use this route to poll a specific request after creating an immediate or scheduled post.

Authentication

Bearer API key required

Path parameters

idstringRequired

Post request ID returned from a publish or schedule call.

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

GET request

curl -X GET "https://mypostshare.com/api/v1/posts/e3143cd2-fb9e-42cf-aa45-f7e711d4823d" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 Retrieved

{
  "id": "e3143cd2-fb9e-42cf-aa45-f7e711d4823d",
  "mode": "immediate",
  "status": "published",
  "externalUserId": "user_123",
  "platformResults": [
    { "platform": "linkedin", "status": "published", "externalId": "urn:li:share:7441018768555757568" }
  ]
}

GET/v1/posts

List post requests

Returns publish and schedule requests for the current app, optionally filtered by user or status.

Use this route for dashboard views, support tools, and recent activity feeds.

Authentication

Bearer API key required

Headers

AuthorizationstringRequired

Send `Bearer YOUR_API_KEY`.

Query parameters

externalUserIdstringOptional

Optional end user filter.

statusstringOptional

Optional lifecycle filter such as `scheduled` or `published`.

platformstringOptional

Optional provider filter.

dateFromstringOptional

Optional ISO 8601 start date filter.

dateTostringOptional

Optional ISO 8601 end date filter.

GET request

curl -X GET "https://mypostshare.com/api/v1/posts?externalUserId=user_123&status=published" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 Retrieved

[
  { "id": "e3143cd2-fb9e-42cf-aa45-f7e711d4823d", "mode": "immediate", "status": "published", "externalUserId": "user_123" },
  { "id": "40bb5e88-4868-4336-af0c-f18dd7a5eb45", "mode": "scheduled", "status": "scheduled", "externalUserId": "user_123" }
]

Provider notes

Each platform now uses a fixed callback URL, while connect-session state safely restores the app and redirect destination.

Customer apps can use either their own provider credentials or your managed credentials for faster onboarding.

Redirect URIs must be allowlisted in the dashboard before a connect session can use them.

Hosted OAuth redirects back with safe fields only, never with provider tokens or secrets.

Publishing results return request-level and platform-level status for support and auditing.

Resources

LLMs.txt Full LLM docs Pricing Trust Playground