# Publora API & MCP Documentation — Full Text
> Complete Publora documentation concatenated for LLM ingestion. Site: https://docs.publora.com · Index: https://docs.publora.com/llms.txt
---
> Source: https://docs.publora.com/getting-started
# Getting Started with Publora API
## Overview
Publora API lets you schedule and publish social media posts across 10 platforms from a single REST endpoint. Base URL: `https://api.publora.com`
Machine-readable API descriptions are available as [OpenAPI YAML](https://docs.publora.com/openapi.yaml) and [OpenAPI JSON](https://docs.publora.com/openapi.json).
> **For AI Agents:** You cannot programmatically create accounts or generate API keys. Your user must complete Steps 1-2 manually at [publora.com](https://publora.com), then provide you with their API key.
## Pricing
| Plan | Monthly | Yearly up to −33% | Posts/Month | Platforms |
|------|---------|-------------|-------------|-----------|
| **Starter** | Free | Free | 15 | All platforms, except X |
| **Pro**, per account | 1–5 · $5.99 6–20 · $2.99 21+ · $0.99 | $3.99 $1.99 $0.66 | Unlimited | All platforms |
| **Agency** | 1–10 · $59 flat 11–50 · $3.00 each 51+ · $1.50 each | $47.20 flat $2.40 each $1.20 each | Unlimited | All platforms |
> **Note:** The free Starter plan **includes** full REST API and MCP access (3 connected accounts, 15 posts/month account-wide).
Pro is priced per connected account and the tiers combine automatically — e.g. 10 accounts = 5 × $5.99 + 5 × $2.99 = **$44.90/mo** ($29.90/mo billed yearly).
Agency is priced per connected account across all client workspaces, minimum 10: $59/mo flat covers the first 10, then $3.00 each for accounts 11–50 and $1.50 each for 51+ — e.g. 20 accounts = $59 + 10 × $3.00 = **$89/mo** ($71.20/mo billed yearly, 20% off). Agency access is enabled on request, with no self-serve signup: contact us via [agencies.publora.com](https://agencies.publora.com) or [publora.com/pricing](https://publora.com/pricing).
See full details at [publora.com/pricing](https://publora.com/pricing) (machine-readable: [publora.com/pricing.md](https://publora.com/pricing.md))
## Step 1: Sign Up and Get an API Key
1. Create an account at [publora.com](https://publora.com) (free tier available)
2. Go to **API** in the sidebar
3. Click **Generate API Key**
4. Copy the key immediately — it's shown only once
Dashboard keys look like: `sk_mrmbzomn_1a2b3c4d.964793af0123456789abcdef0123456789abcdef0123456789ab`
## Step 2: Connect Social Accounts
Connect your social media accounts via the Publora dashboard:
1. Go to **Channels** in the sidebar
2. Click **Add Channel** and select a platform
3. Complete the OAuth authorization in your browser
4. Repeat for each platform you want to post to
**Note:** Social account connections use OAuth and must be done in the dashboard — not via API. The API is for scheduling posts to already-connected accounts.
> **Tip:** Click **MCP** in the sidebar for AI assistant integration instructions.
## Step 3: List Your Connections
### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/platform-connections', {
headers: {
'x-publora-key': 'YOUR_API_KEY'
}
});
const data = await response.json();
console.log(data.connections);
// [{ platformId: "twitter-123456", username: "@you", displayName: "Your Name" }, ...]
```
### Python (requests)
```python
import requests
response = requests.get(
'https://api.publora.com/api/v1/platform-connections',
headers={'x-publora-key': 'YOUR_API_KEY'}
)
connections = response.json()['connections']
for conn in connections:
print(f"{conn['displayName']} ({conn['platformId']})")
```
### cURL
```bash
curl https://api.publora.com/api/v1/platform-connections \
-H "x-publora-key: YOUR_API_KEY"
```
### Node.js (axios)
```javascript
const axios = require('axios');
const { data } = await axios.get(
'https://api.publora.com/api/v1/platform-connections',
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
console.log(data.connections);
```
## Step 4: Create Your First Post
### JavaScript (fetch)
```javascript
const scheduledTime = new Date(Date.now() + 5 * 60 * 1000).toISOString();
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Hello from Publora API! 🚀',
platforms: ['twitter-123456789', 'linkedin-ABC123'],
scheduledTime
})
});
const data = await response.json();
console.log(data.postGroupId); // "507f1f77bcf86cd799439011"
```
### Python (requests)
```python
import requests
from datetime import datetime, timedelta, timezone
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Hello from Publora API! 🚀',
'platforms': ['twitter-123456789', 'linkedin-ABC123'],
'scheduledTime': (datetime.now(timezone.utc) + timedelta(minutes=5)).isoformat()
}
)
print(response.json()['postGroupId'])
```
### cURL
Replace `` with a UTC time at least five minutes ahead.
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Hello from Publora API! 🚀",
"platforms": ["twitter-123456789", "linkedin-ABC123"],
"scheduledTime": ""
}'
```
### Node.js (axios)
```javascript
const axios = require('axios');
const scheduledTime = new Date(Date.now() + 5 * 60 * 1000).toISOString();
const { data } = await axios.post(
'https://api.publora.com/api/v1/create-post',
{
content: 'Hello from Publora API! 🚀',
platforms: ['twitter-123456789', 'linkedin-ABC123'],
scheduledTime
},
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
console.log(data.postGroupId);
```
## Step 5: Check Post Status
### JavaScript (fetch)
```javascript
const response = await fetch(
`https://api.publora.com/api/v1/get-post/${postGroupId}`,
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
// data.posts[0].status: "scheduled" | "published" | "failed"
console.log(data.posts.map(p => `${p.platform}: ${p.status}`));
```
### Python (requests)
```python
response = requests.get(
f'https://api.publora.com/api/v1/get-post/{post_group_id}',
headers={'x-publora-key': 'YOUR_API_KEY'}
)
for post in response.json()['posts']:
print(f"{post['platform']}: {post['status']}")
```
### cURL
```bash
curl https://api.publora.com/api/v1/get-post/507f1f77bcf86cd799439011 \
-H "x-publora-key: YOUR_API_KEY"
```
## What's Next?
- [Upload images and videos](guides/media-uploads.md)
- [Post to specific platforms](guides/cross-platform.md)
- [LinkedIn analytics](endpoints/linkedin-statistics.md)
- [Agency client posts (Company API and MCP)](guides/agency-quickstart.md)
- [Error handling](guides/error-handling.md)
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/authentication
# Authentication
Publora uses **API keys** for authentication. API keys are long-lived credentials that don't expire or require refresh tokens — unlike OAuth, there's no token exchange workflow.
> **Important for AI Agents:** If you're an AI assistant helping a user with the Publora API, you cannot programmatically create accounts or obtain API keys. The user must complete these steps manually in their browser, then provide you with their API key.
## Prerequisites: Account Setup
Before you can authenticate with the API, you need:
### 1. Create a Publora Account
Sign up at [publora.com](https://publora.com) — free accounts are available.
### 2. Connect Your Social Media Accounts
In the Publora dashboard, connect the social platforms you want to post to:
1. Go to **Channels** in the sidebar
2. Click **Add Channel**
3. Select a platform (LinkedIn, X/Twitter, Instagram, etc.)
4. Complete the OAuth authorization flow in your browser
5. Repeat for each platform you want to use
**Note:** OAuth authorization happens in Publora's dashboard, not through the API. The API is for scheduling and managing posts to already-connected accounts.
### 3. Generate Your API Key
1. Go to **API** in the sidebar
2. Click **Generate API Key**
3. **Copy immediately** — the full key is shown only once
> **Tip:** Click **MCP** in the sidebar for MCP-specific setup instructions.
## Pricing Plans
| Plan | Monthly | Yearly up to −33% | Posts/Month | Accounts | Platforms | Video Upload |
|------|---------|-------------|-------------|----------|-----------|--------------|
| **Starter** | Free | Free | 15 | 3 | All platforms, except X | 50MB |
| **Pro**, per account | 1–5 · $5.99 6–20 · $2.99 21+ · $0.99 | $3.99 $1.99 $0.66 | Unlimited | 1–1,000 | All platforms | 250MB |
| **Agency** | 1–10 · $59 flat 11–50 · $3.00 each 51+ · $1.50 each | $47.20 flat $2.40 each $1.20 each | Unlimited | From 10 | All platforms | Custom |
Pro is priced per connected account and the tiers combine automatically — e.g. 10 accounts = 5 × $5.99 + 5 × $2.99 = **$44.90/mo** ($29.90/mo billed yearly).
Agency is priced per connected account across all client workspaces, minimum 10: $59/mo flat covers the first 10, then $3.00 each for accounts 11–50 and $1.50 each for 51+ — e.g. 20 accounts = $59 + 10 × $3.00 = **$89/mo** ($71.20/mo billed yearly, 20% off). Agency access is enabled on request, with no self-serve signup: contact us via [agencies.publora.com](https://agencies.publora.com) or [publora.com/pricing](https://publora.com/pricing).
- **Starter** is free forever — great for trying the API
- View full details at [publora.com/pricing](https://publora.com/pricing) (machine-readable: [publora.com/pricing.md](https://publora.com/pricing.md))
## API Keys vs OAuth Tokens
| Feature | Publora API Keys | OAuth Tokens |
|---------|------------------|--------------|
| Expiration | Never expires | Typically 1 hour |
| Refresh needed | No | Yes (refresh token flow) |
| How to get | Dashboard → API | OAuth authorization flow |
| Format | Dashboard multi-key: `sk_mrmbzomn_1a2b3c4d.964793af0123456789abcdef0123456789abcdef0123456789ab`; single-current `User.apiKey`: `sk_mrmbzomn.964793af0123456789abcdef0123456789abcdef0123456789ab` | `eyJhbG...` (JWT) |
**Key point:** You can generate up to 10 active API keys from the dashboard. Each key works independently and never expires.
## Getting Your API Key
Once you have an account with connected social platforms:
1. Sign in at [publora.com](https://publora.com)
2. Go to **API** in the sidebar
3. Click **Generate API Key**
4. **Copy immediately** — the full key is shown only once
### Why Dashboard Multi-Key Generation Is Session-Only
The dashboard multi-key endpoint (`POST /auth/api-keys`) requires **dashboard session authentication**, not API-key authentication. An existing key therefore cannot mint another named dashboard key for its owner.
This is intentional for security reasons:
| Concern | Why Session-Auth-Only |
|---------|-------------------|
| **Key theft prevention** | API-key auth cannot mint additional dashboard multi-key records for its owner |
| **Human verification** | Dashboard login ensures a human authorized the key |
| **Audit trail** | All key generation is logged with user/IP information |
| **Accidental exposure** | Prevents automated systems from creating excess keys |
**For automation and CI/CD:** Store your API key in environment variables or secrets managers (AWS Secrets Manager, HashiCorp Vault, GitHub Secrets). The key never expires, so you only need to set it up once.
```bash
# GitHub Actions secret
gh secret set PUBLORA_API_KEY
# AWS Secrets Manager
aws secretsmanager create-secret --name publora-api-key --secret-string "sk_..."
# Kubernetes secret
kubectl create secret generic publora --from-literal=api-key="sk_..."
```
### API Key Management Endpoints
These endpoints manage API keys and require **dashboard session authentication** (not API key auth). They power the dashboard UI and cannot be called with an API key.
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/auth/api-keys` | List all API keys for the authenticated user |
| POST | `/auth/api-keys` | Create a new API key |
| PATCH | `/auth/api-keys/:keyId` | Update an API key (e.g., rename) |
| DELETE | `/auth/api-keys/:keyId` | Revoke (soft-delete) an API key |
**Response formats:**
- **POST** `/auth/api-keys` (Create):
```json
{
"message": "API key created successfully",
"apiKey": {
"_id": "65f8a1b2c3d4e5f6a7b8c9d0",
"name": "My Key",
"keyPrefix": "sk_mrmbzomn_1a2b3c4d",
"createdAt": "2026-02-22T10:00:00.000Z",
"lastUsedAt": null,
"rawKey": "sk_mrmbzomn_1a2b3c4d.964793af0123456789abcdef0123456789abcdef0123456789ab"
}
}
```
> **Important:** `rawKey` is only returned once at creation time. Store it immediately.
- **GET** `/auth/api-keys` (List):
```json
{
"apiKeys": [
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d0",
"name": "My Key",
"keyPrefix": "sk_mrmbzomn_1a2b3c4d",
"createdAt": "2026-02-22T10:00:00.000Z",
"lastUsedAt": "2026-02-23T14:30:00.000Z"
}
]
}
```
- **DELETE** `/auth/api-keys/:keyId` (Revoke):
```json
{ "message": "API key revoked successfully" }
```
- **PATCH** `/auth/api-keys/:keyId` (Update):
```json
{
"message": "API key updated successfully",
"apiKey": {
"_id": "65f8a1b2c3d4e5f6a7b8c9d0",
"name": "Renamed Key",
"keyPrefix": "sk_mrmbzomn_1a2b3c4d",
"createdAt": "2026-02-22T10:00:00.000Z",
"lastUsedAt": "2026-02-23T14:30:00.000Z"
}
}
```
**Key name handling:**
- Names are HTML-sanitized to prevent XSS
- If no name is provided (or the name is empty), the key defaults to `"Default"`
- Maximum name length: 100 characters
### Key Format
Publora currently mints two API-key shapes:
```text
# Dashboard key (POST /auth/api-keys)
sk_mrmbzomn_1a2b3c4d.964793af0123456789abcdef0123456789abcdef0123456789ab
# Single-current User.apiKey (session `/auth/generate-api-key`)
sk_mrmbzomn.964793af0123456789abcdef0123456789abcdef0123456789ab
```
- Both start with `sk_`, contain a base36 timestamp, use one dot separator, and end with 52 random hex characters.
- Dashboard keys add an 8-hex collision-resistant segment before the dot: `sk__<8_hex>.<52_hex>` (about 73 characters today).
- Single-current `User.apiKey` keys use `sk_.<52_hex>` (64 characters today). They are produced by session-authenticated `/auth/generate-api-key` for the current user.
- Exact total length varies as the base36 timestamp grows. The authentication shape gate accepts 20–200 URL-safe characters, requires `sk_`, and requires a dot; the stored hash remains authoritative.
- **Dashboard keys:** Maximum **10 active keys** per user; each dashboard key has a name with a 100-character maximum.
- **Single-current `User.apiKey`:** Each user has one stored current key in this form. Session generation replaces the caller's key and does not add a named dashboard multi-key record.
> **Note:** The middleware enforces the broad shape above before its legacy-user fallback. A key without `sk_` or a dot is rejected even if an old user record exists; do not rely on pre-format keys.
### Key Validation (Before Making Requests)
Validate your key format before making API calls:
```javascript
function isValidPubloraKey(key) {
return typeof key === 'string' &&
key.length >= 20 &&
key.length <= 200 &&
key.startsWith('sk_') &&
key.includes('.') &&
/^[A-Za-z0-9._-]+$/.test(key);
}
// Usage
const apiKey = process.env.PUBLORA_API_KEY;
if (!isValidPubloraKey(apiKey)) {
throw new Error('Invalid PUBLORA_API_KEY format');
}
```
```python
import re
def is_valid_publora_key(key):
"""Validate Publora API key format."""
return (
isinstance(key, str)
and 20 <= len(key) <= 200
and key.startswith('sk_')
and '.' in key
and re.fullmatch(r'[A-Za-z0-9._-]+', key) is not None
)
# Usage
api_key = os.environ.get('PUBLORA_API_KEY')
if not is_valid_publora_key(api_key):
raise ValueError('Invalid PUBLORA_API_KEY format')
```
## Authentication by Interface
Publora provides two interfaces that use the **same API key**. REST requires its custom header; MCP recommends Bearer authentication and also accepts the REST-style header:
| Interface | Header Format | Use Case |
|-----------|---------------|----------|
| REST API | `x-publora-key: sk_...` | Direct HTTP requests |
| MCP Server | `Authorization: Bearer sk_...` (recommended) or `x-publora-key: sk_...` | AI assistants (Claude, Cursor) |
### REST API Authentication
For direct HTTP calls to `api.publora.com`:
```bash
curl https://api.publora.com/api/v1/platform-connections \
-H "x-publora-key: sk_mrmbzomn.964793af0123456789abcdef0123456789abcdef0123456789ab"
```
```javascript
const response = await fetch('https://api.publora.com/api/v1/platform-connections', {
headers: {
'x-publora-key': process.env.PUBLORA_API_KEY
}
});
```
```python
response = requests.get(
'https://api.publora.com/api/v1/platform-connections',
headers={'x-publora-key': os.environ['PUBLORA_API_KEY']}
)
```
### MCP Authentication
For MCP clients connecting to `mcp.publora.com`:
```json
{
"mcpServers": {
"publora": {
"type": "http",
"url": "https://mcp.publora.com",
"headers": {
"Authorization": "Bearer sk_mrmbzomn.964793af0123456789abcdef0123456789abcdef0123456789ab"
}
}
}
}
```
**Why recommend Bearer for MCP?** MCP clients commonly expect the standard `Authorization: Bearer` format. The MCP server also accepts `x-publora-key` as a fallback. Direct REST requests accept only `x-publora-key`.
### MCP Client Identification
Publora's MCP server sets `x-publora-client: mcp` on its internal REST requests to the backend. This triggers an `mcpAccess` entitlement check. If the account does not have MCP access enabled, the backend responds with `403 "MCP access is not enabled for this account"`.
Claude Desktop, Cursor, and other MCP clients do not send this REST header; they authenticate to `mcp.publora.com`, and Publora's MCP server adds it downstream. A direct REST caller may also set `x-publora-client`; the value `mcp` opts that request into the same entitlement check.
The backend records any non-empty `x-publora-client` value verbatim as the request's client identifier; when the header is absent it uses `"api"`.
## Complete Authentication Workflow
### Step 1: Store Your Key Securely
```bash
# Add to ~/.bashrc or ~/.zshrc
export PUBLORA_API_KEY="sk_mrmbzomn.964793af0123456789abcdef0123456789abcdef0123456789ab"
```
Or use a `.env` file (add to `.gitignore`):
```bash
# .env
PUBLORA_API_KEY=sk_mrmbzomn.964793af0123456789abcdef0123456789abcdef0123456789ab
```
### Step 2: Verify Your Key Works
Test authentication by fetching your connected platforms:
```javascript
async function verifyAuthentication() {
const apiKey = process.env.PUBLORA_API_KEY;
// Validate format first
if (!apiKey?.startsWith('sk_')) {
console.error('Error: API key must start with sk_');
console.error('Get your key at: https://publora.com → API');
return false;
}
try {
const response = await fetch('https://api.publora.com/api/v1/platform-connections', {
headers: { 'x-publora-key': apiKey }
});
if (response.status === 401) {
console.error('Error: Invalid API key');
console.error('Check your key or generate a new one at publora.com');
return false;
}
if (!response.ok) {
console.error(`Error: HTTP ${response.status}`);
return false;
}
const data = await response.json();
console.log(`✓ Authenticated successfully`);
console.log(`✓ ${data.connections.length} connected platform(s)`);
return true;
} catch (error) {
console.error('Error: Connection failed -', error.message);
return false;
}
}
```
```python
import os
import requests
def verify_authentication():
"""Verify API key is valid and working."""
api_key = os.environ.get('PUBLORA_API_KEY')
# Validate format first
if not api_key or not api_key.startswith('sk_'):
print('Error: API key must start with sk_')
print('Get your key at: https://publora.com → API')
return False
try:
response = requests.get(
'https://api.publora.com/api/v1/platform-connections',
headers={'x-publora-key': api_key}
)
if response.status_code == 401:
print('Error: Invalid API key')
print('Check your key or generate a new one at publora.com')
return False
response.raise_for_status()
data = response.json()
print(f'✓ Authenticated successfully')
print(f"✓ {len(data['connections'])} connected platform(s)")
return True
except requests.RequestException as e:
print(f'Error: Connection failed - {e}')
return False
# Run verification
verify_authentication()
```
### Step 3: Make Your First API Call
```javascript
// After verification succeeds, make API calls
const response = await fetch('https://api.publora.com/api/v1/list-posts', {
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
});
const { posts } = await response.json();
console.log(`Found ${posts.length} posts`);
```
## Error Handling
### Authentication Errors
| Status | Error | Cause | Solution |
|--------|-------|-------|----------|
| 401 | `"API key is required"` | Missing `x-publora-key` header | Include the `x-publora-key` header with your API key |
| 401 | `"Invalid API key"` | Key is wrong or has been revoked | Generate a new key at API in sidebar |
| 401 | `"Invalid API key owner"` | User associated with the key could not be found | Contact support; the key owner account may be deleted |
| 403 | `"API access is not enabled for this account"` | Account lacks the API access entitlement | Contact support if you expect API access |
| 403 | `"Your current plan does not include API access"` | API access is disabled for this account (returned by key management endpoints) | Contact support if you expect API access |
| 403 | `"MCP access is not enabled for this account"` | Account lacks MCP access entitlement (sent via MCP client) | Upgrade your plan to include MCP access |
| 400 | `"Maximum of 10 active API keys allowed"` | Attempted to create an API key when 10 active keys already exist | Delete an existing key before creating a new one |
| 400 | `"Name must be a string with maximum 100 characters"` | POST `/auth/api-keys` — name is not a string or exceeds 100 characters | Provide a valid name under 100 characters |
| 404 | `"User not found"` | POST `/auth/api-keys` — authenticated user could not be found in the database | Contact support; the account may be deleted |
| 400 | `"Name is required"` | PATCH `/auth/api-keys/:keyId` — name field is missing or empty | Provide a non-empty name |
| 400 | `"Name must be maximum 100 characters"` | PATCH `/auth/api-keys/:keyId` — name exceeds 100 characters | Shorten the name to 100 characters or fewer |
| 400 | `"Invalid key ID format"` | PATCH or DELETE `/auth/api-keys/:keyId` — keyId is not a valid ObjectId | Provide a valid 24-character hex ObjectId |
| 404 | `"API key not found"` | DELETE or PATCH `/auth/api-keys/:keyId` — the specified key doesn't exist or has been revoked | Verify the key ID is correct and the key has not already been deleted |
| 500 | `"Internal server error"` | Unexpected error during authentication middleware | Retry the request; if persistent, contact support |
### Handling Auth Errors in Code
```javascript
async function publoraRequest(endpoint, options = {}) {
const apiKey = process.env.PUBLORA_API_KEY;
if (!apiKey?.startsWith('sk_')) {
throw new Error('PUBLORA_API_KEY not set or invalid format');
}
const response = await fetch(`https://api.publora.com/api/v1${endpoint}`, {
...options,
headers: {
'x-publora-key': apiKey,
'Content-Type': 'application/json',
...options.headers
}
});
if (response.status === 401) {
throw new Error('Invalid API key. Generate a new one at publora.com → API');
}
if (response.status === 403) {
const data = await response.json();
if (data.error?.includes('API access is not enabled')) {
throw new Error('API access not enabled. Upgrade at publora.com/pricing');
}
throw new Error(data.error || 'Access denied');
}
if (!response.ok) {
const data = await response.json();
throw new Error(data.error || `HTTP ${response.status}`);
}
return response.json();
}
```
```python
class PubloraAuthError(Exception):
"""Raised when authentication fails."""
pass
def publora_request(endpoint, method='GET', **kwargs):
"""Make authenticated request with proper error handling."""
api_key = os.environ.get('PUBLORA_API_KEY')
if not api_key or not api_key.startswith('sk_'):
raise PubloraAuthError('PUBLORA_API_KEY not set or invalid format')
response = requests.request(
method,
f'https://api.publora.com/api/v1{endpoint}',
headers={
'x-publora-key': api_key,
'Content-Type': 'application/json'
},
**kwargs
)
if response.status_code == 401:
raise PubloraAuthError('Invalid API key. Generate a new one at publora.com → API')
if response.status_code == 403:
data = response.json()
if 'API access is not enabled' in data.get('error', ''):
raise PubloraAuthError('API access not enabled. Upgrade at publora.com/pricing')
raise PubloraAuthError(data.get('error', 'Access denied'))
response.raise_for_status()
return response.json()
```
## Retry Logic with Exponential Backoff
For production applications, implement retry logic:
```javascript
async function publoraRequestWithRetry(endpoint, options = {}, maxRetries = 3) {
const apiKey = process.env.PUBLORA_API_KEY;
if (!apiKey?.startsWith('sk_')) {
throw new Error('PUBLORA_API_KEY not set or invalid format');
}
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = await fetch(`https://api.publora.com/api/v1${endpoint}`, {
...options,
headers: {
'x-publora-key': apiKey,
'Content-Type': 'application/json',
...options.headers
}
});
// Don't retry auth errors - they won't succeed
if (response.status === 401 || response.status === 403) {
const data = await response.json();
throw new Error(data.error || `Auth error: ${response.status}`);
}
// Retry on rate limit
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
console.log(`Rate limited. Waiting ${retryAfter}s...`);
await new Promise(r => setTimeout(r, retryAfter * 1000));
continue;
}
// Retry on server errors
if (response.status >= 500 && attempt < maxRetries) {
const delay = Math.pow(2, attempt) * 1000;
console.log(`Server error. Retry ${attempt}/${maxRetries} in ${delay}ms...`);
await new Promise(r => setTimeout(r, delay));
continue;
}
if (!response.ok) {
const data = await response.json();
throw new Error(data.error || `HTTP ${response.status}`);
}
return response.json();
} catch (error) {
if (attempt === maxRetries) throw error;
if (error.message.includes('Auth error')) throw error; // Don't retry auth errors
}
}
}
```
## Security Best Practices
### Do
- Store keys in environment variables
- Use `.env` files (added to `.gitignore`)
- Rotate keys periodically
- Use separate keys for development and production
- Validate key format before making requests
### Don't
- Hardcode keys in source code
- Commit keys to version control
- Share keys in chat, email, or public forums
- Use keys in client-side JavaScript (browsers)
- Log full API keys (mask them: `sk_mrmbzomn.9647...****`)
### Key Storage
```javascript
// Good: Environment variable
const apiKey = process.env.PUBLORA_API_KEY;
// Bad: Hardcoded
const apiKey = 'sk_mrmbzomn.964793af0123456789abcdef0123456789abcdef0123456789ab'; // Never do this!
```
### Managing API Keys
You can generate multiple API keys — useful for different environments or applications.
**If your key is compromised:**
1. Go to publora.com → **API** in the sidebar
2. Delete the compromised key
3. Click **Generate API Key** to create a new one
4. Update your environment variables with the new key
> **Note:** Key deletion is a soft-delete — it sets a `revokedAt` timestamp rather than removing the key from the database. Revoked keys immediately stop working but remain in the audit trail.
## Quick Reference
| What | Value |
|------|-------|
| REST API Base URL | `https://api.publora.com/api/v1` |
| MCP Server URL | `https://mcp.publora.com` |
| REST API Header | `x-publora-key: sk_...` |
| MCP Header | `Authorization: Bearer sk_...` (recommended) or `x-publora-key: sk_...` |
| Key Format | Dashboard multi-key: `sk__<8_hex>.<52_hex>`; single-current `User.apiKey`: `sk_.<52_hex>` |
| Key Expiration | Never (until revoked) |
| Max Keys | Dashboard: 10 active multi-key records per user; `User.apiKey`: one current key per user, replaced on regeneration |
| Get Key | publora.com → API |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/changelog
# API Changelog and Deprecation Ledger
This page records externally relevant REST and MCP contract changes. Dates are deployment or documentation publication dates, not announcement estimates.
## Upcoming
### Agency LinkedIn Page reshares and client decisions — publora.com #831
- **Affected surface:** Company REST `POST /linkedin-page-posts`, Company drafts
(`repostSourceSnapshot`, `includeRepostSource`), client reviews
(`POST /post-groups/:postGroupId/approval`), Company webhooks, and the new
`company_list_linkedin_page_posts` MCP tool (49 Company / 69 total tools).
- **Tag:** Additive and opt-in. Publish this documentation with or after the
[feature rollout](https://github.com/publora/publora.com/issues/831).
- **Change:** List published posts of a connected Company Page as reshare sources
and save the original's text as a review preview. Clients can decline a review
with an optional comment; `approvalStatus` accepts `declined`. A review requested
with a future `scheduledTime` schedules the approved version automatically.
Workspace webhooks can subscribe to `approval.decided`, with stable event IDs and
bounded retries.
- **Migration action:** Existing clients need no change. To read declined or timed
reviews, send `Accept: application/vnd.publora.company-approval.v2+json,
application/json` on approval reads; to manage `approval.decided`, send
`Accept: application/vnd.publora.company-webhooks.v2+json` on Company webhook
requests. Older clients receive `409 *_CLIENT_UPDATE_REQUIRED` for those
records instead of a silently changed shape. Refresh the MCP tool catalogue. See
[Agency LinkedIn Page reshares](guides/agency-linkedin-reshares.md) and
[Agency webhooks](guides/agency-webhooks.md#approval-decisions).
### TikTok automatic photo music — publora.com #790
- **Affected surface:** personal and Company REST draft create/update, personal
`create_post`/`update_post`, Company `company_create_post`/`company_update_post`,
and the personal/Agency editors.
- **Tag:** Additive, opt-in. Publish this documentation with or after the
[feature rollout](https://github.com/publora/publora.com/issues/790).
- **Change:** Optional boolean `platformSettings.tiktok.autoAddMusic` asks TikTok
to automatically choose music for photo Direct Post. Publora cannot select or
preview a specific track. Explicit `false` and omission are preserved; videos
never send this parameter. Enabling it for known non-photo media and invalid
types fail validation; `false` allows switching to video, and incomplete drafts
remain allowed.
- **Migration action:** Existing callers need no change. Agency clients preserve
the complete settings map on update and request a new client approval after
changing this publishing setting when review is required. See
[TikTok music](platforms/tiktok.md#automatic-music-for-photo-posts).
### Independent Company MCP operations — publora.com #780
- **Affected surface:** the 13 Company MCP dispatchers are replaced by 48 independently exposed operations (20 personal / 68 total tools).
- **Tag:** Breaking MCP names and argument envelopes; personal contracts, Company REST endpoints and OAuth are unchanged.
- **Change:** Each operation has a specific schema, description and effect annotations. Arguments move out of `command`; choose the operation by its tool name instead of `action`.
- **Migration action:** Refresh the client's tool catalogue after the [server rollout](https://github.com/publora/publora.com/issues/780). Follow the [Company tool reference](mcp/tools-reference.md#company-tools-52); do not send the old wrappers. This documentation must publish with or after that server deployment.
### 2026-08-25 — scheduledTime strict-mode ramp
- **Affected surface:** REST `create-post` and `update-post`, plus MCP tools that schedule through them.
- **Tag:** **Potentially breaking**, configuration-dependent.
- **Change:** A `scheduledTime` at least five minutes in the past is scheduled to return `400 SCHEDULED_TIME_IN_PAST` starting on 2026-08-25. This calendar behavior applies only when production configuration does not explicitly override it with `SCHEDULED_TIME_STRICT`; an explicit flag wins in either direction.
- **Migration action:** Always send a future ISO 8601 UTC time. During the warn-first period, inspect `warnings[].code === "SCHEDULED_TIME_COERCED"` and the returned `scheduledTime` to find callers that need correction.
## 2026-11-11
### Zapier app 1.3.0 leaves beta
- **Affected surface:** No REST or MCP contract change. The native Zapier app is out of beta at version 1.3.0, built on the public API and [webhooks](endpoints/webhooks.md).
- **Tag:** Additive.
- **Change:** New instant triggers **New Failed Post** (`post.failed`) and **Post Returned to Draft** (`post.demoted`). New actions **Create LinkedIn Comment**, **Add LinkedIn Reaction** and **Reshare LinkedIn Post**. **Create Post** adds **Publish Now**, up to three first comments and **Platform Options**; **Update Post** can also change the text and accounts. The [Zapier guide](examples/no-code/zapier-integration.md) is updated.
- **Migration action:** None.
## 2026-11-06
### OpenAPI covers the Agency core flow
- **Affected surface:** documentation only: `/openapi.yaml` and `/openapi.json`.
- **Tag:** Documentation change; runtime behaviour is unchanged.
- **Change:** The schema now describes Company context (`/company/contexts/v2`,
Workspace context), channels (`/company/connections`), post group detail,
schedule, reschedule, unschedule, recover and client reviews
(`/company/post-groups/:postGroupId/approval`). Draft, media and platform
operations have typed responses instead of a generic `data` object; the create
draft and media list operations no longer list error statuses they cannot return.
- **Migration action:** Clients generated from the schema should regenerate. The
generic `CompanyCommandResponse` schema is replaced by operation-specific
response schemas. See the [Agency quickstart](guides/agency-quickstart.md) for
the flow.
### Legacy workspace API removed from the documentation; Agency quickstart added
- **Affected surface:** documentation only. The `/api/v1/workspace/*` endpoints,
the `x-publora-user-id` header, managed-user errors and the Workspace / B2B
guide are no longer documented.
- **Tag:** Documentation change. Runtime behaviour is unchanged; the legacy
workspace API will be disabled later.
- **Change:** Agency client work is documented only through the Company API and
the `company_*` MCP tools. The new [Agency quickstart](guides/agency-quickstart.md)
walks through context, channels, draft, media, client review, scheduling and
recovery. `usageScope: "legacy_workspace"` in account context is unchanged.
- **Migration action:** New integrations that manage client posts should use the
[Agency quickstart](guides/agency-quickstart.md).
## 2026-11-05
### Agency LinkedIn Page post, comment and reaction reads — publora.com #871, #877
- **Affected surface:** Company REST `POST /linkedin-page-posts/batch`,
`POST /linkedin-page-posts/comments` and `POST /linkedin-page-posts/reactions`,
and the read-only MCP tools `company_get_linkedin_page_posts_batch`,
`company_list_linkedin_page_post_comments` and
`company_list_linkedin_page_post_reactions` (52 Company / 72 total tools).
Released in [publora.com PR #874](https://github.com/publora/publora.com/pull/874)
and [PR #879](https://github.com/publora/publora.com/pull/879).
- **Tag:** Additive, read-only.
- **Change:** Read up to 50 known posts of a connected Company Page in one request,
optionally with comment and reaction summaries; per-post failures are returned
next to the successful items. List the top-level comments or reactions of one
published Page post with offset paging. Engagement reads need Workspace analytics
view access and the Page's `r_organization_social_feed` permission. Batch reads
need a Page connection authorized through Publora's current LinkedIn app. New
errors: `403 LINKEDIN_BATCH_UNAVAILABLE` and, with reconnect steps in `message`,
`403 LINKEDIN_INSUFFICIENT_SCOPE`.
- **Migration action:** None for existing callers. To use the new reads with an
older Page connection, reconnect the Page through the Workspace's **Copy
reconnect link** as the error message describes. Refresh the MCP tool catalogue.
See [Agency LinkedIn Page reads](guides/agency-linkedin-page-reads.md).
## 2026-11-04
### AI-generated content disclosure — publora.com #836
- **Affected surface:** personal REST `create-post`/`update-post`, MCP `create_post`/`update_post`,
Company REST draft create/update and `company_create_post`/`company_update_post`, and the
personal/Agency editors. Released in [publora.com PR #844](https://github.com/publora/publora.com/pull/844).
- **Tag:** Additive, opt-in.
- **Change:** Optional boolean `platformSettings.{instagram,tiktok,youtube,twitter}.aiGenerated`
(default `false`) self-discloses realistic AI-generated or AI-altered media. It is sent as
Instagram `is_ai_generated` on the published container (carousel parent only; Instagram cannot
change the label after publishing), TikTok `is_aigc`, YouTube `status.containsSyntheticMedia`
and X `made_with_ai` (only when the post attaches media, on the head tweet of a thread).
`twitter` becomes a Company settings owner with `aiGenerated` as its only Company setting;
`replyTo`/`quoteTweet` stay personal-API only. A personal `update-post` that changes
`instagram.aiGenerated` once publishing has started returns `409 POST_PUBLISH_IN_PROGRESS`,
like a content edit.
- **Migration action:** None for existing callers; the default leaves provider requests unchanged
(TikTok video uploads keep sending `is_aigc: false`). Agency clients preserve the complete
settings map on update and request a new client approval after changing this setting when
review is required. See [AI-Generated Content Disclosure](endpoints/create-post.md#ai-generated-content-disclosure)
and [Agency platform settings](guides/agency-platform-settings.md#ai-generated-content-disclosure).
## 2026-10-22
### Agency Workspace webhooks — publora.com #775
- **Affected surface:** Company `/webhooks` REST API and new `company_webhooks` MCP tool (13 Company / 33 total tools).
- **Tag:** Additive.
- **Change:** Workspace managers configure post-published/failed subscriptions with HMAC signatures and create/rotate secret responses; personal and Company subscriptions are isolated.
- **Migration action:** Existing personal integrations need no change. Use the selected Workspace header and stable mutation idempotency keys for Company subscriptions. See [Agency webhooks](guides/agency-webhooks.md).
### Agency platform formats and settings — publora.com #775
- **Affected surface:** Company draft REST API and `company_save_post` / `company_media` MCP tools.
- **Tag:** Additive. Discover available capabilities with Company `/platforms` before use.
- **Change:** Instagram Stories and Reels cover URLs/feed sharing, Threads reply controls, LinkedIn reposts, TikTok commercial disclosure, YouTube tags/channel-bound playlists and trusted auxiliary thumbnail uploads. Publishing settings and thumbnail changes invalidate client approval.
- **Migration action:** Existing clients need no change. New clients preserve the complete settings map on updates and use the Company reserve → PUT → complete flow for thumbnails; personal upload endpoints are not interchangeable. Reels covers use a public HTTP(S) JPEG URL (empty clears); `shareToFeed` defaults to true. See [Agency platform settings](guides/agency-platform-settings.md).
## 2026-10-15
### Post-log retention — publora.com #663
- **Affected surface:** `GET /api/v1/post-logs/:postGroupId`.
- **Tag:** **Potentially breaking** retention change.
- **Change:** Responses include events from the last 90 days by event `createdAt`,
oldest first, limited to 100 entries. Old diagnostic events expire
asynchronously; post groups and published post history remain available.
- **Migration action:** Handle HTTP 200 with `success: true` and `logs: []` for
an owned group without recent events. Events older than 90 days are no longer
returned; store diagnostic events on your side if your integration requires a
longer history. Ownership and 404 behavior are unchanged. See
[Post logs](endpoints/post-logs.md).
## 2026-10-02
### Publish Now — publora.com #608, #610
- **Affected surface:** personal REST `create-post` and `update-post`; MCP `create_post` and `update_post`; `GET /account-context` and MCP `account_context` queue counts.
- **Tag:** Additive.
- **Change:** `publishNow: true` publishes immediately at server time. It uses the monthly post allowance (`POST_LIMIT_REACHED` still applies) but takes no slot in the scheduled-post queue and ignores the schedule horizon. Combining it with a future `scheduledTime` or `status: "draft"` returns `400 PUBLISH_NOW_CONFLICT`; a non-boolean value returns `400 INVALID_PUBLISH_NOW`. Moving a scheduled post to Publish Now frees its queue slot and keeps its monthly reservation. A `scheduledTime` within a few seconds of server time is still treated as immediate for existing clients.
- **Docs:** `GET /account-context`, released with publora.com #589 on 2026-10-01, now has its own [REST reference page](endpoints/account-context.md) and OpenAPI entry.
- **Migration action:** None. New integrations should send `publishNow: true` instead of a current `scheduledTime`. See [Publish now](endpoints/create-post.md#publish-now).
## 2026-10-01
### YouTube granted scopes — publora.com #490
- **Affected surface:** REST `POST /test-connection/{platformId}`, YouTube only. Released in [backend PR #590](https://github.com/publora/publora.com/pull/590) on 2026-10-01.
- **Tag:** **Potentially breaking** permission values, with an additive `permissionsKnown` field.
- **Change:** `permissions` returns Google's recorded full scope URIs, such as `https://www.googleapis.com/auth/youtube`, instead of the fixed short `youtube.upload` and `youtube.readonly` list. A broad grant is not expanded into narrower grants. Connections without recorded scopes return `permissions: []` with `permissionsKnown: false`.
- **Migration action:** Handle `permissionsKnown: false` as unknown; recognize broad `youtube` access when checking capabilities. Do not require the old short scope labels or treat an unknown empty list as denied access. See [YouTube connection diagnostics](endpoints/test-connection.md#youtube-permissions--490-update).
### `account_context` MCP tool — publora.com #589
- **Affected surface:** New MCP tool `account_context`, which brings the personal MCP toolset from 19 to 20 tools. It reads the new REST endpoint `GET /api/v1/account-context` with the same API key.
- **Tag:** Additive.
- **Changes:**
- `account_context` is read-only. It returns the plan, available features, publishing quotas (monthly platform posts, scheduled posts, connected channels), the schedule horizon with `maxScheduledDate`, and `allowedPlatforms` for the personal account behind the key. Quotas count platform posts, `limit: null` means unlimited, and a per-connection monthly limit (`scope: "connection"`) is broken down in `quotas.monthlyPosts.connections[]`.
- The optional `scheduledTime` (ISO 8601 with `Z` or an offset) selects the monthly quota period of a planned batch. A past time resolves to the current period, and `effectiveQuotaTime` shows the date used. A malformed value returns `400 INVALID_SCHEDULED_TIME` from the REST endpoint; the MCP tool rejects it before calling the API.
- The response is an advisory snapshot (`advisory: true`): it reserves nothing, and every write is still checked against the limits.
- **Migration action:** None. Optionally, call `account_context` before a batch of posts and after a quota or feature error. See [account_context](mcp/tools-reference.md#account_context).
## 2026-09-30
### `connectionStatus` on connections — publora.com #526
- **Affected surface:** REST `GET /platform-connections`; MCP `list_connections`.
- **Tag:** Additive. The field has been returned since publora.com #526 was merged on 2026-09-25, and is documented from 2026-09-30.
- **Changes:**
- Each connection carries `connectionStatus`: `active` or `reconnect_required`, Publora's verdict on whether it can publish with the connection now. It is computed from stored data (reconnect flags, stored credentials, access-token expiry) without calling the platform. See [`connectionStatus` and `tokenStatus`](endpoints/platform-connections.md#connectionstatus-and-tokenstatus).
- It differs from `tokenStatus` in two systematic cases. Telegram connections store no expiry date and are never flagged, so `tokenStatus` is always `unknown` while `connectionStatus` is `active`. An X or YouTube account reported suspended is `reconnect_required` while its `tokenStatus` stays `valid`.
- Documentation corrections, no behavior change: `displayName` and `profileImageUrl` can be `null`, and `subscriptionType` (X only: `None`, `Basic`, `Premium`, `PremiumPlus`, re-checked when publishing to X at most once a day) is now in the OpenAPI schema.
- **Migration action:** Prompt a reconnect on `connectionStatus: "reconnect_required"` instead of `tokenStatus: "expired"`, and keep using `tokenStatus: "expiring_soon"` for advance warnings. Clients generated from the OpenAPI spec should treat `displayName` and `profileImageUrl` as nullable.
## 2026-09-29
### Ordered first comments and Agency first comment — publora.com #537, #538, #552
- **Affected surface:** personal REST `create-post`, `update-post`, `get-post`; MCP `create_post`, `update_post`, `get_post`; Agency Company post save and detail routes and MCP tools.
- **Tag:** Additive.
- **Change:** Personal posts accept `firstComments[]` with up to three ordered `{text, platforms?, delaySeconds?}` items. Delay is 0–86,400 seconds and delivery runs on scheduler ticks. A later comment waits for the previous one to post; failure stops the sequence. `firstComments: null` or `[]` clears it on update. Supplying both `firstComment` and `firstComments` returns `400 FIRST_COMMENT_INVALID`.
- **Read contract:** `get-post` / `get_post` return group `firstComments[]` and per-target `firstCommentResults[]`. Existing `firstComment` / `firstCommentResult` fields remain aliases for item 0; old documents read as a one-element array.
- **Agency:** Company draft save accepts one `firstComment`; Company post detail returns its per-target result. Multiple comments and delays remain personal-only. See the [Agency first comment guide](guides/agency-first-comments.md).
- **Migration action:** none for clients using the single-comment fields.
### Telegram: private channels over a bot connection — publora.com #570
- **Affected surface:** Telegram bot connections (dashboard and client connection pages); REST `GET /platform-connections` and `POST /test-connection/{platformId}`; MCP `list_connections`.
- **Tag:** Additive; **potentially breaking** for clients that assume `username` is always a string. Behavioral change for `test-connection`: a Telegram bot connection whose token still works can now return `error` where it returned `ok`, and its message strings changed.
- **Changes:**
- The channel field accepts a public channel's `@username` or `t.me/username`, and for a private channel its `-100…` chat ID or a `t.me/c/…` link to any of its messages. Invite links (`t.me/+…`, `t.me/joinchat/…`) are rejected with guidance, because the Bot API cannot identify a channel from them. See [Telegram](platforms/telegram.md#bot-connection-default).
- A channel without a public username is saved with `username: null`, and `displayName` holds the channel title. `GET /platform-connections`, `test-connection` and `list_connections` return that `null`. The platform ID comes from the chat ID, as for any bot connection, for example `telegram--1001234567890`.
- `test-connection` on a Telegram bot connection now also checks that the bot can read the channel and is an administrator allowed to post, not only that the token works. A passing check returns `Bot can post to ` instead of `Connected as @`; the new failure messages include `Channel is unavailable` and `Bot needs channel administrator posting rights`, and Telegram API errors from the new channel checks (for example, a bot removed from a private channel) return `Request failed with status code `. MTProto connections now fail with `Invalid bot connection` instead of `Invalid bot token`. See [Test Connection](endpoints/test-connection.md#telegram-connections).
- **Migration action:** Treat `username` as nullable and label connections by `displayName` when it is `null`. Keep targeting posts by `platformId`. If you gate scheduling on `test-connection`, a Telegram connection that now returns `error` needs its bot's administrator posting rights restored in Telegram.
### Media URL errors: hosts that resolve to private addresses report `MEDIA_URL_BLOCKED_HOST` — publora.com #565
- **Affected surface:** REST `create-post` and `update-post` (`mediaUrls`) and `POST /attach-media/{postGroupId}`; MCP `create_post`, `update_post` and `attach_media`.
- **Tag:** Fix.
- **Change:** When a media URL's host, or a redirect target, resolves to a private or reserved address, `mediaResults[].code` is now `MEDIA_URL_BLOCKED_HOST`. It was reported as `MEDIA_URL_FETCH_FAILED` before. The download was refused then and still is; only the code and message change. A DNS lookup that fails is still reported as `MEDIA_URL_FETCH_FAILED`, whether the domain does not exist or the host has no A or AAAA records. See [`mediaUrls` per-URL codes](guides/error-codes.md#mediaurls-per-url-codes).
- **Migration action:** Clients that treated `MEDIA_URL_FETCH_FAILED` as retryable for such hosts should not retry `MEDIA_URL_BLOCKED_HOST`; it needs a publicly reachable URL.
## 2026-09-28
### ChatGPT file attachments — publora.com #539
- **Affected surface:** New REST endpoint `POST /attach-media/{postGroupId}` and new MCP tool `attach_media`, which brings the personal MCP toolset from 18 to 19 tools. The existing `mediaUrls` and presigned-upload flows are unchanged.
- **Tag:** Additive.
- **Changes:**
- `attach_media` declares `_meta["openai/fileParams"]: ["file"]`, so ChatGPT passes a file from the conversation as `{ download_url, file_id, mime_type?, file_name? }`. Images ChatGPT generates can be attached when the client exposes them as file references. The `openai/fileParams` declaration is included in authenticated `tools/list`, in unauthenticated discovery and in the server card.
- The endpoint accepts only `{ file, fileName? }`. It downloads the file right away through the `mediaUrls` pipeline (images up to 25 MB, videos up to 150 MB, type detected from the bytes, then probed) and attaches it as `ready`. It always leaves the post in `draft`, so a scheduled post is demoted (without a `post.demoted` webhook), and it never publishes. The optional `fileName` (1–255 characters, cleaned to a safe name) becomes `media[].sourceFileName`. Without it, the name comes from `file.file_name`, or is `chatgpt-media` when that is absent.
- `Idempotency-Key` matches on the post ID, `file_id` and file name, not the expiring `download_url`, so a retry with a refreshed URL replays the first result instead of attaching the file twice. The MCP tool sends a stable key by default. A failed download frees the key.
- New top-level 400 code `INVALID_MEDIA_FILE` for any other body field, a malformed file object, a `download_url` that fails the static URL checks, or an invalid file name.
- **Migration action:** None for existing callers. ChatGPT users who already added the Publora connector should refresh its tool list so `attach_media` appears.
### First comment for LinkedIn company Pages — publora.com #533, #534
- **Affected surface:** REST `create-post`, `update-post`, `get-post`; MCP `create_post`, `update_post`, `get_post` — LinkedIn targets only.
- **Tag:** Additive.
- **Change:** A LinkedIn company Page connection now gets the first comment too, posted as the organization (`urn:li:organization:`), the way its posts are published. Before this change, Page targets were recorded as `skipped` with `skipReason: "unsupported_account_type"`; that reason now only remains on results recorded before the change.
- **Migration action:** none.
### First comment (wave 1) — publora.com #529, #530
- **Affected surface:** REST `create-post`, `update-post` and `get-post`; MCP `create_post`, `update_post` and `get_post`.
- **Tag:** Additive.
- **Changes:**
- New optional top-level `firstComment { text, platforms? }` on create and update: a text comment posted under the account's own post right after it publishes. `platforms` are platform types (never connection IDs); omitted = every supported target. Wave 1 platforms: LinkedIn member profiles (company Pages followed in publora.com #534), X, Threads, Bluesky, Mastodon.
- Length is validated per applicable platform (X 280 / 25,000 Premium-only, LinkedIn 1,250, Threads 500 code points, Bluesky 300 graphemes and 3,000 bytes, Mastodon 500 with links = 23) with an absolute cap of 25,000. New 400 codes `FIRST_COMMENT_INVALID`, `FIRST_COMMENT_PLATFORM_UNKNOWN`, `FIRST_COMMENT_TOO_LONG`; new warnings `FIRST_COMMENT_PLATFORM_NOT_TARGETED`, `FIRST_COMMENT_UNSUPPORTED_PLATFORMS`.
- `get-post` / `get_post` return the stored `firstComment` (or `null`) and a per-target `posts[].firstCommentResult` (`pending | posted | failed | skipped`, `commentId`, `skipReason`, `attemptedAt`, `postedAt`, `error` with `outcomeUnknown`). The comment is attempted once, right after publish, and never retried; a failed comment never changes the published post.
- On `update-post`, `firstComment: null` removes the comment; changing only the time leaves it untouched; the stored comment is re-validated when `platforms` change.
- **Migration action:** none. Clients that mirror `get-post` responses should tolerate the two new keys.
## 2026-09-24
### LinkedIn image-only comments
- **Affected surface:** REST `POST /linkedin-comments` and MCP `linkedin_create_comment`.
- **Tag:** Additive validation change.
- **Change:** `message` remains a required string, but `message: ""` with a valid `imageUrl` is accepted for personal and organization comments. Text and image URLs are trimmed. Blank text without an image still returns HTTP 400, now with `message cannot be empty without imageUrl`. No placeholder text is inserted; failed image validation or upload prevents publication.
- **Migration action:** Callers can send an empty string with `imageUrl` instead of padding image-only comments with text. Existing text comments are unchanged.
## 2026-09-14
### Threads multi-part chains — publora.com #472, #474
- **Affected surface:** REST `create-post`, `update-post` and `get-post`; MCP `create_post`, `update_post` and `get_post`; `GET /platform-limits`.
- **Tag:** Additive, with one behaviour change for over-limit Threads content.
- **Changes:**
- Meta Threads now supports multi-part chains. `platforms.threads.requirements.supportsThreading` in `GET /platform-limits` is `true`; it was `false`.
- Threads content over 500 characters is **no longer rejected**. It is accepted and split into a chain instead of being rejected with `CONTENT_TOO_LONG` in `validation.errors[]`. A successful request carries no `validation` object, so there is nothing new to read on success — the split is simply performed. A standalone `---` line, or a complete `[n/m]` marker set, splits the content explicitly; automatically derived parts get a ` (1/N)` suffix, explicit ones are published verbatim. Media attach to the first part only.
- `get-post` `posts[]` entries gained **`isThread`** (boolean) and **`threadParts`** (array). Both are always present — `false` and `[]` for a non-chain target. Each part carries `index` (zero-based), `content`, `status` (`pending`, `published`, `failed`) and `publishedId` (`null` until confirmed). `postedId` is the first part's ID. `list-posts` does not include these fields. The same fields reach MCP through `get_post`, which passes the REST body through unchanged. They are populated for X/Twitter chains as well as Threads.
- Scheduling a Threads chain requires the connection to have granted `threads_manage_replies`. The grant is checked at scheduling (from a per-connection cache up to five minutes old) and re-checked against Meta immediately before publishing: a missing grant returns `400` with `THREADS_PERMISSION_REQUIRED` in `validation.errors[]` and nothing is published. A failure of the permission lookup itself returns `503` with `{ "code": "THREADS_PERMISSIONS_UNAVAILABLE", "error": … }` and no `validation` object — that one never means reconnect. `GET /platform-connections` does not report granted scopes, so the grant cannot be pre-checked.
- New publish-time codes in `posts[].error.code`: `THREADS_INVALID_THREAD_PART`, and `THREAD_PARTIALLY_PUBLISHED` / `PUBLISH_OUTCOME_UNKNOWN` now reachable for Threads. A chain with published parts is never republished from the beginning.
- The error message `"Multi-part threads (nested replies) are temporarily blocked while we wait for Meta to approve additional permissions for our app."` no longer occurs.
- **Migration action:** If your client special-cased Threads by truncating text at 500 characters or by treating over-limit content as a hard error, that workaround is now unnecessary. After a partial or unknown publication, read `threadParts` and publish only the missing parts — do not resubmit the post.
## 2026-09-08
### Mastodon and Bluesky statistics — publora.com #460
- **Affected surface:** New REST endpoints `POST /post-statistics` and `POST /profile-statistics`, and new MCP tools `post_stats` and `profile_stats`. Nothing existing changes shape.
- **Tag:** Additive.
- **Changes:**
- `POST /post-statistics` takes `{ posts: [{ platform, platformId, postedId }] }` (1–50 entries, `mastodon` and `bluesky`, both platforms may be mixed in one request) and returns `stats` keyed by `postedId`. Each value is a metric object — `reactions`, `comments`, `reposts`, `quotes`, `saves`, `impressions`, `reach`, `clicks` — or `null`. Every key is always present; a metric the platform does not expose is `null`, never `0`.
- `POST /profile-statistics` takes `{ platform, platformId }` and returns `profile` (`followers`, `following`, `posts`) with `cached` and `fetchedAt`, or `404` when the connection is not the caller's.
- `platformId` is accepted with or without the `-` prefix returned by `GET /platform-connections`.
- Per-connection problems do not fail the request: `post-statistics` reports them in an `issues` object keyed by connection ID (`CONNECTION_NOT_FOUND`, `AUTH_REVOKED`, `FORBIDDEN`, `RATE_LIMITED`, `FETCH_FAILED`), and `profile-statistics` reports them in `unavailable` and `rateLimited`.
- Both endpoints, and both MCP tools, are gated by the analytics plan feature that already gated the LinkedIn analytics endpoints; a plan without it receives `403 ANALYTICS_PLAN_REQUIRED`. A request that exceeds its 90-second budget returns `504 ANALYTICS_REQUEST_TIMEOUT`.
- Values are fetched from the platform on request and cached for about 2 hours. Nothing is collected in the background, so there is no history — only the counters as they stand when you ask.
- **Known limitation:** only posts Publora published for you **and stored a platform post ID for** can be queried. Publora began storing `postedId` for Mastodon and Bluesky on 2026-09-07; posts published before that have no `postedId` and are answered `null`. For a thread, only the root part is addressable.
- **Migration action:** None. New capability.
## 2026-08-27
### Native Zapier app (beta)
- **Affected surface:** No REST or MCP contract change. Publora now has a native app on Zapier (beta, v1.2.0), built on the public API and [webhooks](endpoints/webhooks.md): instant triggers **New Published Post** and **New Scheduled Post**, actions **Create Post**, **Update Post** and **Delete Post**, and searches **Find Connected Account** and **Find Posts**.
- **Tag:** Additive.
- **Change:** The [Zapier guide](examples/no-code/zapier-integration.md) was rewritten for the native app. It previously documented a workaround through Webhooks by Zapier; that approach still works and stays documented on the same page for endpoints the app does not expose.
- **Migration action:** None. Existing Webhooks-by-Zapier Zaps keep working; the native app is the recommended path for new Zaps.
## 2026-08-24
### Connection health reporting corrected — publora.com #407
- **Affected surface:** REST `GET /platform-connections` and the MCP `list_connections` tool, which passes that response through unchanged. `test-connection` reports the same corrected expiry.
- **Tag:** **Behavioral correction.** No request shape changes, no field is added or removed; two response fields now report different — and correct — values for some connections.
- **Changes:**
- `accessTokenExpiresAt` now carries the **effective** credential expiry, the same value `tokenStatus` and `tokenExpiresIn` are derived from, instead of the raw stored access-token timestamp. For YouTube it is now always `null`: the access token is refreshed on demand before each publish, and Google publishes no refresh-token lifetime, so no authoritative date exists. TikTok continues to report its real refresh-token expiry; every other platform is unchanged.
- Previously, healthy YouTube and TikTok connections returned a timestamp already in the past alongside `tokenStatus: "valid"`. Clients that compared that date against the current time concluded the connection was dead and prompted users to reconnect working channels.
- `tokenStatus` now returns `expired` for any connection Publora has flagged for reconnection after the platform rejected its credential — including on platforms that never expire on a schedule, where such a connection previously reported `valid`. In that case `accessTokenExpiresAt` may be `null` or still in the future.
- **Migration action:** Decide about reconnecting from **`tokenStatus`**, not by comparing `accessTokenExpiresAt` against the clock. Treat `expired` as "prompt the user to reconnect" and `expiring_soon` as "warn". Treat a `null` expiry as "no scheduled expiry", never as a problem. The examples on the endpoint, guide and MCP pages were rewritten accordingly; code copied from earlier versions of those examples should be updated.
### X replies and quote posts — publora.com #405
- **Affected surface:** REST `create-post` and `update-post`, the MCP `create_post` and `update_post` tools, and the `posts[].error.code` reported by `GET /get-post` and the `post.failed` webhook.
- **Tag:** Additive. No existing request shape changes behavior.
- **Changes:**
- `platformSettings` accepts a new top-level `twitter` object with two string keys, `replyTo` and `quoteTweet`. Both take a full `x.com`/`twitter.com` status URL or a bare 1–19 digit post ID, and both are normalized to the numeric ID before storage, so `GET /get-post` echoes the ID rather than the URL you sent.
- `replyTo` publishes the post — or the head part of a thread — as a reply to the target; the remaining thread parts chain under it as before. `quoteTweet` applies to the single post or the thread head only. The two fields combine with each other and with media. An empty string clears either one.
- A malformed reference is rejected at intake with `400` and a plain `error` message (`platformSettings.twitter.replyTo must be a tweet URL (https://x.com/user/status/123...) or a numeric tweet ID`); no `code` field accompanies it. An unknown key under `twitter` is still `400 PLATFORM_SETTING_UNKNOWN`, which is evaluated first.
- Two publish-time codes were added: `X_REPLY_NOT_AUTHORIZED` when X refuses the reply or quote relationship, and `X_TARGET_REJECTED` when the target is deleted, protected, or its author blocked the account. Both are permanent — `retryable: false`.
- `twitter` is no longer an example of a rejected `platformSettings` platform; the allowlist now has seven platforms.
- **Restriction to know before integrating:** X allows a programmatic reply or quote on self-serve API tiers only when the target post's author mentioned the connected account **in that same post**, quoted one of the account's posts, or the connected account authored the target. Enterprise apps are exempt. Publora cannot check that relationship at intake, so an unrelated target is accepted by `create-post`/`update-post` and fails later at publish time.
- **Migration action:** None for existing callers. New integrations should treat these fields as inbound-engagement and own-post tools, match on `error.code` rather than message text, and not retry `X_REPLY_NOT_AUTHORIZED` or `X_TARGET_REJECTED` with the same target.
## 2026-08-03
### MCP OAuth consent no longer asks for an API key
- **Affected surface:** the OAuth 2.1 flow on `mcp.publora.com` (Dynamic Client Registration + PKCE), used by claude.ai's custom connector, Claude Code, Codex/ChatGPT, Cursor, VS Code, Manus and other browser-capable clients.
- **Tag:** Behavioral, non-breaking for existing credentials.
- **Change:** The consent step is a sign-in-and-approve page — *"An application is requesting access to your Publora account"*, naming the account being authorized, with **Approve** and **Cancel**. It no longer asks you to paste an `sk_...` key; that step was replaced when SSO login shipped on 2026-07-27, and the wording was finalized on 2026-08-03. On approval Publora mints a dedicated API key for that client registration, named `MCP ( #)`, and returns it as the access token. Static API-key headers (`Authorization: Bearer sk_...` / `x-publora-key`) are unaffected and remain the option for headless clients.
- **Migration action:** None for connectors that already work. Re-authorizing a client mints a fresh key; per-client keys are listed and revocable on the **API** page in the dashboard. If you built on the old instructions and expected a key-paste page, drop that step.
## 2026-07-21
### Editable draft and scheduled posts — publora.com #231
- **Affected surface:** REST `PUT /update-post/:postGroupId` and the MCP `update_post` tool.
- **Tag:** Additive, with new stable conflict codes.
- **Changes:**
- `update-post` accepts two new optional patch fields: `content` (replacement base text) and `platforms` (replacement target set). Omitting a field leaves the stored value unchanged.
- A `content` edit rewrites every platform post to its effective text while preserving explicit per-account overrides; editing the text of a Twitter or Threads target clears its derived thread split.
- A `platforms` edit replaces the whole target set: dropped IDs have their platform posts deleted, added IDs are validated for ownership and plan entitlement, and adding a target to a scheduled post re-runs scheduling limits plus full content/media validation. `[]` is accepted only while the post remains a draft.
- Added stable codes `POST_NOT_EDITABLE` (400), `POST_PUBLISH_IN_PROGRESS` (409), and `POST_GROUP_VERSION_CONFLICT` (409), plus `INVALID_CONTENT`, `INVALID_PLATFORMS`, `INVALID_PLATFORM_CONNECTION`, and `INVALID_PLATFORM_ID` (400). The pre-existing `"Cannot update post: post is currently in {status} status"` 400 now also carries `code: "POST_NOT_EDITABLE"`.
- The success snapshot's `postGroup` now always includes the effective `content` and `platforms`.
- The "at least one field" error text changed to `"At least one of status, scheduledTime, content, platforms, platformSettings, or mediaUrls must be provided"`.
- `platforms` arrays on both `create-post` and `update-post` now reject duplicate connection IDs with `400 "Platforms must not contain duplicates"`.
- MCP `update_post` exposes `content` and `platforms`, and instructs clients to call `list_connections` before changing targets.
- **Migration action:** No change is required for existing callers. Integrations that previously deleted and recreated a post to fix its text or targets should switch to `update-post`. Match on the new `code` values rather than message text, send an `Idempotency-Key` with content/platform edits, and re-read the post with `GET /get-post` on a 409 instead of blind-retrying. If you relied on a repeated connection ID in `platforms` being tolerated, de-duplicate the array.
## 2026-07-17
### LinkedIn mentionable-people directory — publora.com #218
- **Affected surface:** REST and MCP.
- **Tag:** Additive.
- **Changes:** Added `GET /linkedin-mentionables` and the `linkedin_list_mentionables` MCP tool (the 15th active tool). Both list the per-user directory of native LinkedIn member ids captured automatically from engagement on connected company pages, with `q`/`limit` filtering and a ready-to-paste `mention` token per person. Paid plans only — free plans receive `403 UPGRADE_REQUIRED`.
- **Migration action:** None. New integrations that build person mentions should prefer this directory over harvesting actor URNs manually.
## 2026-07-15
### API/MCP correctness release — publora.com #198
- **Affected surface:** REST create/update/get-post, webhooks, MCP sessions and tool responses.
- **Tags:** **Breaking** for unknown `platformSettings` paths; additive/behavioral for the remaining items.
- **Changes:**
- Added Mongo-backed `Idempotency-Key` handling to create/update.
- Added the warn-first `scheduledTime` ramp and structured coercion/rejection codes.
- Unknown `platformSettings` paths now return `400 PLATFORM_SETTING_UNKNOWN`; they are no longer silently discarded.
- Added MCP session admission checks and more robust MCP response parsing.
- Publication identity now flows through get-post and `post.published`, including `platformId`, `postedId`, and nullable `permalink`.
- **Migration action:** Remove unknown settings before retrying; add idempotency keys to retryable create/update workflows; read publication identity from documented fields; audit past-time warnings before strict mode.
### LinkedIn repost/reshare — publora.com #194
- **Affected surface:** REST, MCP, and scheduled LinkedIn publishing.
- **Tag:** Additive.
- **Changes:** Added `POST /linkedin-reshare`, the `linkedin_create_reshare` MCP tool (the 14th active tool), and `platformSettings.linkedin` with `repostEnabled`, `repostParentUrn`, and `repostVisibility` as the sixth accepted settings branch.
- **Migration action:** No change is required for existing callers. New integrations should use a `urn:li:share:*` or `urn:li:ugcPost:*` parent. `CONNECTIONS` visibility is personal-profile-only; use `PUBLIC` for company-page reposts.
### Correctness-release documentation — publora-api-docs #21
- **Affected surface:** Public API, MCP, webhook, and OpenAPI documentation.
- **Tag:** Documentation.
- **Change:** Published the idempotency, scheduled-time, strict-settings, MCP-draft, and publication-identity contract introduced by the correctness release.
- **Migration action:** Compare existing integrations with the updated create/update, get-post, webhook, and MCP reference pages; no separate runtime change was introduced by the docs release.
## Deprecation policy
No additional public API deprecations are currently scheduled. Future entries will identify the affected surface, breaking behavior, effective date, and migration action.
---
> Source: https://docs.publora.com/endpoints/create-post
# Create Post
Schedule or immediately queue a post across multiple social media platforms.
## Endpoint
```
POST https://api.publora.com/api/v1/create-post
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `mcp` for MCP integrations). Affects which access controls are checked. |
| `Idempotency-Key` | No | Opt-in duplicate protection. A client-generated unique string. Retrying with the **same key and same body** replays the original response instead of creating a second post. See [Idempotency](#idempotency). |
| `Content-Type` | Yes | `application/json` |
> **Browser usage:** CORS permits `x-publora-key`, `x-publora-client`, and `Idempotency-Key`, but only requests from origins in Publora's deployment allowlist are accepted. An arbitrary integrator origin can still fail preflight. Even from an allowed origin, embedding a secret API key in client-side code exposes it; prefer a server-side proxy.
## Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Conditional | Normally required and non-empty. It may be omitted or empty when a targeted LinkedIn connection has repost intent through `platformSettings.linkedin.repostEnabled: true` or a non-empty `repostParentUrn`; the repost settings must still form a valid parent/enable combination. Non-string truthy values (numbers, objects) can pass the initial content gate but cause unexpected behavior. |
| `platforms` | string[] | Yes | Array of `-` connection IDs. The ID cannot contain whitespace, `/`, `?`, or `#`; colons are allowed (e.g., `twitter-123456789`, `bluesky-did:plc:abc123`). Each ID must appear at most once — a repeated ID is rejected with `400 "Platforms must not contain duplicates"`. |
| `scheduledTime` | string | No | ISO 8601 UTC datetime. If omitted, the post is created as a `draft`. A time in the past is **never silently accepted** — it is either clamped to server time with a `SCHEDULED_TIME_COERCED` warning in the response, or rejected with `400 SCHEDULED_TIME_IN_PAST`. See [Past scheduled times](#past-scheduled-times). |
| `publishNow` | boolean | No | `true` publishes immediately. The server uses its own current time as `scheduledTime`, creates the post as `scheduled` and starts delivery at once. Omitted or `false` keeps the default: a draft without `scheduledTime`, a scheduled post with it. Cannot be combined with a future `scheduledTime` or `status: "draft"` (`400 PUBLISH_NOW_CONFLICT`). See [Publish now](#publish-now). |
| `platformSettings` | object | No | Per-platform settings that are merged with server-side defaults. User-provided values override defaults on a per-platform basis. The accepted keys are `tiktok`, `instagram`, `youtube`, `threads`, `twitter`, `telegram`, and `linkedin`. **Any unknown top-level platform or unknown nested key is rejected with `400 PLATFORM_SETTING_UNKNOWN` and nothing is persisted** — see [Unknown platformSettings paths](#unknown-platformsettings-paths) for the exact accepted tree. Each platform key must map to a plain object. Validation errors (`"Invalid platformSettings JSON"`, `"platformSettings must be an object"`) are returned if the field is present and malformed. |
| `firstComment` | object | No | Legacy single-comment form `{ "text": "…", "platforms": ["linkedin"] }`; equivalent to the first item of `firstComments`. Do not send both fields. See [First comments](#first-comment). |
| `firstComments` | object[]/null | No | Up to three ordered `{ text, platforms?, delaySeconds? }` comments. `null` or `[]` means none. `platforms` are platform **types**, not connection IDs; `delaySeconds` is an integer from 0 to 86,400. See [First comments](#first-comment). |
| `mediaUrls` | string[] | No | Up to **10** public **https** image/video URLs. Publora downloads them server-side and attaches them to the post **before** validation, so you can attach media *and* schedule in one call (pass together with `scheduledTime`). This is the one-shot alternative to the draft → `get-upload-url` → schedule flow. Ingestion is rate-limited to 60 URLs/hour. See [Posts with Media](#posts-with-media). |
## Response
Returns HTTP **200** on success (not 201).
```json
{
"success": true,
"postGroupId": "507f1f77bcf86cd799439011",
"scheduledTime": "2026-03-01T14:00:00.000Z"
}
```
Use the `postGroupId` to track, update, or delete the post.
| Field | Always present | Description |
|-------|----------------|-------------|
| `success` | Yes | `true` on a 200 |
| `postGroupId` | Yes | Post group ID — use it to track, update, or delete the post |
| `scheduledTime` | Yes | The **effective** scheduled time actually stored (ISO 8601 UTC), or `null` for a draft. Trust this over the value you sent — a permitted past-time clamp may change it; a plan-horizon violation is rejected rather than adjusted. |
| `warnings` | No | Present only when the request was accepted with a caveat. Array of `{ code, message, requested, effective }`. |
| `media` | No | Per-URL ingestion results, present only when `mediaUrls` was supplied |
When a past `scheduledTime` is clamped, the response carries a warning and `scheduledTime` reflects the clamped value:
```json
{
"success": true,
"postGroupId": "507f1f77bcf86cd799439011",
"scheduledTime": "2026-03-01T14:03:11.000Z",
"warnings": [
{
"code": "SCHEDULED_TIME_COERCED",
"message": "Requested scheduled time 2026-03-01T14:01:00.000Z was in the past and was changed to server time 2026-03-01T14:03:11.000Z.",
"requested": "2026-03-01T14:01:00.000Z",
"effective": "2026-03-01T14:03:11.000Z"
}
]
}
```
## Publish now
Set `publishNow: true` to publish a post immediately instead of at a scheduled time:
```json
{
"content": "We just shipped dark mode 🌙",
"platforms": ["twitter-123456789", "linkedin-ABC123"],
"publishNow": true
}
```
- **Server time.** Publora assigns its own current time, so the client clock does not matter. The response is the usual `{ "success": true, "postGroupId": "…", "scheduledTime": "" }` and the post group is `scheduled`.
- **Asynchronous.** The response does not wait for the platforms. Read the outcome with [Get Post](get-post.md) or a [webhook](webhooks.md).
- **Same checks as scheduling.** Connections, plan platforms, content, media (Instagram, TikTok and YouTube still need media, otherwise `400 MEDIA_REQUIRED`) and first comments are validated exactly as for a scheduled post.
- **Limits.** Publish Now uses the monthly post allowance, so `403 POST_LIMIT_REACHED` still applies. It does **not** take a slot in the scheduled-post queue and ignores the schedule horizon: a Starter account with a full queue (3 of 3) can still publish now while it has monthly posts left.
- **Conflicts.** `publishNow: true` with a future `scheduledTime` or with `status: "draft"` returns `400 PUBLISH_NOW_CONFLICT`. A `scheduledTime` that is not in the future is ignored in favour of server time. A non-boolean `publishNow` returns `400 INVALID_PUBLISH_NOW`.
- **Retries.** A retried Publish Now request can publish twice. Send an [`Idempotency-Key`](#idempotency) and reuse it with the identical body.
> **Older clients.** A `scheduledTime` within a few seconds of server time is still treated as an immediate publication, so existing integrations keep working. New integrations should send `publishNow: true`.
## Past scheduled times
A `scheduledTime` in the past is handled by how far in the past it is. The 5-minute
tolerance absorbs ordinary client clock skew; anything beyond it is a real bug in the
caller's logic.
| How far in the past | Behaviour today | Behaviour when strict mode is active (scheduled 2026-08-25 by default) |
|---------------------|-----------------|----------------------------|
| Less than 5 minutes | Clamped to server time + `SCHEDULED_TIME_COERCED` warning | **Unchanged** — clamped + warned |
| 5 minutes or more | Clamped to server time + `SCHEDULED_TIME_COERCED` warning | **Rejected** with `400` / `SCHEDULED_TIME_IN_PAST` |
> **⚠️ Scheduled strict date — 2026-08-25.** Sending a `scheduledTime` 5+ minutes in the
> past currently succeeds with a warning. It is scheduled to become a hard `400` on
> **2026-08-25**, unless production configuration overrides that date either way.
> If you see `SCHEDULED_TIME_COERCED` in your responses today, fix it before that date:
> the usual causes are an unsynced client clock, a local-time value sent without a UTC
> offset, or replaying a stored `scheduledTime` from an earlier run. Compare your
> requested time against the `serverTime` / `effective` values the API returns.
> **The 5-minute tolerance is permanent.** The sunset changes the handling of times
> **5+ minutes** in the past and nothing else. A time 2 minutes in the past will still
> be clamped-and-warned after 2026-08-25, exactly as it is today.
The rejection body:
```json
{
"error": "Scheduled time is in the past. Server time is 2026-03-01T14:03:11.000Z UTC.",
"code": "SCHEDULED_TIME_IN_PAST",
"serverTime": "2026-03-01T14:03:11.000Z"
}
```
Use `serverTime` to measure your clock offset against Publora's.
## Unknown platformSettings paths
`platformSettings` is validated against a strict allowlist **before anything is
persisted**. An unrecognized top-level platform (e.g. `facebook`, `bluesky`) or an
unrecognized nested key returns `400` and creates no post:
```json
{
"error": "Unknown platformSettings path: youtube.thumbnail.mediaID",
"code": "PLATFORM_SETTING_UNKNOWN",
"field": "youtube.thumbnail.mediaID"
}
```
> **Why this matters:** a typo like `youtube.thumbnail.mediaID` (capital `D`) or
> `instagram.coverurl` previously passed silently and *wiped* the corresponding
> setting. It is now a loud `400` naming the exact `field`.
Nested reference objects are checked to their leaves — `youtube.playlist` and
`youtube.thumbnail` cannot carry extra keys. The complete accepted tree:
| Platform | Accepted keys |
|----------|---------------|
| `tiktok` | `viewerSetting`, `allowComments`, `allowDuet`, `allowStitch`, `autoAddMusic`, `commercialContent`, `brandOrganic`, `brandedContent`, `aiGenerated` |
| `instagram` | `videoType`, `shareToFeed`, `coverUrl` (alias `cover_url`), `aiGenerated` |
| `youtube` | `privacy`, `title`, `tags`, `madeForKids`, `aiGenerated`, `categoryId`, `playlist.{id,platformId}`, `thumbnail.{mediaId,id,url,path}` |
| `threads` | `replyControl` |
| `twitter` | `replyTo`, `quoteTweet`, `aiGenerated` |
| `telegram` | `disableNotification`, `disableWebPagePreview`, `protectContent` |
| `linkedin` | `repostEnabled`, `repostParentUrn`, `repostVisibility` |
`tiktok.autoAddMusic` is an optional JSON boolean for **photo Direct Post**.
Set `true` to let TikTok automatically choose music; Publora cannot select or
preview a specific track. Explicit `false` is preserved; omission does not
silently enable music. Enabling it for known non-photo media is rejected;
`false` disables music and permits switching to video. A draft without media
may save it for later photo uploads. See
[TikTok automatic photo music](../platforms/tiktok.md#automatic-music-for-photo-posts).
`aiGenerated` is an optional boolean on `instagram`, `tiktok`, `youtube` and
`twitter` (default `false`) that self-discloses realistic AI-generated or
AI-altered media to the platform: Instagram `is_ai_generated`, TikTok `is_aigc`,
YouTube `status.containsSyntheticMedia` and X `made_with_ai`. See
[AI-Generated Content Disclosure](#ai-generated-content-disclosure).
LinkedIn repost settings default to `false`, an empty parent URN, and an empty visibility. When enabled, use a canonical `urn:li:share:...` or `urn:li:ugcPost:...` parent. `CONNECTIONS` visibility is supported only for personal connections; scheduling a company-page repost with it returns `400` with `"LinkedIn company-page reposts cannot use CONNECTIONS visibility; choose PUBLIC"`. See [LinkedIn Repost Settings](#linkedin-repost-settings) for the full contract (commentary, media rules, error strings).
Still accepted, unchanged:
- **REST aliases** — `instagram.cover_url`, `youtube.thumbnail.id` (for `mediaId`),
`youtube.thumbnail.path` (for `url`).
- **String booleans** — `"false"` / `"0"` / `"off"` coerce to `false` on `telegram` and
existing `tiktok` boolean keys, and on `aiGenerated` for all four disclosing
platforms (`"true"` / `"1"` / `"yes"` / `"on"` coerce to `true`). `tiktok.autoAddMusic`
accepts JSON booleans only.
- **Comma-separated `youtube.tags`** — a string is split into an array.
- **Legacy flat fields** — `youtube.playlistId` and `youtube.thumbnailUrl` are not
`PLATFORM_SETTING_UNKNOWN`; they keep returning their existing migration-hint `400`
(e.g. *"playlistId is not supported; use …playlist"*). They are never persisted.
## Idempotency
Send an optional `Idempotency-Key` request header to make `create-post` safe to retry.
This solves the classic agent failure: **the request times out or the connection drops,
the client retries, and the user ends up with two identical posts**. With a key, the
retry replays the original response — one post, not two.
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-H "Idempotency-Key: 8f1c0b6e-6a2f-4a1e-9f3b-2b1d0c9a7e55" \
-d '{
"content": "Excited to share our new product launch! 🚀 #launch",
"platforms": ["twitter-123456789"],
"scheduledTime": "2026-03-01T14:00:00.000Z"
}'
```
| Situation | Result |
|-----------|--------|
| Key not seen before | Request runs normally; the response is recorded against the key |
| Same key + **same** body | The original response is **replayed** verbatim (same status, same `postGroupId`). No second post. |
| Same key + **different** body | `422` / `IDEMPOTENCY_KEY_CONFLICT` |
| Same key, first request **still running** | `409` / `IDEMPOTENCY_IN_FLIGHT` — retry shortly |
> **Opt-in.** Without the header, behaviour is exactly as before — no dedup, no new
> failure modes.
**Client guidance:**
- Generate a **fresh key per logical create** (e.g. `crypto.randomUUID()`), and reuse
that same key for *every retry of that one create* — that is the entire point.
- Never reuse a key across different posts; the second one gets `422`.
- On `409`, wait and retry the identical request rather than dropping the key — a stuck
in-flight claim frees up after ~3 minutes and the retry then completes or replays.
- Keys are scoped to the API key's user, so keys cannot collide across accounts.
- **Records expire after 24 hours.** After that a reused key is treated as new and
creates a second post — keep retries well inside that window.
- Body comparison is order-insensitive (JSON keys are canonicalized), so re-serializing
the same payload does not trip a conflict. Extremely deeply nested bodies (>200 levels)
are rejected with `400` / `IDEMPOTENCY_BODY_TOO_COMPLEX`.
## Posts with Media
> **Publishable media-required platforms (Instagram, TikTok, YouTube):** these platforms require media on every post. `create-post` **validates this at the scheduling gate**: if `scheduledTime` is set (so the post is created as `scheduled`) and one of these platforms has no media, the call is **rejected up front with HTTP 400 `MEDIA_REQUIRED`** — the validator runs with an empty media list. It is *not* accepted-then-failed-at-publish. Two ways to satisfy it: (1) pass `mediaUrls` (public https URLs) in the **same** `create-post` call to attach and schedule in one shot, or (2) create a **draft** (omit `scheduledTime`), attach media, then schedule via [Update Post](update-post.md). Creating a draft with no media is always allowed (drafts skip validation). Pinterest is connect-only: its registry limits and media validation do not imply publishing support. See [Validation](../guides/validation.md) for the per-platform media matrix.
> **Two supported media flows:**
>
> **A. One-shot with `mediaUrls`** (public https URLs — best for agents):
```
POST /create-post → content + platforms + scheduledTime + mediaUrls[] (attached + scheduled in one call)
```
> **B. Draft → upload → schedule** (for local files):
```
1. POST /create-post → Omit scheduledTime (creates draft)
2. POST /get-upload-url → Get pre-signed URL for media
3. PUT {uploadUrl} → Upload file to S3
4. POST /complete-media/:mediaId → (optional) finalize/validate the upload early
5. PUT /update-post/:postGroupId → Set status="scheduled" + scheduledTime
```
> **Do not** attach media via `get-upload-url` to an *already-scheduled* post: attaching media demotes the post back to `draft` (`postGroupDemoted: true`) and you must re-schedule. See [Upload Media](upload-media.md).
This ensures media is fully uploaded before the scheduler processes your post. See [Upload Media](upload-media.md) for details.
## Default Platform Settings
When creating via the API, these defaults are applied automatically. If you provide a `platformSettings` object in the request body, your values are **merged** with these defaults on a per-platform basis — user-provided fields override the corresponding default fields, while any default fields you omit are preserved. See [Default Platform Settings](#default-platform-settings) for the full list.
```json
{
"tiktok": {
"viewerSetting": "PUBLIC_TO_EVERYONE",
"allowComments": true,
"allowDuet": false,
"allowStitch": false,
"commercialContent": false,
"brandOrganic": false,
"brandedContent": false,
"aiGenerated": false
},
"instagram": {
"videoType": "REELS",
"aiGenerated": false
},
"youtube": {
"privacy": "public",
"title": "",
"madeForKids": false,
"aiGenerated": false,
"playlist": {
"id": "",
"platformId": ""
}
},
"threads": {
"replyControl": ""
},
"twitter": {
"replyTo": "",
"quoteTweet": "",
"aiGenerated": false
},
"telegram": {
"disableNotification": false,
"disableWebPagePreview": false,
"protectContent": false
}
}
```
> **Note:** Only `tiktok`, `instagram`, `youtube`, `threads`, `twitter`, `telegram`, and `linkedin` keys are recognized in `platformSettings`. Other platform keys (e.g., `facebook`, `bluesky`, `mastodon`) are **rejected with `400` / `PLATFORM_SETTING_UNKNOWN`** — they are no longer silently dropped. X accepts `replyTo`, `quoteTweet` and `aiGenerated`; LinkedIn accepts `repostEnabled`, `repostParentUrn`, and `repostVisibility`. For `telegram`, only the three boolean keys shown above (`disableNotification`, `disableWebPagePreview`, `protectContent`) are accepted; any other key inside the telegram object is likewise a `400`, and string values like `"false"` / `"0"` / `"off"` are still coerced to `false`. See [Unknown platformSettings paths](#unknown-platformsettings-paths).
> **YouTube** also accepts `tags`, `categoryId`, `madeForKids`, `aiGenerated`, and a `playlist` object (`{ id, platformId }`) in addition to `privacy`/`title`. A `playlist` can be set directly on `create-post`. Nested objects are validated to their leaves: `playlist` accepts only `id`/`platformId` and `thumbnail` only `mediaId`/`id`/`url`/`path` — any other nested key (e.g. `youtube.thumbnail.mediaID`) returns `400` / `PLATFORM_SETTING_UNKNOWN` rather than silently clearing the value. A custom `thumbnail` **cannot** be set on `create-post` — the thumbnail upload requires a `postGroupId`, so create the post first and set the thumbnail via `update-post`. See [YouTube → Platform-Specific Settings](../platforms/youtube.md#platform-specific-settings) for the full field reference.
> **Instagram** also accepts `coverUrl` (alias: `cover_url`) — a custom cover image for Reels. Provide a **publicly accessible http(s) URL to a JPEG image** (Instagram fetches it server-side at publish time), or [upload a cover file](upload-instagram-cover.md) (JPEG/PNG/WebP up to 8 MB) and use the URL it returns. Non-JPEG or non-http(s) URLs are rejected with `400`. An empty string clears the custom cover. Ignored for Stories and image posts. See [Instagram → Platform-Specific Settings](../platforms/instagram.md#platform-specific-settings).
> **AI-generated content** — `instagram`, `tiktok`, `youtube` and `twitter` accept `aiGenerated` (boolean, default `false`) to self-disclose realistic AI-generated or AI-altered media. See [AI-Generated Content Disclosure](#ai-generated-content-disclosure).
## X Reply and Quote Settings
Use `platformSettings.twitter` to publish as a reply, quote another post, or do both:
```json
{
"content": "Thanks for the mention — here is the detail you asked for.",
"platforms": ["twitter-123456789"],
"scheduledTime": "2026-08-25T14:00:00.000Z",
"platformSettings": {
"twitter": {
"replyTo": "https://x.com/customer/status/1234567890123456789",
"quoteTweet": "987654321098765432"
}
}
}
```
| Field | Type | Description |
|-------|------|-------------|
| `replyTo` | string | Full `x.com`/`twitter.com` status URL or bare numeric post ID. A single post replies to this target; an auto-thread chains its first post under the target and the remaining parts under one another. Empty string clears the setting. |
| `quoteTweet` | string | Full status URL or bare numeric post ID. The quote is applied to the single post or the first post of a thread. It can be combined with `replyTo` and with media. Empty string clears the setting. |
URLs are normalized to their numeric ID. IDs must contain 1–19 digits; malformed references are rejected at intake.
> **Important X restriction:** on self-serve X API tiers, a programmatic reply or quote is accepted only when the target post's author **mentioned the connected account in that same post**, **quoted one of the account's posts**, or the connected account **authored the target itself**. Enterprise apps are exempt. Use these fields for inbound engagement and resurfacing your own posts, not for replying to arbitrary third-party posts.
Publora cannot reliably prevalidate that relationship. The create/update request can therefore succeed, but X can reject the post later during publication. Publora records that permanent failure as `X_REPLY_NOT_AUTHORIZED`; retrying the same target does not help. Deleted, protected, or otherwise inaccessible targets can instead fail as `X_TARGET_REJECTED`.
## AI-Generated Content Disclosure
Instagram, TikTok, YouTube and X each offer a self-disclosure flag for realistic AI-generated or AI-altered media. Set the optional boolean `aiGenerated` under the matching `platformSettings` key. It defaults to `false`, is accepted on `create-post` and `update-post`, and is forwarded to the platform when the post publishes:
```json
{
"content": "Concept video rendered with a generative model.",
"platforms": ["instagram-123456789", "tiktok-123456789", "youtube-UCxxxxxxxx", "twitter-123456789"],
"scheduledTime": "2026-11-10T14:00:00.000Z",
"mediaUrls": ["https://cdn.example.com/renders/concept.mp4"],
"platformSettings": {
"instagram": { "aiGenerated": true },
"tiktok": { "viewerSetting": "PUBLIC_TO_EVERYONE", "aiGenerated": true },
"youtube": { "aiGenerated": true },
"twitter": { "aiGenerated": true }
}
}
```
| Platform | Provider flag | When and where it is sent |
|----------|---------------|---------------------------|
| Instagram | `is_ai_generated` — the "AI info" label | On the container that is published: a single image or video, a Reel, a Story, or the parent of a carousel (never carousel children). Instagram does not allow adding or removing the label after publishing. |
| TikTok | `is_aigc` — "Creator labeled as AI-generated" | In `post_info` of a video Direct Post (always present, `false` by default) and at the top level of the photo `content/init` request (only when `true`). |
| YouTube | `status.containsSyntheticMedia` — "Altered or synthetic content" | On the video upload, only when `true`. |
| X | `made_with_ai` — "Made with AI" | Only when the post attaches media, on the single post or the head tweet of a thread. A text-only post is published without it. |
Each platform publishes its own rules on when disclosure is required: Meta for realistic AI-generated or AI-altered video, audio or images; TikTok for realistic AI-generated video or images (a missing label risks removal or loss of For You eligibility); YouTube for realistic AI-generated or AI-altered video or audio, but not for scripts, titles, thumbnails, beauty filters or clearly unrealistic content; X treats it as voluntary in general. Publora forwards the flag as you set it and does not detect AI content.
- Like the other REST booleans, `aiGenerated` accepts the string encodings `"true"` / `"false"` / `"1"` / `"0"` / `"yes"` / `"no"` / `"on"` / `"off"`. MCP `create_post`/`update_post` and the Company API accept JSON booleans only.
- With the default `false` the provider request is unchanged, so existing integrations need no change.
- On `update-post`, an omitted `aiGenerated` keeps its stored value. Because Instagram fixes the label when the container is created, changing `instagram.aiGenerated` once publishing has started returns `409 POST_PUBLISH_IN_PROGRESS`, the same gate as a content edit — see [Update Post → Editing content and targets](./update-post.md#editing-content-and-targets).
- Sending `aiGenerated` under any other platform (for example `telegram`) is an unknown path and returns `400 PLATFORM_SETTING_UNKNOWN`.
- Agency drafts accept the same four paths inside `draft.platformSettings`; `twitter.aiGenerated` is the only X setting the Company API accepts. See [Agency platform settings](../guides/agency-platform-settings.md#ai-generated-content-disclosure).
## LinkedIn Repost Settings
Set `platformSettings.linkedin.repostParentUrn` to schedule a **repost** (reshare) of an existing LinkedIn post instead of a regular post. The group's `content` becomes the reshare commentary shown above the reposted post (the normal LinkedIn 3,000-character content limit applies); empty content is allowed for a plain repost.
```json
{
"content": "My commentary on this great post.",
"platforms": ["linkedin-Tz9W5i6ZYG"],
"scheduledTime": "2026-08-01T14:00:00.000Z",
"platformSettings": {
"linkedin": {
"repostParentUrn": "urn:li:share:7123456789012345678",
"repostVisibility": "PUBLIC"
}
}
}
```
| Field | Type | Description |
|-------|------|-------------|
| `repostParentUrn` | string | URN of the post to reshare — `urn:li:share:` or `urn:li:ugcPost:` (**not** `urn:li:activity:`). Empty string = normal post (repost off) |
| `repostVisibility` | string | `PUBLIC` (default) or `CONNECTIONS`. Lowercase input is normalized to uppercase. `CONNECTIONS` is only valid for personal accounts — company (organization) pages are rejected at intake (see [the accepted tree](#unknown-platformsettings-paths)) and are always forced to `PUBLIC` at publish time |
| `repostEnabled` | boolean | Optional explicit toggle. `true` requires a non-empty `repostParentUrn`; `false` requires an empty one. When omitted, a non-empty `repostParentUrn` enables the repost |
**Rules:**
- **Media is forbidden on repost groups.** Scheduling a repost group with attached media fails validation with code `MEDIA_TYPE_NOT_SUPPORTED`: *"LinkedIn reposts cannot include media — remove the attached files or turn off the repost setting"*.
- **Publish-time failures:** if the parent post was deleted, made private, or is not reshareable, the scheduled post fails permanently with *"LinkedIn rejected the repost — the original post may have been deleted, made private, or is not reshareable."*
Field-level validation errors (400):
| Error | Cause |
|-------|-------|
| `"platformSettings.linkedin.repostParentUrn must be a LinkedIn post URN like urn:li:share: or urn:li:ugcPost:"` | Invalid URN shape (activity URNs are rejected) |
| `"platformSettings.linkedin.repostVisibility must be one of: PUBLIC, CONNECTIONS"` | Invalid visibility value |
| `"platformSettings.linkedin.repostParentUrn is required when repostEnabled is true"` | `repostEnabled: true` without a parent URN |
| `"platformSettings.linkedin.repostParentUrn must be empty when repostEnabled is false"` | `repostEnabled: false` with a parent URN set |
> **Tip:** To repost **immediately** without scheduling, use the dedicated [LinkedIn Reshare endpoint](linkedin-reshare.md) (`POST /linkedin-reshare`) instead.
## First comment
Post up to three ordered text comments under your own post. Pass `firstComments`:
```json
{
"content": "Three lessons from our launch week.",
"platforms": ["linkedin-Tz9W5i6ZYG", "twitter-123456789"],
"scheduledTime": "2027-03-01T14:00:00.000Z",
"firstComments": [
{ "text": "Full write-up with the numbers: https://example.com/launch-week", "platforms": ["linkedin"] },
{ "text": "Which lesson resonates?", "platforms": ["linkedin"], "delaySeconds": 60 }
]
}
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | The comment. Stored verbatim, measured and posted trimmed; whitespace-only text clears the comment. Hard cap 25,000 characters regardless of targets. |
| `platforms` | string[] | No | Platform **types** that get the comment: `linkedin`, `twitter`, `threads`, `bluesky`, `mastodon`. Omit it (or send `[]`) for every supported target. Connection IDs such as `linkedin-abc` are rejected with `400 FIRST_COMMENT_PLATFORM_UNKNOWN`; a type the post is not published to only produces a `FIRST_COMMENT_PLATFORM_NOT_TARGETED` warning. |
| `delaySeconds` | integer | No | Delay after publication for item 0, or after the previous comment posts for later items. 0–86,400 seconds; omitted means 0. Actual delivery is within one scheduler tick of the due time. |
How it behaves:
- **Wave 1 platforms:** LinkedIn (member profiles comment as the person, company Pages as the organization), X, Threads (the connection must grant `threads_manage_replies`), Bluesky, Mastodon. Targets on other platforms are skipped and reported in a `FIRST_COMMENT_UNSUPPORTED_PLATFORMS` warning in the response's `warnings[]`.
- **Length** is validated per applicable platform with that platform's own counting: X 280 weighted characters (25,000 only when *every* targeted X connection is Premium), LinkedIn 1,250, Threads 500 code points, Bluesky 300 graphemes **and** 3,000 UTF-8 bytes, Mastodon 500 with each link counted as 23. Over the limit → `400 FIRST_COMMENT_TOO_LONG` with `platform`, `limit`, `count` and `unit`.
- **Order and failures.** A comment becomes due on a scheduler tick; the next comment waits until the previous one is confirmed `posted`. If one fails, later comments stop. Each comment is attempted at most once per target. A failed comment never changes the published post. Read each outcome in [`get-post` → `posts[].firstCommentResults[]`](./get-post.md#first-comment-result-postsfirstcommentresult).
- **Compatibility.** The old `firstComment: { text, platforms? }` still creates one comment. Send either `firstComment` or `firstComments`; sending both returns `400 FIRST_COMMENT_INVALID` on `firstComments`.
- **Editable** with [`update-post`](./update-post.md) while the post is a draft or scheduled; changing only the time leaves comments untouched. `firstComments: null` or `[]` clears them.
## Examples
### Schedule a text post to X and LinkedIn
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Excited to share our new product launch! 🚀 #launch',
platforms: ['twitter-123456789', 'linkedin-ABC123'],
scheduledTime: '2026-03-01T14:00:00.000Z'
})
});
const data = await response.json();
console.log(data.postGroupId);
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Excited to share our new product launch! 🚀 #launch',
'platforms': ['twitter-123456789', 'linkedin-ABC123'],
'scheduledTime': '2026-03-01T14:00:00.000Z'
}
)
print(response.json()['postGroupId'])
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Excited to share our new product launch! 🚀 #launch",
"platforms": ["twitter-123456789", "linkedin-ABC123"],
"scheduledTime": "2026-03-01T14:00:00.000Z"
}'
```
#### Node.js (axios)
```javascript
const axios = require('axios');
const { data } = await axios.post(
'https://api.publora.com/api/v1/create-post',
{
content: 'Excited to share our new product launch! 🚀 #launch',
platforms: ['twitter-123456789', 'linkedin-ABC123'],
scheduledTime: '2026-03-01T14:00:00.000Z'
},
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
console.log(data.postGroupId);
```
### Post to all 10 platforms at once
> **Note:** This example shows the platform-ID format and fan-out only. As written it is **text-only** with `scheduledTime` set, so it is **rejected with HTTP 400 `MEDIA_REQUIRED`** — the **Instagram, TikTok, and YouTube** targets require media. To include them, either pass `mediaUrls` in this same call, or create as a draft (omit `scheduledTime`), [upload media](upload-media.md), then schedule. Pinterest is connect-only and is intentionally absent: satisfying its registry media validation does not make it publishable.
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Big announcement dropping tomorrow. Stay tuned.',
platforms: [
'twitter-111', 'linkedin-222', 'instagram-333',
'threads-444', 'tiktok-555', 'youtube-666',
'facebook-777', 'bluesky-888', 'mastodon-999',
'telegram-000'
],
scheduledTime: '2026-03-01T09:00:00.000Z'
})
});
```
### Create a draft (no scheduled time)
```python
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Draft post -- will schedule later',
'platforms': ['twitter-123456789']
}
)
```
## Errors
Platform IDs use `-`. The prefix must contain only lowercase ASCII letters. The ID must be non-empty and cannot contain whitespace, `/`, `?`, or `#`; other characters, including colons, are allowed. For example, `bluesky-did:plc:abc123` is a valid target.
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"Content is required"` | Missing `content` field or content is empty/whitespace-only |
| 400 | `"Platforms are required"` | `platforms` field is missing or null |
| 400 | `"At least one platform is required"` | `platforms` is an empty array |
| 400 | `"Platforms must be an array"` | `platforms` is not an array |
| 400 | `"Invalid platforms JSON format"` | `platforms` contains malformed JSON |
| 400 | `"Invalid platform ID format: "` | Prefix is not lowercase letters, or the ID is empty or contains whitespace, `/`, `?`, or `#` |
| 400 | `"Platforms must not contain duplicates"` | The same connection ID appears more than once in `platforms` |
| 400 | `"Invalid scheduled time format"` | `scheduledTime` is not a valid ISO 8601 datetime |
| 400 | `"publishNow must be a boolean"` | `code: "INVALID_PUBLISH_NOW"`. `publishNow` is present but not `true` or `false` |
| 400 | `"publishNow cannot be combined with a draft status"` / `"publishNow cannot be combined with an invalid or future scheduledTime"` | `code: "PUBLISH_NOW_CONFLICT"`. See [Publish now](#publish-now) |
| 400 | `"Scheduled time is in the past. Server time is UTC."` | `code: "SCHEDULED_TIME_IN_PAST"`, `serverTime: ""`. `scheduledTime` is 5+ minutes in the past while strict mode is active; the default transition is scheduled for **2026-08-25** but configuration can override it. |
| 400 | `"Unknown platformSettings path: "` | `code: "PLATFORM_SETTING_UNKNOWN"`, `field: ""`. Unknown platform or nested key; nothing is persisted. See [Unknown platformSettings paths](#unknown-platformsettings-paths) |
| 400 | `"platformSettings.linkedin.*"` validation errors | Invalid LinkedIn repost settings (bad URN shape, bad visibility, `repostEnabled`/`repostParentUrn` mismatch) — see [LinkedIn Repost Settings](#linkedin-repost-settings) |
| 400 | `"LinkedIn company-page reposts cannot use CONNECTIONS visibility; choose PUBLIC"` | `repostVisibility: "CONNECTIONS"` while the scheduled group targets a LinkedIn company-page connection |
| 400 | `"Invalid platformSettings JSON"` | `platformSettings` was provided as a string that could not be parsed as valid JSON |
| 400 | `"firstComment must be an object { text, platforms? }"` | `code: "FIRST_COMMENT_INVALID"`, `field`. `firstComment` was a string, an array, or carried an unknown field — see [First comment](#first-comment) |
| 400 | `FIRST_COMMENT_INVALID` | `firstComments` has more than three entries, an invalid `delaySeconds`, an invalid item shape, or was sent together with `firstComment`; `field` points to the problem |
| 400 | `"Unknown first comment platform \"\": use platform types such as linkedin or twitter, not connection keys"` | `code: "FIRST_COMMENT_PLATFORM_UNKNOWN"`, `field: "firstComment.platforms"`, `allowed: [...]`. A connection ID or unknown type in `firstComment.platforms` |
| 400 | `"First comment is too long for : , limit "` | `code: "FIRST_COMMENT_TOO_LONG"`, `field: "firstComment.text"`, plus `platform`, `limit`, `count`, `unit`. The absolute cap reads `"firstComment.text is too long: characters, limit 25000"` |
| 400 | `"Idempotency-Key request body is too deeply nested"` | `code: "IDEMPOTENCY_BODY_TOO_COMPLEX"`. Body nested more than 200 levels deep while using `Idempotency-Key` |
| 400 | `"mediaUrls must be an array of public https URLs"` | `mediaUrls` is present but not an array |
| 400 | `"mediaUrls supports at most 10 URLs per request"` | More than 10 URLs supplied (also: `"mediaUrls must contain at least one URL when provided"`, `"Every mediaUrls entry must be a non-empty string"`) |
| 400 | `"Media ingestion failed"` | One or more `mediaUrls` could not be downloaded/probed; per-URL detail in the `mediaResults` array |
| 429 | `"Media URL ingestion rate limit reached (60 URLs/hour)…"` | `code: "MEDIA_URL_RATE_LIMITED"`, `retryAfterSec` + `Retry-After` header |
| 400 | `"platformSettings must be an object"` | `platformSettings` is provided but is not a plain object (e.g., array, null, or primitive after JSON parsing) |
| 401 | `"API key is required"` | Missing `x-publora-key` header |
| 401 | `"Invalid API key"` | `x-publora-key` value is incorrect or revoked |
| 401 | `"Invalid API key owner"` | API key exists but its user could not be resolved |
| 403 | `"API access is not enabled for this account"` | The account has `apiAccess` disabled (a custom plan; standard plans including the free Starter plan include API access) |
| 403 | `"MCP access is not enabled for this account"` | Returned when `x-publora-client: mcp` is set but MCP access is not enabled |
| 403 | LimitExceededError (structured) | Plan limit reached (see below) |
| 409 | `"A request with this idempotency key is still in flight"` | `code: "IDEMPOTENCY_IN_FLIGHT"`. An earlier request with the same `Idempotency-Key` has not finished. Retry the identical request shortly. See [Idempotency](#idempotency) |
| 422 | `"Idempotency key was already used with a different request body"` | `code: "IDEMPOTENCY_KEY_CONFLICT"`. The same `Idempotency-Key` was reused with a different body. Generate a fresh key per logical create |
| 500 | `"Failed to create post group"` | Unexpected server error |
| 503 | `"Unable to check Threads permissions. Please try scheduling again shortly."` | `code: "THREADS_PERMISSIONS_UNAVAILABLE"`. Scheduling a Threads chain (a Threads target with more than one part) needed a permission check that Publora could not complete. The body is only `{ code, error }`. Retry in a few seconds; it never means reconnect. See [Threads chain codes](../guides/error-codes.md#at-scheduling). |
> **Publishable media-required platforms (Instagram, TikTok, YouTube):** when `scheduledTime` is set, `create-post` validates media presence and **rejects a media-less post with HTTP 400 `MEDIA_REQUIRED`** (the validator runs with an empty media list). Attach media first — pass `mediaUrls`, or use the draft flow. Pinterest is connect-only and cannot be published even if media validation passes. See [Posts with Media](#posts-with-media) and [Validation](../guides/validation.md). The 400 body shape:
>
> ```json
> {
> "error": "Validation failed",
> "validation": {
> "valid": false,
> "errors": [
> {
> "code": "MEDIA_REQUIRED",
> "message": "Instagram posts require media",
> "platform": "instagram",
> "field": "media",
> "suggestions": [
> "Upload an image or video for this platform",
> "This platform requires media. One-shot fix: POST /api/v1/create-post with mediaUrls (array of public https URLs) plus scheduledTime. Manual flow: create a draft (no scheduledTime), POST /api/v1/get-upload-url once per file, PUT the bytes with the same Content-Type, POST /api/v1/complete-media/:mediaId, then PUT /api/v1/update-post/:postGroupId with status='scheduled'."
> ],
> "severity": "error"
> }
> ],
> "warnings": [],
> "summary": { "errorCount": 1, "warningCount": 0, "affectedPlatforms": ["instagram"] }
> }
> }
> ```
> (The second `suggestions` entry is the channel-aware recovery hint — MCP callers get the `create_post`/`get_upload_url` tool-name variant.)
### LimitExceededError (403)
When a plan limit is exceeded, the API returns a structured error response. The `error` field contains a short label, while the `message` field contains the full human-readable explanation.
> **Note:** The first time a post limit is exceeded in a given billing month, an email notification is sent to the account owner. This notification is sent only once per month.
```json
{
"error": "Post limit reached",
"code": "POST_LIMIT_REACHED",
"metric": "posts.platform_monthly",
"message": "Monthly post limit reached. Your Pro plan allows 100 platform posts per month.",
"limit": 100,
"used": 100,
"requested": 2,
"remaining": 0,
"periodStart": "2026-03-01T00:00:00.000Z",
"periodEnd": "2026-04-01T00:00:00.000Z",
"planName": "Pro"
}
```
> **Note:** Not all fields are present on every error code. For example, `SCHEDULE_HORIZON_REACHED` returns `null` for `used`, `requested`, `remaining`, `periodStart`, and `periodEnd`.
Some limit errors include additional context fields:
| Field | Present on | Description |
|-------|-----------|-------------|
| `scheduledTime` | `SCHEDULE_HORIZON_REACHED` | The requested scheduled time that exceeded the horizon |
| `maxScheduledDate` | `SCHEDULE_HORIZON_REACHED` | The furthest date allowed by the current plan |
| `limitScope` | `POST_LIMIT_REACHED` | `"account"` or `"connection"`, matching the plan's monthly-post scope |
| `blockedPlatforms` | `POST_LIMIT_REACHED` | Per-connection `{ platformSelection, used, remaining }` entries; present only for a connection-scoped monthly-post rejection |
| `overLimitBy` | `CONNECTIONS_OVER_LIMIT` | Number of connections over the plan limit |
| `disallowedPlatforms` | `PLATFORM_NOT_AVAILABLE` | Array of platform names not available on the current plan |
| `allowedPlatforms` | `PLATFORM_NOT_AVAILABLE` | Array of platform names available on the current plan |
Possible `code` values:
| Code | Error value | Description |
|------|-------------|-------------|
| `POST_LIMIT_REACHED` | `"Post limit reached"` | Monthly post limit exceeded |
| `SCHEDULED_POST_LIMIT_REACHED` | `"Scheduled post limit reached"` | Scheduled post limit exceeded |
| `SCHEDULE_HORIZON_REACHED` | `"Schedule horizon reached"` | Scheduling too far in the future for current plan |
| `CONNECTIONS_OVER_LIMIT` | `"Account over channel limit"` | Too many platform connections for current plan |
| `PLATFORM_NOT_AVAILABLE` | `"Platform not available"` | Platform not available on current plan (e.g., a custom plan with restricted `allowedPlatforms`). Metric: `posts.platform_monthly`. |
## Post Statuses
After creation, the post group goes through these states:
```
draft → scheduled → published
→ failed
→ partially_published
```
**Post group statuses** (returned in `status` field):
- **draft**: Saved but not scheduled
- **scheduled**: Will be published at `scheduledTime`
- **published**: Successfully posted on all platforms
- **failed**: Failed on all platforms
- **partially_published**: Succeeded on some, failed on others
> **Note:** Individual platform records (ScheduledPost) have their own statuses including `pending` and `processing`, which reflect per-platform delivery state. The post group `status` field above is a rollup and does not include `processing`. A separate `processingStatus` field on the post group tracks whether the post is currently being processed. Possible `processingStatus` values are: `pending`, `processing`, `finished`.
> **Note:** `processingStatus` is internal and is not returned by get-post or list-posts.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/get-post
# Get Post
Retrieve details and publishing status of a post group.
## Endpoint
```
GET https://api.publora.com/api/v1/get-post/:postGroupId
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `"mcp"`) |
## Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `postGroupId` | string | The post group ID returned from create-post |
## Response
```json
{
"success": true,
"postGroupId": "507f1f77bcf86cd799439011",
"status": "published",
"scheduledTime": "2026-02-22T14:30:00.000Z",
"platforms": ["twitter-123456789", "linkedin-ABC123"],
"platformSettings": {
"youtube": { "privacy": "public" }
},
"firstComment": {
"text": "Full write-up with the numbers: https://example.com/launch",
"platforms": ["linkedin"]
},
"firstComments": [
{ "text": "Full write-up with the numbers: https://example.com/launch", "platforms": ["linkedin"] }
],
"posts": [
{
"_id": "663a1b2c3d4e5f6a7b8c9d01",
"platform": "twitter",
"platformId": "123456789",
"content": "Excited to share our new product launch! 🚀",
"status": "published",
"postedId": "1234567890123456789",
"permalink": null,
"isThread": false,
"threadParts": [],
"firstCommentResult": null,
"firstCommentResults": []
},
{
"_id": "663a1b2c3d4e5f6a7b8c9d02",
"platform": "linkedin",
"platformId": "ABC123",
"content": "Excited to share our new product launch! 🚀",
"status": "published",
"postedId": "urn:li:share:7654321",
"permalink": null,
"isThread": false,
"threadParts": [],
"firstCommentResult": {
"status": "posted",
"commentId": "urn:li:comment:(urn:li:activity:7654321,1234)",
"skipReason": null,
"error": null,
"attemptedAt": "2026-02-22T14:30:04.120Z",
"postedAt": "2026-02-22T14:30:05.310Z"
},
"firstCommentResults": [
{
"status": "posted",
"commentId": "urn:li:comment:(urn:li:activity:7654321,1234)",
"skipReason": null,
"error": null,
"attemptedAt": "2026-02-22T14:30:04.120Z",
"postedAt": "2026-02-22T14:30:05.310Z"
}
]
}
],
"media": []
}
```
### Group-level fields
| Field | Type | Description |
|-------|------|-------------|
| `postGroupId` | string | The post group ID |
| `status` | string | Group status (see [Post Status Values](#post-status-values)) |
| `scheduledTime` | string/null | **The effective scheduled time as actually stored by the server** — `null` if the group has none |
| `platforms` | array | The effective platform list stored on the group (compound `platform-platformId` form) |
| `platformSettings` | object | The stored per-platform settings (`{}` if none were stored) |
| `firstComment` | object/null | Legacy alias for `firstComments[0]`, or `null` when none is set |
| `firstComments` | array | Stored ordered [first comments](./create-post.md#first-comment) `{ text, platforms?, delaySeconds? }`; old one-comment documents read as a one-element array without a migration |
| `posts` | array | One entry per platform target (see below) |
| `media` | array | Attached media inventory in group order; always present and empty when none is attached |
> **Read-after-write:** `scheduledTime`, `platforms` and `platformSettings` echo **what the server actually stored**, not what you sent. A permitted past-time clamp may change `scheduledTime`; schedule-horizon violations are rejected, not adjusted. See [past scheduled times](../guides/scheduling.md#past-scheduled-times).
### Media inventory (`media[]`)
One entry per attached file, in the order the files are attached to the post.
| Field | Type | Description |
|-------|------|-------------|
| `mediaId` | string | The media ID, used by `DELETE /media/:mediaId` and `complete-media` |
| `sourceFileName` | string/null | The client-facing file name: the cleaned `fileName` from `get-upload-url` or [`attach-media`](./attach-media.md), or the URL's file name for `mediaUrls` |
| `fileName` | string/null | The storage key, e.g. `images/1790000000000-0-1a2b3c4d-spring-launch-banner.png` |
| `type` | string/null | `image`, `video` or `document` |
| `mimeType` | string/null | The MIME type of the stored file |
| `status` | string | `uploading` (not verified yet), `ready`, `failed` (see `failureReason`) or `deleting`. Files attached before statuses existed report `ready` |
| `failureReason` | string/null | Why validation failed, when `status` is `failed` |
| `url` | string/null | The public URL of the stored file |
### Per-platform fields (`posts[]`)
| Field | Type | Description |
|-------|------|-------------|
| `_id` | string | The individual platform post ID |
| `platform` | string | Platform name (e.g., `twitter`) |
| `platformId` | string/null | Raw platform account ID — `null` when absent |
| `content` | string | The content published to this platform |
| `status` | string | Per-platform status |
| `postedId` | string/null | The platform's own ID for the published post — `null` until published |
| `permalink` | string/null | Public URL of the published post — `null` when unavailable |
| `isThread` | boolean | `true` when this target was published as a multi-part chain. Always present |
| `threadParts` | array | Per-part publication progress — see [Thread parts](#thread-parts). Always present, `[]` when the target is not a chain |
| `firstCommentResult` | object/null | Outcome of the [first comment](./create-post.md#first-comment) on this target — see [First comment result](#first-comment-result-postsfirstcommentresult). `null` when no comment applies to this target or the post is not published yet |
| `firstCommentResults` | array | Per-comment outcomes in order on this target; the singular field is an alias for item 0. An empty array means no result applies yet |
> **Stable shape:** `platformId`, `postedId` and `permalink` are **always present** on every `posts[]` entry. When a value is unavailable it is explicitly `null` — the key never disappears, so you can read it without existence checks.
> **`permalink` is not yet populated.** The field is delivered end-to-end, but is currently `null` for essentially all posts pending a separate backfill. Treat a non-null `permalink` as a bonus, never a guarantee — to locate the live post today, resolve it from `platform` + `platformId` + `postedId`.
> **Note:** With `.lean()`, the `error` field may be **absent** (undefined) for non-failed posts if the error subdocument was never populated — it will not necessarily be `null`. When a post has failed, the `error` field contains an error object with details about the failure.
> **Note:** For draft and scheduled posts, `postedId` is `null` (present, but empty) since the post has not yet been published to the platform. Published posts normally carry a non-null `postedId`; a partially published X thread is the exception where a `failed` target can retain the head tweet ID in `postedId`.
> **Note:** The `platformId` field returns the raw platform ID (e.g., `"123456789"`), not the compound format used by list-posts (e.g., `"twitter-123456789"`). See the [list-posts](./list-posts) endpoint for details on this difference.
### Thread parts
X/Twitter and Meta Threads targets can publish one post as a chain of connected
parts. `get-post` reports that progress per target.
| Field | Type | Description |
|-------|------|-------------|
| `index` | number | Zero-based position of the part in the chain |
| `content` | string | The text of that part, exactly as published |
| `status` | string | `pending`, `published`, or `failed` |
| `publishedId` | string/null | The platform's own ID for that part — `null` until confirmed |
```json
{
"_id": "663a1b2c3d4e5f6a7b8c9d04",
"platform": "threads",
"platformId": "17841412345678",
"content": "The whole story, as submitted.\n\n---\n\nThe second half.",
"status": "published",
"postedId": "17900000000000001",
"permalink": null,
"isThread": true,
"threadParts": [
{ "index": 0, "content": "The whole story, as submitted.", "status": "published", "publishedId": "17900000000000001" },
{ "index": 1, "content": "The second half.", "status": "published", "publishedId": "17900000000000002" }
]
}
```
`postedId` on the target is the **first** part's platform ID, which is also
`threadParts[0].publishedId`. There is no single ID that addresses the whole chain.
> **After a partial failure, read the parts before acting.** A chain that published
> some parts and then failed leaves those parts live on the platform, with
> `status: "published"` and a `publishedId`; the rest stay `pending` or `failed` and
> the target carries the error. A partially published chain is terminal and is not
> retried, and on Threads a re-entry guard additionally refuses any chain that already
> has published parts. Recreating the post would duplicate the parts that already
> exist — inspect `threadParts` and the live account, then publish only what is missing.
> **Note:** `threadParts` is exposed by `get-post` only. `list-posts` does not
> include it, so fetch the group to inspect chain progress.
### First comment result (`posts[].firstCommentResult`)
Read `firstCommentResults[]` in the same order as group `firstComments[]`. The legacy `firstCommentResult` mirrors item 0 and is `null` when no result applies. Comments become due on scheduler ticks in order; item N+1 waits until N is `posted`, and failure stops later items. A `pending` result may have a future `dueAt`.
| Field | Type | Description |
|-------|------|-------------|
| `status` | string | `pending` (waiting for its due time or attempt), `posted`, `failed`, `skipped` |
| `dueAt` | string/null | Earliest scheduler time for this comment (ISO 8601 UTC) |
| `commentId` | string/null | The platform's ID of the comment: LinkedIn `urn:li:comment:…` URN, X tweet ID, Threads media ID, Bluesky `at://` URI, Mastodon status ID |
| `skipReason` | string/null | Why nothing was attempted, such as `unsupported_platform`, `feature_disabled`, or an unavailable connection. Older records may retain `workspace_post` or `unsupported_account_type` |
| `attemptedAt` | string/null | When the attempt was claimed (ISO 8601 UTC) |
| `postedAt` | string/null | When the platform confirmed the comment |
| `error` | object/null | For `failed`: `{ code, message, platformStatusCode, outcomeUnknown }`. **`outcomeUnknown: true` means the request was sent but no definitive answer came back — the comment may exist; check the platform before commenting manually.** |
Error codes specific to the comment: `FIRST_COMMENT_PERMISSION_REQUIRED` (the connection lacks the reply permission — reconnect it), `FIRST_COMMENT_TARGET_UNAVAILABLE` (the platform returned no ID for the published post), `FIRST_COMMENT_NOT_ATTEMPTED` (the publish was recovered late, so no comment was posted), `FIRST_COMMENT_INTERRUPTED` (the publishing worker stopped mid-way), `FIRST_COMMENT_DEADLINE_EXCEEDED` (the platform did not answer within the time budget). The general codes below (`PLATFORM_AUTH_EXPIRED`, `RATE_LIMITED`, `X_REPLY_NOT_AUTHORIZED`, …) can appear here too. A comment is never retried; the post itself is unaffected by a failed comment.
### Failed Post Response
When a post fails, the response includes detailed error information:
```json
{
"success": true,
"postGroupId": "507f1f77bcf86cd799439011",
"posts": [
{
"_id": "663a1b2c3d4e5f6a7b8c9d03",
"platform": "threads",
"platformId": "17841412345678",
"content": "Check out our new feature!",
"status": "failed",
"postedId": null,
"permalink": null,
"error": {
"code": "PLATFORM_AUTH_EXPIRED",
"message": "Error validating access token",
"platformStatusCode": 401,
"platformError": "Invalid OAuth access token",
"failedAt": "2026-02-22T14:30:00.000Z",
"retryable": false
}
}
]
}
```
## Post Status Values
| Status | Meaning |
|--------|---------|
| `draft` | Saved but not yet scheduled |
| `scheduled` | Waiting for scheduled time |
| `pending` | Being processed by scheduler |
| `processing` | Currently publishing to platform |
| `published` | Successfully posted |
| `failed` | Publishing failed (see `error` object for details) |
> **Note:** The statuses above apply to **individual platform posts**. The post **group** itself can also have a status of `partially_published`, which occurs when some platform posts in the group succeeded while others failed. For example, if a post group targets Twitter, LinkedIn, and Threads, and the Threads post fails while the others succeed, the group status will be `partially_published`. Query individual posts within the group to determine which platforms succeeded or failed.
## Error Codes
When `status` is `failed`, the `error` object contains:
| Field | Type | Description |
|-------|------|-------------|
| `code` | string | Error classification code (see table below) |
| `message` | string | Human-readable error message |
| `platformStatusCode` | number/undefined | HTTP status code from the platform API (field may be absent rather than explicitly `null`) |
| `platformError` | string/null | Raw error message from the platform |
| `failedAt` | string | Timestamp when the failure occurred |
| `retryable` | boolean | Whether the error might succeed on retry |
| Error Code | Description | Retryable |
|------------|-------------|-----------|
| `PLATFORM_AUTH_EXPIRED` | Access token expired or revoked | No |
| `RATE_LIMITED` | Platform rate limit exceeded | Yes |
| `INVALID_CONTENT` | Content rejected by platform (e.g., too long, banned words) | No |
| `CONTENT_TOO_LARGE` | Media file exceeds platform limits | No |
| `PLATFORM_SERVER_ERROR` | Platform API returned 5xx error | Yes |
| `NETWORK_ERROR` | Could not reach platform API | Yes |
| `TIMEOUT_ERROR` | Request timed out | Yes |
| `X_REPLY_NOT_AUTHORIZED` | X refused a `platformSettings.twitter` reply or quote: on self-serve API tiers the target's author must have mentioned this account in that post, quoted one of its posts, or the account must have written the target itself | No |
| `X_TARGET_REJECTED` | The `platformSettings.twitter` reply/quote target is unusable — deleted, protected, or its author blocked this account | No |
| `UNKNOWN_ERROR` | Unclassified error | Maybe |
> **Note:** The error codes listed above are not exhaustive. The schema does not validate error codes, so additional codes beyond these eight may appear in the response. Always handle unknown codes gracefully.
## Examples
### JavaScript (fetch)
```javascript
const postGroupId = '507f1f77bcf86cd799439011';
const response = await fetch(
`https://api.publora.com/api/v1/get-post/${postGroupId}`,
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
for (const post of data.posts) {
console.log(`${post.platform}: ${post.status}`);
if (post.postedId) {
console.log(` Platform post ID: ${post.postedId}`);
}
}
```
### Python (requests)
```python
import requests
post_group_id = '507f1f77bcf86cd799439011'
response = requests.get(
f'https://api.publora.com/api/v1/get-post/{post_group_id}',
headers={'x-publora-key': 'YOUR_API_KEY'}
)
data = response.json()
for post in data['posts']:
print(f"{post['platform']}: {post['status']}")
```
### cURL
```bash
curl https://api.publora.com/api/v1/get-post/507f1f77bcf86cd799439011 \
-H "x-publora-key: YOUR_API_KEY"
```
### Node.js (axios)
```javascript
const axios = require('axios');
const { data } = await axios.get(
`https://api.publora.com/api/v1/get-post/${postGroupId}`,
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
// Check if all posts published successfully
const allPublished = data.posts.every(p => p.status === 'published');
console.log(`All published: ${allPublished}`);
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"Invalid post group ID"` | `postGroupId` is not a valid ObjectId |
| 401 | `"API key is required"` | Missing `x-publora-key` header |
| 401 | `"Invalid API key"` | The provided API key is not valid |
| 401 | `"Invalid API key owner"` | The API key exists but its owner account could not be found |
| 403 | `"API access is not enabled for this account"` | The account does not have API access enabled |
| 403 | `"MCP access is not enabled for this account"` | The account does not have MCP access enabled (MCP-only keys) |
| 404 | `"Post group not found"` | No post with this ID belongs to the acting user |
| 500 | `"Failed to fetch post group"` | Internal server error |
| 500 | `"Internal server error"` | Unexpected server error in middleware |
> **Note:** A `postGroupId` that is not a valid MongoDB ObjectId returns `400 { "error": "Invalid post group ID" }` before any lookup. Pass the IDs returned by create-post or list-posts.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/update-post
# Update Post
Edit an existing **draft** or **scheduled** post in place — its base text, its target accounts, its scheduling time, its status, its per-platform settings, or its media — without deleting and recreating it. Updating a post group also updates all associated platform-specific posts.
## Endpoint
```
PUT https://api.publora.com/api/v1/update-post/:postGroupId
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `"mcp"`) |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | Opt-in retry safety. Any client-generated unique string (e.g. a UUID). See [Idempotency](#idempotency). **Strongly recommended when sending `mediaUrls`** — without it, a retried update appends the media a second time. |
## Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `postGroupId` | string | The post group ID to update |
## Request Body
At least one of `publishNow`, `status`, `scheduledTime`, `content`, `platforms`, `platformSettings`, `firstComment`, `firstComments`, or `mediaUrls` must be provided. Missing all nine returns 400.
Every field is a **patch**: omit it and the stored value is left unchanged.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | No | Replacement **base** post text. Applies to every target that has no explicit per-account override (overrides set in the web editor are preserved). An empty string is accepted while the post stays a draft; scheduling still enforces each platform's content/media rules. See [Editing content and targets](#editing-content-and-targets). |
| `platforms` | string[] | No | Replacement target set — **the whole array replaces the stored one**, it is not merged. Use the exact connection IDs from [`GET /platform-connections`](./platform-connections.md); duplicates are rejected. `[]` is accepted only while the post remains a draft. See [Editing content and targets](#editing-content-and-targets). |
| `status` | string | No | `"draft"` or `"scheduled"` |
| `scheduledTime` | string | No | New ISO 8601 UTC datetime |
| `publishNow` | boolean | No | `true` publishes the draft or scheduled post immediately, at server time. It can be combined with other edits in the same request. Cannot be combined with a future `scheduledTime` or `status: "draft"` (`400 PUBLISH_NOW_CONFLICT`). See [Publish an existing post now](#publish-an-existing-post-now). |
| `platformSettings` | object | No | Per-platform settings using the canonical [create-post allowlist](./create-post.md#unknown-platformsettings-paths), including X reply/quote, LinkedIn repost and AI-generated content disclosure settings. Merged with existing settings server-side — fields you omit are preserved. Any unknown top-level platform **or** unknown nested key is **rejected with `400 PLATFORM_SETTING_UNKNOWN`** and nothing is persisted — see [Unknown platformSettings paths](#unknown-platformsettings-paths). |
| `firstComment` | object/null | No | Legacy single-comment replacement `{ "text": "…", "platforms": ["linkedin"] }`, or `null` to remove it. Do not send together with `firstComments`. |
| `firstComments` | object[]/null | No | Replace the **whole ordered list** of up to three `{ text, platforms?, delaySeconds? }` comments; `null` or `[]` clears it. Delays are integer seconds 0–86,400. Validated against effective targets with the same rules as [create-post](./create-post.md#first-comment); the stored list is re-validated when targets change or the post is scheduled. A time change leaves it untouched. |
| `mediaUrls` | string[] | No | Public **`https://`** URLs (1–10 per request) that the server downloads and attaches to the post. **Semantics are APPEND** — the media is added to the post's existing media, never replacing it. Ingestion is all-or-nothing: if any URL fails, none are attached. Plain `http://`, embedded credentials, non-443 ports, and internal/loopback hosts are rejected. Because a retry re-appends, **send an [`Idempotency-Key`](#idempotency) whenever this field is present.** |
> **YouTube playlist & thumbnail (partial update):** `platformSettings` supports partial per-platform updates, so you can change `youtube.playlist` or set/clear `youtube.thumbnail` without resending the other YouTube fields. The **thumbnail can only be set here** (not on `create-post`, which has no `postGroupId` yet). Clear either by sending empty strings — `youtube.playlist` as `{ "id": "", "platformId": "" }`, or `youtube.thumbnail` as `{ "url": "" }`. Playlist or thumbnail changes return **`409`** while the post is publishing/processing (e.g. *"Post group is currently being published; cannot change YouTube playlist. Retry once publishing completes."*). See [YouTube → Platform-Specific Settings](../platforms/youtube.md#platform-specific-settings).
> **Instagram Reels cover:** set or change `instagram.coverUrl` (alias: `cover_url`) here — a JPEG image used as the Reel's cover. Either pass a publicly accessible http(s) URL, or [upload a cover file](upload-instagram-cover.md) (JPEG/PNG/WebP up to 8 MB) and set the returned URL. Send `{ "instagram": { "coverUrl": "" } }` to clear it (the cover falls back to automatic/frame-based selection). Non-JPEG or non-http(s) URLs are rejected with `400`; a change is rejected with `409` while the post is publishing. See [Instagram → Platform-Specific Settings](../platforms/instagram.md#platform-specific-settings).
> **LinkedIn repost (reshare):** `platformSettings.linkedin` turns the group into a repost of an existing LinkedIn post — set `repostParentUrn` to a `urn:li:share:` or `urn:li:ugcPost:` (send an empty string to turn the repost off and revert to a normal post), and optionally `repostVisibility` (`PUBLIC` default; `CONNECTIONS` is personal-accounts-only). The group's post content becomes the reshare commentary (3,000-character LinkedIn limit). **Media is forbidden on repost groups** — scheduling a repost group with attached media fails validation with code `MEDIA_TYPE_NOT_SUPPORTED` (*"LinkedIn reposts cannot include media — remove the attached files or turn off the repost setting"*). If the parent post was deleted, made private, or is not reshareable, the post fails permanently at publish time with *"LinkedIn rejected the repost — the original post may have been deleted, made private, or is not reshareable."* See [Create Post → LinkedIn Repost Settings](./create-post.md#linkedin-repost-settings) for the full field reference and validation error strings.
> **X reply/quote (partial update):** set or clear `twitter.replyTo` and `twitter.quoteTweet` independently; omitted fields are preserved, and an empty string clears one. Each value is a full `x.com`/`twitter.com` status URL or a 1–19 digit post ID. `quoteTweet` may be combined with `replyTo` and media. On self-serve X API tiers, publication succeeds only when the target author mentioned the connected account in that same post, quoted one of its posts, or the connected account authored the target itself. Publora cannot prevalidate this relationship: an unrelated target can be accepted by this endpoint and later fail permanently at publish time with `X_REPLY_NOT_AUTHORIZED`. See [Create Post → X Reply and Quote Settings](./create-post.md#x-reply-and-quote-settings).
> **TikTok automatic photo music:** `platformSettings.tiktok.autoAddMusic` accepts
> a JSON boolean. Set `true` to let TikTok automatically choose music for photo
> Direct Post; Publora cannot select or preview a specific track. Explicit `false`
> is preserved. Omitting the field on update keeps the stored value. Enabling
> it with known non-photo media fails validation; send `false` to disable it
> when switching to video. Video requests never send the provider parameter.
> Incomplete drafts without media are allowed. See [TikTok music](../platforms/tiktok.md#automatic-music-for-photo-posts).
> When an appended video/document makes a stored `true` inapplicable, omitting
> `autoAddMusic` clears that preference automatically; explicit `true` still fails
> validation with non-photo media.
> **AI-generated content disclosure (partial update):** set `instagram.aiGenerated`,
> `tiktok.aiGenerated`, `youtube.aiGenerated` or `twitter.aiGenerated` to `true` or `false`;
> an omitted field keeps its stored value. Instagram fixes its "AI info" label when the
> media container is created, so changing `instagram.aiGenerated` once publishing has started
> — the group is `processing`, an Instagram platform post is `pending`/`processing`, or it
> already holds a media container — returns `409 POST_PUBLISH_IN_PROGRESS` like a content
> edit. Re-read the post and retry only while it is still `draft` or `scheduled`. Resending the
> stored value or changing another Instagram setting is not gated; TikTok, YouTube and X read
> the flag at publish time. See [Create Post → AI-Generated Content Disclosure](./create-post.md#ai-generated-content-disclosure).
### Unknown platformSettings paths
Every path you send is checked against the accepted tree **before anything is written**. An unrecognized top-level platform, or an unrecognized nested key under a known one, is rejected — the whole request is a no-op:
```json
{
"error": "Unknown platformSettings path: youtube.thumbnail.mediaID",
"code": "PLATFORM_SETTING_UNKNOWN",
"field": "youtube.thumbnail.mediaID"
}
```
`field` is the exact dotted path that failed, so you can point a user straight at the typo. Nested references are checked down to their leaves — `youtube.playlist.{id,platformId}` and `youtube.thumbnail.{mediaId,id,url,path}`. This matters most for thumbnails: a miscased `youtube.thumbnail.mediaID` previously slipped through the allowlist and **silently cleared an already-uploaded thumbnail**. It is now a `400`.
Values under a known leaf are never traversed, so these keep working unchanged:
- Aliases — `instagram.cover_url` (for `coverUrl`), `youtube.thumbnail.id` (for `mediaId`), `youtube.thumbnail.path` (for `url`)
- String booleans — `"true"` / `"false"` / `"1"` / `"0"` / `"yes"` / `"no"` / `"on"` / `"off"`
- Comma-separated `youtube.tags`
The deprecated flat fields `youtube.playlistId` and `youtube.thumbnailUrl` still return their existing guidance errors (e.g. *"playlistId is not supported; use …playlist"*) rather than `PLATFORM_SETTING_UNKNOWN`.
### Editing content and targets
`content` and `platforms` let you correct a post you already created instead of deleting it and starting over.
```bash
curl -X PUT https://api.publora.com/api/v1/update-post/507f1f77bcf86cd799439011 \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Corrected launch announcement.",
"platforms": ["linkedin-ABC123", "twitter-XYZ789"]
}'
```
**How the fields behave**
- **`content` replaces the base text.** Each platform post is rewritten to its *effective* content: the base text for normal targets, or the account's own text where a per-account override exists (overrides created in the web editor survive a base-content edit). Editing the text of a Twitter or Threads target also clears the derived thread split so it is recomputed from the new text.
- **`platforms` replaces the entire target set.** Send the complete list you want — IDs not in the array have their platform posts removed. Added IDs are checked for ownership and plan entitlement before anything is written; a duplicate ID in the array is rejected. Copy IDs verbatim from [`GET /platform-connections`](./platform-connections.md).
- **Editing a post that is already `scheduled` re-runs post validation** against the new final state. A failure returns `400 { "error": "Validation failed", "validation": {…} }` and nothing is written.
- **Adding a target to a `scheduled` post additionally re-runs scheduling checks** — plan availability and posting limits. Reordering the same IDs is not a change and skips those checks.
- **Removing every target** is allowed only while the post is (or becomes) a draft. Scheduling an empty set returns `400 PLATFORMS_REQUIRED`.
- **The write is all-or-nothing.** Group, platform posts, and the group's post list commit together, guarded by a compare-and-swap. A failed validation or a lost race leaves the post exactly as it was.
- **A settings-only change of `instagram.aiGenerated` takes the same gates.** Instagram fixes its "AI info" label when the media container is created, so flipping that flag is refused with the same `POST_PUBLISH_IN_PROGRESS` responses as a content edit once publishing has started. Other `platformSettings` keys keep their own rules (see the notes above).
**When editing is refused**
| Situation | Response |
|---|---|
| Group status is not `draft` or `scheduled` (e.g. `published`, `failed`) | `400` `POST_NOT_EDITABLE` |
| A platform post has already reached a terminal state | `400` `POST_NOT_EDITABLE` |
| The group is being published (`processingStatus: processing`) | `409` `POST_PUBLISH_IN_PROGRESS` |
| A platform post is already `pending` or `processing` | `409` `POST_PUBLISH_IN_PROGRESS` |
| A platform upload/publish has a resumable operation in flight | `409` `POST_PUBLISH_IN_PROGRESS` |
| Another edit committed while this one was in flight | `409` `POST_GROUP_VERSION_CONFLICT` |
`POST_PUBLISH_IN_PROGRESS` and `POST_GROUP_VERSION_CONFLICT` are conflicts, not permanent failures — re-read the post with [`GET /get-post`](./get-post.md) and retry only if it is still `draft` or `scheduled`. Do **not** blind-retry an edit that races publishing; that is exactly what these codes exist to prevent.
> **Retry safety:** send an [`Idempotency-Key`](#idempotency) with content/platform edits too. A replayed key returns the original response instead of re-applying the edit over a post that has since moved on.
### ISO 8601 DateTime Format
The `scheduledTime` must be a valid ISO 8601 UTC datetime string:
```
YYYY-MM-DDTHH:mm:ss.sssZ
```
**Valid formats:**
```
2026-03-15T10:00:00.000Z ✓ Full format with milliseconds
2026-03-15T10:00:00Z ✓ Without milliseconds
2026-03-15T10:00:00+00:00 ✓ With explicit UTC offset
```
**Invalid formats:**
```
2026-03-15 10:00:00 ✗ Missing T separator and timezone
March 15, 2026 ✗ Not ISO 8601
03/15/2026 ✗ Not ISO 8601
2026-03-15 ✗ Missing time component
```
### Timing Constraints
- **Past times:** Never silent. A time in the past is either clamped to the current server time **with a `warnings` entry in the response**, or rejected with `400 SCHEDULED_TIME_IN_PAST` — see [Past scheduled times](#past-scheduled-times) for the exact rule and the migration date.
- **No scheduled time:** If the resulting status is `scheduled` and neither the request body nor the existing post has a `scheduledTime`, it defaults to the current time (`new Date()`). This default does not apply when updating to `draft` — the existing value is preserved
- **Maximum:** Recommended within 2 months for best reliability
- **Timezone:** Always use UTC (Z suffix or +00:00 offset)
### Past scheduled times
| How far in the past | Today | When strict mode is active (scheduled **2026-08-25** by default) |
|---|---|---|
| Less than 5 minutes | Clamped to server time + `SCHEDULED_TIME_COERCED` warning | **Unchanged — still clamped + warned** |
| 5 minutes or more | Clamped to server time + `SCHEDULED_TIME_COERCED` warning | **Rejected — `400 SCHEDULED_TIME_IN_PAST`** |
> **The 5-minute tolerance is permanent.** The *5-minutes-or-more* case is scheduled to flip from clamp-and-warn to a hard `400` on 2026-08-25, unless production configuration overrides that date either way.
Clamped requests still return `200`, and the response carries the warning:
```json
{
"success": true,
"message": "Post updated successfully",
"scheduledTime": "2026-07-15T09:31:04.812Z",
"warnings": [
{
"code": "SCHEDULED_TIME_COERCED",
"message": "Requested scheduled time 2026-07-15T08:00:00.000Z was in the past and was changed to server time 2026-07-15T09:31:04.812Z.",
"requested": "2026-07-15T08:00:00.000Z",
"effective": "2026-07-15T09:31:04.812Z"
}
],
"postGroup": {
"_id": "507f1f77bcf86cd799439011",
"status": "scheduled",
"scheduledTime": "2026-07-15T09:31:04.812Z"
}
}
```
Once strict mode is on, that same request returns:
```json
{
"error": "Scheduled time is in the past. Server time is 2026-07-15T09:31:04.812Z UTC.",
"code": "SCHEDULED_TIME_IN_PAST",
"serverTime": "2026-07-15T09:31:04.812Z"
}
```
**Migrate now:** treat every `SCHEDULED_TIME_COERCED` warning where the gap is 5 minutes or more as a future `400`. Log it, and re-send a time in the future. `serverTime` on the error is the authoritative clock to compute against. For the full rationale and cross-endpoint behaviour, see [Scheduling → Past scheduled times](../guides/scheduling.md#past-scheduled-times).
> **Status-only transitions validate the *stored* time.** Sending `{ "status": "scheduled" }` with **no** `scheduledTime`, on a post that is not already scheduled, runs the post's **existing stored** time through the rules above. An old draft whose stored time has since passed therefore now returns a `SCHEDULED_TIME_COERCED` warning (and, once strict mode is on, a `400 SCHEDULED_TIME_IN_PAST`). Previously it silently published at the stale time — effectively immediately. If you flip old drafts to `scheduled`, always send an explicit fresh `scheduledTime` alongside the status.
### Scheduling Limits
When rescheduling a post (changing `scheduledTime`), the update flow performs two validations:
1. **Platform availability check** (`assertPlatformsAllowed`): Verifies that all platforms targeted by the post are still available on the user's current plan. If a platform is no longer allowed, a `PLATFORM_NOT_AVAILABLE` error is returned.
2. **Limits check**: Validates that the new time does not exceed the account's posting limits for the target time slot.
If either check fails, the request returns a **403** error with a `LimitExceededError` message describing which limit was hit.
> **Note:** There is no minimum-interval adjustment. A schedule-horizon violation returns `403`; only the documented past-time compatibility ramp can clamp a time, with a `SCHEDULED_TIME_COERCED` warning.
### Helper Functions
**JavaScript:**
```javascript
function toISO8601(date) {
return new Date(date).toISOString();
}
function scheduleForTomorrow(hour = 9, minute = 0) {
const date = new Date();
date.setDate(date.getDate() + 1);
date.setUTCHours(hour, minute, 0, 0);
return date.toISOString();
}
// Usage
const scheduledTime = scheduleForTomorrow(14, 0); // Tomorrow at 2pm UTC
// "2026-02-21T14:00:00.000Z"
```
**Python:**
```python
from datetime import datetime, timedelta, timezone
def to_iso8601(dt):
"""Convert datetime to ISO 8601 UTC string."""
if dt.tzinfo is None:
dt = dt.replace(tzinfo=timezone.utc)
return dt.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.000Z')
def schedule_for_tomorrow(hour=9, minute=0):
"""Get ISO 8601 string for tomorrow at specified time (UTC)."""
tomorrow = datetime.now(timezone.utc) + timedelta(days=1)
scheduled = tomorrow.replace(hour=hour, minute=minute, second=0, microsecond=0)
return to_iso8601(scheduled)
# Usage
scheduled_time = schedule_for_tomorrow(14, 0) # Tomorrow at 2pm UTC
# "2026-02-21T14:00:00.000Z"
```
## Idempotency
Send an optional `Idempotency-Key` header with any value unique to the logical operation (a UUID works). It is **opt-in** — omit it and behaviour is exactly as before.
| Situation | Result |
|---|---|
| Same key, same body | The original response is **replayed** (same status code, same body). The update is not applied twice. |
| Same key, **different** body | `422` `IDEMPOTENCY_KEY_CONFLICT` |
| Same key, original still running | `409` `IDEMPOTENCY_IN_FLIGHT` |
| New key | Processed normally |
Keys are scoped to the API key's user and expire **24 hours** after first use. Two different users can safely use the same key string.
> **Why it matters most here:** `mediaUrls` on `update-post` has **append** semantics. A timeout or network blip on a request that already committed leaves you no way to tell whether it landed — and a naive retry appends the same media **again**, producing duplicate attachments on the post. With an `Idempotency-Key`, the retry replays the original response instead. **Always send one when the body contains `mediaUrls`.**
```javascript
const key = crypto.randomUUID(); // reuse this exact key for every retry
await fetch(`https://api.publora.com/api/v1/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': process.env.PUBLORA_API_KEY,
'Idempotency-Key': key
},
body: JSON.stringify({
mediaUrls: ['https://example.com/photo.jpg']
})
});
```
Generate the key **once per logical update** and reuse it across retries. Generating a fresh key per attempt defeats the protection entirely.
## Response
```json
{
"success": true,
"message": "Post updated successfully",
"scheduledTime": "2026-03-15T10:00:00.000Z",
"postGroup": {
"_id": "507f1f77bcf86cd799439011",
"status": "scheduled",
"content": "Corrected launch announcement.",
"platforms": ["linkedin-ABC123", "twitter-XYZ789"],
"scheduledTime": "2026-03-15T10:00:00.000Z"
}
}
```
| Field | Type | Description |
|-------|------|-------------|
| `scheduledTime` | string/null | **Always present.** The effective stored time after any permitted past-time clamp. `null` if the post has no scheduled time. |
| `postGroup.content` | string | **Always present.** The effective base text stored after the update (`""` if the post has none). |
| `postGroup.platforms` | string[] | **Always present.** The effective target set stored after the update (`[]` for a draft with no targets). |
| `postGroup.scheduledTime` | string | The same value; included only when the post has a scheduled time set. |
| `warnings` | array | Present only when something was adjusted — e.g. a `SCHEDULED_TIME_COERCED` entry. See [Past scheduled times](#past-scheduled-times). |
A post is never scheduled while its media is still being validated. If validation does not finish in time, the request returns `503` with `Retry-After` and the post is not changed; validation progress on the media is kept for the retry. See [Media scheduling codes](../guides/error-codes.md#media-scheduling-codes).
## Examples
### Fix a typo and swap a target account
```javascript
// platforms REPLACES the stored set — send the complete final list.
const connections = await fetch('https://api.publora.com/api/v1/platform-connections', {
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
}).then(r => r.json());
await fetch(`https://api.publora.com/api/v1/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': process.env.PUBLORA_API_KEY,
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
content: 'Corrected launch announcement.',
platforms: ['linkedin-ABC123', 'threads-DEF456']
})
});
```
```python
requests.put(
f'https://api.publora.com/api/v1/update-post/{post_group_id}',
headers={
'Content-Type': 'application/json',
'x-publora-key': os.environ['PUBLORA_API_KEY']
},
json={
'content': 'Corrected launch announcement.',
'platforms': ['linkedin-ABC123', 'threads-DEF456']
}
)
```
### Reschedule a post
#### JavaScript (fetch)
```javascript
const response = await fetch(
`https://api.publora.com/api/v1/update-post/${postGroupId}`,
{
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
scheduledTime: '2026-03-15T10:00:00.000Z'
})
}
);
```
#### Python (requests)
```python
response = requests.put(
f'https://api.publora.com/api/v1/update-post/{post_group_id}',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={'scheduledTime': '2026-03-15T10:00:00.000Z'}
)
```
#### cURL
```bash
curl -X PUT https://api.publora.com/api/v1/update-post/507f1f77bcf86cd799439011 \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{"scheduledTime": "2026-03-15T10:00:00.000Z"}'
```
### Change a draft to scheduled
```javascript
await fetch(`https://api.publora.com/api/v1/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-04-01T12:00:00.000Z'
})
});
```
### Publish an existing post now
```javascript
await fetch(`https://api.publora.com/api/v1/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({ publishNow: true })
});
```
`publishNow: true` works on a draft or a scheduled post. The server sets `scheduledTime` to its current time and starts delivery; the response does not wait for the platforms. The same validation, media and monthly-limit checks as [Create Post → Publish now](./create-post.md#publish-now) apply. A scheduled post that you publish now frees its scheduled-queue slot and keeps the monthly reservation it already had, as long as the month and targets do not change. Rescheduling a Publish Now post to a future time turns it back into a normal scheduled post, and the queue and horizon are checked again.
### Pause a scheduled post (move to draft)
```python
response = requests.put(
f'https://api.publora.com/api/v1/update-post/{post_group_id}',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={'status': 'draft'}
)
```
### Node.js (axios)
```javascript
const axios = require('axios');
const client = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
});
async function reschedulePost(postGroupId, newTime) {
const { data } = await client.put(`/update-post/${postGroupId}`, {
scheduledTime: newTime
});
return data;
}
// Usage
await reschedulePost('507f1f77bcf86cd799439011', '2026-03-20T14:00:00.000Z');
```
### With Error Handling
```javascript
async function updatePostSafely(postGroupId, updates) {
try {
const response = await fetch(
`https://api.publora.com/api/v1/update-post/${postGroupId}`,
{
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': process.env.PUBLORA_API_KEY
},
body: JSON.stringify(updates)
}
);
const data = await response.json();
if (!response.ok) {
switch (response.status) {
case 400:
if (data.error?.includes('status')) {
throw new Error('Post is in a non-editable status. Cannot update.');
}
throw new Error(data.error || 'Invalid request');
case 401:
throw new Error('Authentication failed. Check your API key.');
case 403:
throw new Error('API access is not enabled for this account.');
case 404:
throw new Error('Post not found. It may have been deleted.');
default:
throw new Error(data.error || `HTTP ${response.status}`);
}
}
return data;
} catch (error) {
console.error('Failed to update post:', error.message);
throw error;
}
}
```
```python
def update_post_safely(post_group_id, updates):
"""Update a post with comprehensive error handling."""
try:
response = requests.put(
f'https://api.publora.com/api/v1/update-post/{post_group_id}',
headers={
'Content-Type': 'application/json',
'x-publora-key': os.environ['PUBLORA_API_KEY']
},
json=updates
)
data = response.json()
if response.status_code == 400:
error = data.get('error', '')
if 'status' in error.lower():
raise ValueError('Post is in a non-editable status. Cannot update.')
raise ValueError(error or 'Invalid request')
if response.status_code == 401:
raise ValueError('Authentication failed. Check your API key.')
if response.status_code == 403:
raise ValueError('API access is not enabled for this account.')
if response.status_code == 404:
raise ValueError('Post not found. It may have been deleted.')
response.raise_for_status()
return data
except requests.RequestException as e:
print(f'Failed to update post: {e}')
raise
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | Missing update fields | None of `publishNow`, `status`, `scheduledTime`, `content`, `platforms`, `platformSettings`, `firstComment`, `firstComments`, or `mediaUrls` was provided |
| 400 | `"firstComment must be an object { text, platforms? }"` / `"Unknown first comment platform …"` / `"First comment is too long for : …"` — codes `FIRST_COMMENT_INVALID`, `FIRST_COMMENT_PLATFORM_UNKNOWN`, `FIRST_COMMENT_TOO_LONG` | The first comment failed shape, platform-type or per-platform length validation — also raised when a `platforms` change makes the **stored** comment too long for a newly added platform. See [Create Post → First comment](./create-post.md#first-comment). |
| 400 | `FIRST_COMMENT_INVALID` | `firstComments` exceeds three entries, has an invalid item/delay, or is sent together with `firstComment` |
| 400 | `"Content must be a string"` — code `INVALID_CONTENT` | `content` was sent as something other than a string. Response includes `field: "content"`. |
| 400 | `"Platforms must be an array"` / `"Invalid platforms JSON format"` / `"Invalid platform ID format: {id}"` / `"Platforms must not contain duplicates"` — code `INVALID_PLATFORMS` | `platforms` failed shape validation. Response includes `field: "platforms"`. |
| 400 | `"Invalid platform connection(s): {ids}. Check connected accounts or call GET /platform-connections."` — code `INVALID_PLATFORM_CONNECTION` | A newly added platform ID is not a connection owned by the acting user. Response includes `invalidPlatforms`. |
| 400 | `"At least one platform is required to schedule a post. Add a platform or keep the post as a draft."` — code `PLATFORMS_REQUIRED` | The effective final state is `scheduled` with an empty `platforms` array |
| 400 | `"Cannot edit a post with a child in {status} status."` — code `POST_NOT_EDITABLE` | A platform post under this group has already reached a terminal state |
| 409 | `"Post publishing has already started; the post can no longer be edited."` / `"…retrying this edit could publish stale or duplicate content."` / `"A platform upload or publish operation has already started; editing now could publish stale content."` — code `POST_PUBLISH_IN_PROGRESS` | The group or one of its platform posts is publishing. Re-read with `GET /get-post` before retrying. |
| 409 | `"Post group state changed concurrently; please retry."` — code `POST_GROUP_VERSION_CONFLICT` | Another write committed first; this request changed nothing. Re-read and retry. |
| 400 | `"Unknown platformSettings path: {path}"` — code `PLATFORM_SETTING_UNKNOWN` | An unrecognized top-level platform or nested settings key. The response includes `field` with the exact dotted path. Nothing is persisted. |
| 400 | `"platformSettings.linkedin.*"` validation errors | Invalid LinkedIn repost settings (bad URN shape, bad visibility, `repostEnabled`/`repostParentUrn` mismatch) — see [Create Post → LinkedIn Repost Settings](./create-post.md#linkedin-repost-settings) |
| 400 | `"LinkedIn company-page reposts cannot use CONNECTIONS visibility; choose PUBLIC"` | `repostVisibility: "CONNECTIONS"` on a scheduled group that targets a LinkedIn company-page connection |
| 400 | `"Scheduled time is in the past. Server time is {t} UTC."` — code `SCHEDULED_TIME_IN_PAST` | The requested or stored time is 5+ minutes in the past while strict mode is active (scheduled for **2026-08-25** unless configuration overrides it). Includes `serverTime`. |
| 400 | `"Idempotency-Key request body is too deeply nested"` — code `IDEMPOTENCY_BODY_TOO_COMPLEX` | The request body sent with an `Idempotency-Key` exceeds the nesting limit and cannot be hashed |
| 409 | `"A request with this idempotency key is still in flight"` — code `IDEMPOTENCY_IN_FLIGHT` | Another request with the same `Idempotency-Key` is still being processed. Retry shortly. |
| 422 | `"Idempotency key was already used with a different request body"` — code `IDEMPOTENCY_KEY_CONFLICT` | The same `Idempotency-Key` was reused with a different body. Use a new key. |
| 400 | `"Status must be either 'draft' or 'scheduled'"` | Invalid status value |
| 400 | `"Invalid scheduled time format"` | Malformed datetime string |
| 400 | `"publishNow must be a boolean"` — code `INVALID_PUBLISH_NOW` | `publishNow` is present but not `true` or `false` |
| 400 | `"publishNow cannot be combined with a draft status"` / `"publishNow cannot be combined with an invalid or future scheduledTime"` — code `PUBLISH_NOW_CONFLICT` | `publishNow: true` sent with `status: "draft"` or a future `scheduledTime` |
| 400 | `"Cannot update post: post is currently in {status} status"` — code `POST_NOT_EDITABLE` | Post is in any status other than `draft` or `scheduled` |
| 400 | codes `MEDIA_UPLOAD_MISSING`, `MEDIA_VALIDATION_FAILED`, `MEDIA_REFERENCE_MISSING`, `MEDIA_NOT_READY` | Scheduling found an attached media file that cannot be used. The post was not changed; a media file the check marked `failed` stays failed. See [Media scheduling codes](../guides/error-codes.md#media-scheduling-codes). |
| 503 | codes `MEDIA_UPLOAD_PENDING`, `MEDIA_VALIDATION_PENDING` | An attached upload is not in storage yet, or its validation did not finish in time. The post was not scheduled or changed; validation progress on the media is kept. Retry after the `Retry-After` header (also `retryAfterSec`). |
| 503 | `"Unable to check Threads permissions. Please try scheduling again shortly."` — code `THREADS_PERMISSIONS_UNAVAILABLE` | Scheduling a Threads chain (a Threads target with more than one part) needed a permission check that Publora could not complete. The body is only `{ code, error }`, with no `retryable` field and no `Retry-After` header. Retry in a few seconds; it never means reconnect. See [Threads chain codes](../guides/error-codes.md#at-scheduling). |
| 400 | `"Invalid post group ID"` | `postGroupId` is not a valid ObjectId |
| 401 | `"API key is required"` | Missing `x-publora-key` header |
| 401 | `"Invalid API key"` | `x-publora-key` value is incorrect or revoked |
| 401 | `"Invalid API key owner"` | The API key exists but its owner account could not be found |
| 403 | `"API access is not enabled for this account"` | No active subscription or API access not enabled |
| 403 | `"MCP access is not enabled for this account"` | The account does not have MCP access enabled (MCP-only keys) |
| 403 | `LimitExceededError` (structured JSON) | Rescheduling would exceed the account's posting limits for the target time slot (see below) |
| 404 | `"Post group not found"` | No post with this ID belongs to the acting user |
| 500 | `"Failed to update post"` | Internal server error |
| 500 | `"Internal server error"` | Unexpected server error in middleware |
> **Note:** The `status` field must be a **non-empty string**. The server uses a JavaScript falsy check, so empty strings (`""`), `null`, and `0` are all treated as absent. `content` and `platforms` are detected by **key presence**, not truthiness — sending `"content": ""` or `"platforms": []` counts as a real edit. If `status` and `scheduledTime` are both falsy and none of `content`, `platforms`, `platformSettings`, or `mediaUrls` is present, you will receive the "At least one of status, scheduledTime, content, platforms, platformSettings, or mediaUrls must be provided" error.
> **Note:** A `postGroupId` that is not a valid MongoDB ObjectId returns `400 { "error": "Invalid post group ID" }` before any lookup. Pass the IDs returned by create-post or list-posts.
### Limit Exceeded Error Format
When a **403** limit error is returned, the response body is a structured JSON object (not a simple string):
```json
{
"error": "Post limit reached",
"code": "POST_LIMIT_REACHED",
"metric": "posts.platform_monthly",
"message": "Monthly post limit reached. Your Pro plan allows 50 platform posts per month.",
"limit": 50,
"used": 48,
"requested": 3,
"remaining": 2,
"periodStart": "2026-03-01T00:00:00.000Z",
"periodEnd": "2026-04-01T00:00:00.000Z",
"planName": "Pro"
}
```
| Field | Type | Description |
|-------|------|-------------|
| `error` | string | Descriptive error string (see values below) |
| `code` | string | Error code identifying which limit was hit (see values below) |
| `metric` | string | Which limit metric was exceeded (see values below) |
| `message` | string | Human-readable description of the limit violation |
| `limit` | number | Maximum allowed value for this metric |
| `used` | number/null | How many have been used in the current period (`null` for date-based limits) |
| `requested` | number/null | How many were requested in this operation (`null` for date-based limits) |
| `remaining` | number/null | How many are still available (`null` for date-based limits) |
| `periodStart` | string | ISO 8601 start of the current billing/limit period |
| `periodEnd` | string | ISO 8601 end of the current billing/limit period |
| `planName` | string | The user's current plan name |
**Error codes and their corresponding `error` and `metric` values:**
| `code` | `error` | `metric` |
|--------|---------|----------|
| `POST_LIMIT_REACHED` | `"Post limit reached"` | `"posts.platform_monthly"` |
| `SCHEDULED_POST_LIMIT_REACHED` | `"Scheduled post limit reached"` | `"posts.scheduled_active"` |
| `SCHEDULE_HORIZON_REACHED` | `"Schedule horizon reached"` | `"posts.schedule_horizon_days"` |
| `PLATFORM_NOT_AVAILABLE` | `"Platform not available"` | `"posts.platform_monthly"` |
| `CONNECTIONS_OVER_LIMIT` | `"Account over channel limit"` | `"connections.total"` |
> **Note:** For `SCHEDULE_HORIZON_REACHED`, the `used`, `requested`, and `remaining` fields are `null` since this limit is date-based rather than count-based.
> **Note:** Additional top-level context depends on the code: `scheduledTime`/`maxScheduledDate` for the schedule horizon; `limitScope` and (for connection scope) `blockedPlatforms` for monthly posts; workspace fields for the scheduled queue; and platform allowlist fields for availability checks.
> **Note (low priority):** When a `LimitExceededError` is triggered, the API also sends a limit-reached notification email to the account owner as a side effect. This is an internal behavior and does not affect the API response.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/delete-post
# Delete Post
Delete a post across all platforms where it was created. This endpoint removes the entire post group and all associated platform-specific posts in a single operation, regardless of the post's current status.
## Endpoint
```
DELETE https://api.publora.com/api/v1/delete-post/:postGroupId
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `"mcp"`) |
## Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `postGroupId` | string | The post group ID to delete |
## Response
Returns HTTP **200** with the following JSON body on success:
```json
{
"success": true
}
```
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Whether the deletion succeeded (only present on **200** responses) |
> **Note:** The `success` field only appears on successful (200) responses. Error responses return an `error` string field instead (e.g., `{ "error": "Post group not found" }`).
## What Gets Deleted
When you delete a post group, the following are removed (in this order):
**Inside the database transaction:**
1. **The post group record** - Find and delete the parent container for all platform posts
2. **Find media files** - Locate all media file references associated with the post group
3. **Delete media file records from database** - Remove media references from the database
4. **All platform-specific posts** - Delete Twitter post, LinkedIn post, Instagram post, etc.
**After the transaction commits:**
5. **All media files from S3 storage** - The actual image and video files are deleted from S3
### Deletion Behavior
- **Atomic operation**: The deletion uses a MongoDB transaction to ensure all database records (post group, platform posts, and media records) are deleted atomically. If any database deletion fails, the entire operation is rolled back.
- **S3 cleanup**: Media files are deleted from S3 storage after the database transaction completes. S3 deletion failures are logged but do not fail the request - your post will still be successfully deleted even if S3 cleanup encounters issues.
## Examples
### JavaScript - Delete Post Across All Platforms
```javascript
async function deletePostAcrossAllPlatforms(apiKey, postGroupId) {
const response = await fetch(
`https://api.publora.com/api/v1/delete-post/${postGroupId}`,
{
method: 'DELETE',
headers: { 'x-publora-key': apiKey }
}
);
if (!response.ok) {
const error = await response.json();
throw new Error(`Failed to delete: ${error.error || response.statusText}`);
}
const data = await response.json();
console.log(`Successfully deleted post ${postGroupId}`);
return data;
}
// Usage
await deletePostAcrossAllPlatforms('YOUR_API_KEY', '507f1f77bcf86cd799439011');
```
### JavaScript - Delete Multiple Posts
```javascript
async function deleteMultiplePosts(apiKey, postGroupIds) {
const results = {
succeeded: [],
failed: []
};
for (const postGroupId of postGroupIds) {
try {
const response = await fetch(
`https://api.publora.com/api/v1/delete-post/${postGroupId}`,
{
method: 'DELETE',
headers: { 'x-publora-key': apiKey }
}
);
if (response.ok) {
results.succeeded.push({ postGroupId });
} else {
const error = await response.json();
results.failed.push({ postGroupId, error: error.error });
}
} catch (err) {
results.failed.push({ postGroupId, error: err.message });
}
}
console.log(`Deleted ${results.succeeded.length} posts`);
console.log(`Failed: ${results.failed.length}`);
return results;
}
// Usage: Delete all posts from a list
const postIds = ['507f1f77bcf86cd799439011', '507f1f77bcf86cd799439012', '507f1f77bcf86cd799439013'];
await deleteMultiplePosts('YOUR_API_KEY', postIds);
```
### JavaScript - Delete with Confirmation
```javascript
async function deletePostWithConfirmation(apiKey, postGroupId) {
// First, get post details to show what will be deleted
const getResponse = await fetch(
`https://api.publora.com/api/v1/get-post/${postGroupId}`,
{ headers: { 'x-publora-key': apiKey } }
);
if (!getResponse.ok) {
throw new Error('Post not found');
}
const postData = await getResponse.json();
console.log('About to delete:');
console.log(` Content: ${postData.posts[0]?.content?.slice(0, 50)}...`);
console.log(` Platforms: ${postData.posts.map(p => p.platform).join(', ')}`);
console.log(` Status: ${postData.posts[0]?.status}`);
// Perform deletion
const deleteResponse = await fetch(
`https://api.publora.com/api/v1/delete-post/${postGroupId}`,
{
method: 'DELETE',
headers: { 'x-publora-key': apiKey }
}
);
const result = await deleteResponse.json();
console.log('Deletion complete:', result);
return result;
}
```
### Python - Delete Post Across All Platforms
```python
import requests
from typing import Dict, Any
def delete_post_across_all_platforms(api_key: str, post_group_id: str) -> Dict[str, Any]:
"""
Delete a post from all platforms where it was scheduled.
Args:
api_key: Your Publora API key
post_group_id: The post group ID to delete
Returns:
Deletion result with success status
"""
response = requests.delete(
f'https://api.publora.com/api/v1/delete-post/{post_group_id}',
headers={'x-publora-key': api_key}
)
response.raise_for_status()
data = response.json()
print(f"Successfully deleted post {post_group_id}")
return data
# Usage
result = delete_post_across_all_platforms('YOUR_API_KEY', '507f1f77bcf86cd799439011')
```
### Python - Bulk Delete with Error Handling
```python
import requests
from typing import List, Dict, Tuple
def bulk_delete_posts(api_key: str, post_group_ids: List[str]) -> Tuple[List[str], List[Dict]]:
"""
Delete multiple posts, returning succeeded and failed results.
Args:
api_key: Your Publora API key
post_group_ids: List of post group IDs to delete
Returns:
Tuple of (succeeded_ids, failed_list)
"""
succeeded = []
failed = []
for post_group_id in post_group_ids:
try:
response = requests.delete(
f'https://api.publora.com/api/v1/delete-post/{post_group_id}',
headers={'x-publora-key': api_key}
)
if response.ok:
succeeded.append(post_group_id)
else:
error = response.json()
failed.append({
'postGroupId': post_group_id,
'error': error.get('error', 'Unknown error')
})
except Exception as e:
failed.append({
'postGroupId': post_group_id,
'error': str(e)
})
print(f"Successfully deleted: {len(succeeded)}")
print(f"Failed: {len(failed)}")
return succeeded, failed
# Usage
post_ids = ['507f1f77bcf86cd799439011', '507f1f77bcf86cd799439012']
succeeded, failed = bulk_delete_posts('YOUR_API_KEY', post_ids)
```
### Python - Delete All Scheduled Posts for a Platform
```python
import requests
def delete_all_scheduled_for_platform(api_key: str, platform: str) -> int:
"""
Delete all scheduled posts that include a specific platform.
Args:
api_key: Your Publora API key
platform: Platform name (twitter, linkedin, instagram, etc.)
Returns:
Number of posts deleted
"""
headers = {'x-publora-key': api_key}
deleted_count = 0
page = 1
while True:
# Fetch scheduled posts filtered by platform
response = requests.get(
'https://api.publora.com/api/v1/list-posts',
headers=headers,
params={
'status': 'scheduled',
'platform': platform,
'page': page,
'limit': 100
}
)
data = response.json()
if not data['posts']:
break
# Delete each post
for post in data['posts']:
delete_response = requests.delete(
f"https://api.publora.com/api/v1/delete-post/{post['postGroupId']}",
headers=headers
)
if delete_response.ok:
deleted_count += 1
print(f"Deleted {post['postGroupId']} from {platform}")
if not data['pagination']['hasNextPage']:
break
page += 1
print(f"Total posts deleted: {deleted_count}")
return deleted_count
# Usage: Delete all scheduled Twitter posts
delete_all_scheduled_for_platform('YOUR_API_KEY', 'twitter')
```
### Node.js (axios) - Delete with Full Error Handling
```javascript
const axios = require('axios');
class PubloraClient {
constructor(apiKey) {
this.api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: { 'x-publora-key': apiKey }
});
}
async deletePost(postGroupId) {
try {
await this.api.delete(`/delete-post/${postGroupId}`);
return { success: true, postGroupId };
} catch (error) {
if (error.response) {
return {
success: false,
postGroupId,
error: error.response.data.error || 'Unknown error',
status: error.response.status
};
}
throw error;
}
}
async deleteMultiplePosts(postGroupIds) {
const results = await Promise.allSettled(
postGroupIds.map(id => this.deletePost(id))
);
return results.map((result, index) => ({
postGroupId: postGroupIds[index],
...(result.status === 'fulfilled' ? result.value : { success: false, error: result.reason.message })
}));
}
}
// Usage
const client = new PubloraClient('YOUR_API_KEY');
// Delete single post across all platforms
const result = await client.deletePost('507f1f77bcf86cd799439011');
console.log(`Deleted: ${result.success}`);
// Delete multiple posts
const results = await client.deleteMultiplePosts([
'507f1f77bcf86cd799439011',
'507f1f77bcf86cd799439012',
'507f1f77bcf86cd799439013'
]);
const succeeded = results.filter(r => r.success);
const failed = results.filter(r => !r.success);
console.log(`Deleted: ${succeeded.length}, Failed: ${failed.length}`);
```
### cURL - Delete Post
```bash
# Delete a single post across all platforms
curl -X DELETE "https://api.publora.com/api/v1/delete-post/507f1f77bcf86cd799439011" \
-H "x-publora-key: YOUR_API_KEY"
# Response:
# { "success": true }
```
### Bash - Bulk Delete Script
```bash
#!/bin/bash
API_KEY="YOUR_API_KEY"
POST_IDS=("507f1f77bcf86cd799439011" "507f1f77bcf86cd799439012" "507f1f77bcf86cd799439013")
SUCCEEDED=0
FAILED=0
for POST_ID in "${POST_IDS[@]}"; do
RESPONSE=$(curl -s -w "\n%{http_code}" -X DELETE \
"https://api.publora.com/api/v1/delete-post/${POST_ID}" \
-H "x-publora-key: ${API_KEY}")
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')
if [ "$HTTP_CODE" = "200" ]; then
echo "Deleted $POST_ID successfully"
SUCCEEDED=$((SUCCEEDED + 1))
else
echo "Failed to delete $POST_ID: $BODY"
FAILED=$((FAILED + 1))
fi
done
echo ""
echo "Summary: $SUCCEEDED succeeded, $FAILED failed"
```
## Errors
| Status | Response | Cause |
|--------|----------|-------|
| 400 | `{ "error": "Invalid post group ID" }` | `postGroupId` is not a valid ObjectId |
| 401 | `{ "error": "API key is required" }` | Missing `x-publora-key` header |
| 401 | `{ "error": "Invalid API key" }` | `x-publora-key` value is incorrect or revoked |
| 401 | `{ "error": "Invalid API key owner" }` | The API key exists but its owner account could not be found |
| 403 | `{ "error": "API access is not enabled for this account" }` | No active subscription or API access not enabled |
| 403 | `{ "error": "MCP access is not enabled for this account" }` | The account does not have MCP access enabled (MCP-only keys) |
| 404 | `{ "error": "Post group not found" }` | The post group ID doesn't exist or belongs to another user |
| 500 | `{ "error": "Failed to delete post group" }` | Server error during database transaction (deletion is rolled back) |
| 500 | `{ "error": "Internal server error" }` | Unexpected server error in middleware |
## Important Notes
### Cross-Platform Deletion
When you create a post with multiple platforms (e.g., Twitter, LinkedIn, and Instagram), Publora creates a **post group** containing individual platform-specific posts. Deleting via `postGroupId` removes the entire group - you don't need to delete each platform separately.
```
Post Group (postGroupId: 507f1f77bcf86cd799439011)
├── Twitter post
├── LinkedIn post
└── Instagram post
DELETE /delete-post/507f1f77bcf86cd799439011
→ Deletes ALL THREE platform posts in one request
```
### Malformed Post Group IDs
A `postGroupId` that is not a valid MongoDB ObjectId returns `400 { "error": "Invalid post group ID" }` before any lookup. Pass the IDs returned by create-post or list-posts.
### No Status Restrictions
Any post can be deleted regardless of its current status (draft, scheduled, published, failed, or partially_published). Deleting a published post removes it from Publora but does not remove it from the platforms where it was already published.
### Media File Cleanup
All media files (images, videos) associated with the deleted post are automatically removed from both the database and S3 storage. The database deletion happens atomically within a MongoDB transaction. S3 file deletion occurs after the transaction commits - if S3 deletion fails, it is logged but does not affect the success of your delete request.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/upload-media
# Upload Media
Upload images, videos, or PDF documents to attach to posts. Uses pre-signed S3 URLs for direct uploads.
## Endpoint
```
POST https://api.publora.com/api/v1/get-upload-url
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Set to `mcp` for MCP tool access |
| `Content-Type` | Yes | `application/json` |
> **MCP access:** If the `x-publora-client: mcp` header is sent, the server validates `entitlements.features.mcpAccess` and returns `403 "MCP access is not enabled for this account"` if the feature is not enabled.
## Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileName` | string | Yes | Name of the file (e.g., `photo.jpg`). The filename is sanitized before use: whitespace is trimmed, spaces are replaced with underscores, and special characters (except underscores, dots, and hyphens) are removed. For example, `my photo (1).jpg` becomes `my_photo_1.jpg`. |
| `contentType` | string | Yes | MIME type. Must begin with `image/` or `video/`, or equal `application/pdf`; otherwise the API returns `400 "Only video, image, and PDF files are allowed"`. |
| `postGroupId` | string | Yes | The post group to attach this media to. The attach helper verifies that it belongs to the effective API user. |
| `type` | string | No | `"image"`, `"video"`, or `"document"`. When omitted, the API infers it from `contentType` (including PDF → `document`). |
## Response
```json
{
"success": true,
"uploadUrl": "https://brandcraft-media.s3.amazonaws.com/images/...",
"fileUrl": "https://brandcraft-media.s3.amazonaws.com/images/1710500000000-product-photo.jpg",
"mediaId": "65f8a1b2c3d4e5f6a7b8c9d0"
}
```
| Field | Description |
|-------|-------------|
| `success` | `true` if the upload URL was generated successfully. |
| `uploadUrl` | Pre-signed S3 URL. Upload your file here via HTTP PUT. Expires in 1 hour. |
| `fileUrl` | The public URL where the file will be accessible after upload. |
| `mediaId` | The unique ID of the created media record. Use this to reference or delete the media. |
> **Internal fields:** Media records also store additional internal fields (`urlPure`, `mimeType`, `addedAt`, `filePath`, `uploadUrlExpiresAt`, `fileName` (S3 key), `metadata`) that are not returned by the API. The presigned `uploadUrl` itself is returned only in this response and is not stored on new media records. Note that `mimeType` is a top-level field on the media record when created via the API `get-upload-url` endpoint, but the `process-video` endpoint stores `mimeType` inside the `metadata` subdocument instead. The `metadata` object contains: `size`, `width`, `height`, `aspectRatio`, `format` (defaults to `"unknown"` — never populated by any endpoint), `frameRate`, `codecName`, `bitRate`, and `duration`.
### Dashboard vs API Differences
The dashboard actively uses a session-authenticated endpoint (`/media/generate-upload-url`) with a closely related response:
| Aspect | API (`/api/v1/get-upload-url`) | Dashboard (`/media/generate-upload-url`) |
|--------|-------------------------------|------------------------------------------|
| **Required fields** | `fileName`, `contentType`, `postGroupId` | `fileName`, `contentType`, `postGroupId` |
| **Optional fields** | `type` (inferred when omitted) | `metadata` (object), `type` (inferred when omitted) |
| **Validation** | Accepts `image/*`, `video/*`, or `application/pdf` | Accepts `image/*`, `video/*`, or `application/pdf` |
| **Missing-field errors** | `"fileName, contentType, and postGroupId are required"` | `"fileName and contentType are required"`, or `"postGroupId is required"` |
| **Response format** | `{ success, uploadUrl, fileUrl, mediaId }` | `{ uploadUrl, key, mediaId }` |
| **Auth** | API key (`x-publora-key`) | Session cookie |
Either route may also return `postGroupDemoted` and `message` when attaching the new asset demotes a scheduled group to draft.
## Upload Flow
> **Important:** When uploading media, always create the post as a **draft first**, upload media, then schedule. This prevents the scheduler from processing the post before media upload completes.
### Recommended workflow (with media):
```
1. POST /create-post → Create draft (no scheduledTime), get postGroupId
2. POST /get-upload-url → Get pre-signed URL
3. PUT {uploadUrl} → Upload file to S3
4. PUT /update-post/:postGroupId → Set status="scheduled" and scheduledTime
```
### Why this matters
If you create a post with `scheduledTime` set immediately, the scheduler may attempt to publish before your media upload completes — resulting in a failed post or missing media.
> **⚠ Attaching media demotes a scheduled post to draft.** If you call `get-upload-url` against a post that is already `scheduled`, the post is automatically demoted back to `draft` so the new media set gets re-validated. The response carries `postGroupDemoted: true` and a `message`. **You must re-schedule** it afterward with `PUT /update-post/:postGroupId` (`status: "scheduled"` + `scheduledTime`). Skipping the re-schedule is the most common cause of media that "uploaded fine" but never published — the post silently sits in `draft`. The same demote happens when you remove media with `DELETE /media/:mediaId`.
> **No presigned upload needed?** If the file is already reachable over HTTPS, you can skip steps 2–3. Pass public URLs as `mediaUrls` on [`create-post`](./create-post.md) or [`update-post`](./update-post.md). For a file reference with a stable file ID, such as the ones ChatGPT supplies, use [`attach-media`](./attach-media.md). In both cases Publora downloads the file on the server.
### Quick workflow (text-only posts):
```
1. POST /create-post → Create with scheduledTime (no media needed)
```
## Supported Formats
The upload endpoint validates the broad MIME family; platform-specific formats and limits are enforced when the post is scheduled.
| Type | Formats | Max Size |
|------|---------|----------|
| Image | Any `image/*` at upload; platform validator decides publishability | No shared presigned-upload cap |
| Video | Any `video/*` at upload; platform validator decides publishability | No shared presigned-upload cap |
| Document | `application/pdf` | Platform/document rules apply |
**Note:** The 512 MB per file limit applies only to the server-side multipart upload endpoint (`process-video`), not to pre-signed URL uploads. Individual platforms may impose their own size limits at publish time.
**Note:** Upload acceptance does not promise that a platform publisher will accept the same file; consult the platform limits before scheduling.
## Examples
### Complete workflow: Post with image
#### JavaScript (fetch)
```javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
// Step 1: Create draft post (no scheduledTime)
const postRes = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-publora-key': API_KEY },
body: JSON.stringify({
content: 'Check out our new product! 🚀',
platforms: ['twitter-123456789', 'linkedin-ABC123']
// No scheduledTime = draft
})
});
const { postGroupId } = await postRes.json();
// Step 2: Get upload URL
const urlRes = await fetch(`${BASE_URL}/get-upload-url`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-publora-key': API_KEY },
body: JSON.stringify({
fileName: 'product-photo.jpg',
contentType: 'image/jpeg',
type: 'image',
postGroupId
})
});
const { uploadUrl, fileUrl, mediaId } = await urlRes.json();
// Step 3: Upload file to S3
const fileBuffer = await fs.promises.readFile('./product-photo.jpg');
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: fileBuffer
});
console.log(`Uploaded: ${fileUrl} (mediaId: ${mediaId})`);
// Step 4: Schedule the post
await fetch(`${BASE_URL}/update-post/${postGroupId}`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json', 'x-publora-key': API_KEY },
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-01T14:00:00.000Z'
})
});
console.log('Post scheduled!');
```
#### Python (requests)
```python
import requests
API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.publora.com/api/v1'
headers = {'Content-Type': 'application/json', 'x-publora-key': API_KEY}
# Step 1: Create draft post
post_res = requests.post(f'{BASE_URL}/create-post', headers=headers, json={
'content': 'Check out our new product! 🚀',
'platforms': ['twitter-123456789', 'linkedin-ABC123']
})
post_group_id = post_res.json()['postGroupId']
# Step 2: Get upload URL
url_res = requests.post(f'{BASE_URL}/get-upload-url', headers=headers, json={
'fileName': 'product-photo.jpg',
'contentType': 'image/jpeg',
'type': 'image',
'postGroupId': post_group_id
})
data = url_res.json()
# Step 3: Upload file to S3
with open('product-photo.jpg', 'rb') as f:
requests.put(data['uploadUrl'], headers={'Content-Type': 'image/jpeg'}, data=f)
print(f"Uploaded: {data['fileUrl']} (mediaId: {data['mediaId']})")
# Step 4: Schedule the post
requests.put(f'{BASE_URL}/update-post/{post_group_id}', headers=headers, json={
'status': 'scheduled',
'scheduledTime': '2026-03-01T14:00:00.000Z'
})
print('Post scheduled!')
```
#### cURL
```bash
API_KEY="YOUR_API_KEY"
# Step 1: Create draft post
POST_GROUP_ID=$(curl -s -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"content": "Check out our new product! 🚀",
"platforms": ["twitter-123456789", "linkedin-ABC123"]
}' | jq -r '.postGroupId')
# Step 2: Get upload URL
UPLOAD_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/get-upload-url \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d "{
\"fileName\": \"product-photo.jpg\",
\"contentType\": \"image/jpeg\",
\"type\": \"image\",
\"postGroupId\": \"$POST_GROUP_ID\"
}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
FILE_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.fileUrl')
MEDIA_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.mediaId')
# Step 3: Upload file to S3
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
--data-binary @product-photo.jpg
# Step 4: Schedule the post
curl -X PUT "https://api.publora.com/api/v1/update-post/$POST_GROUP_ID" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"status": "scheduled",
"scheduledTime": "2026-03-01T14:00:00.000Z"
}'
```
### Upload a video
#### JavaScript (fetch)
```javascript
// Step 1: Get upload URL for video
const urlResponse = await fetch('https://api.publora.com/api/v1/get-upload-url', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
fileName: 'promo-video.mp4',
contentType: 'video/mp4',
type: 'video',
postGroupId: '507f1f77bcf86cd799439011'
})
});
const { uploadUrl, fileUrl, mediaId } = await urlResponse.json();
// Step 2: Upload video to S3
const videoBuffer = await fs.promises.readFile('./promo-video.mp4');
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'video/mp4' },
body: videoBuffer
});
```
#### Python (requests)
```python
# Step 1: Get upload URL for video
url_response = requests.post(
'https://api.publora.com/api/v1/get-upload-url',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'fileName': 'promo-video.mp4',
'contentType': 'video/mp4',
'type': 'video',
'postGroupId': '507f1f77bcf86cd799439011'
}
)
upload_url = url_response.json()['uploadUrl']
# Step 2: Upload video to S3
with open('promo-video.mp4', 'rb') as f:
requests.put(upload_url, headers={'Content-Type': 'video/mp4'}, data=f)
```
### Upload multiple images for a carousel
```javascript
const images = ['photo1.jpg', 'photo2.jpg', 'photo3.jpg', 'photo4.jpg'];
for (const image of images) {
// Get upload URL for each image
const urlRes = await fetch('https://api.publora.com/api/v1/get-upload-url', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
fileName: image,
contentType: 'image/jpeg',
type: 'image',
postGroupId: '507f1f77bcf86cd799439011'
})
});
const { uploadUrl } = await urlRes.json();
// Upload each image
const fileBuffer = await fs.promises.readFile(`./${image}`);
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: fileBuffer
});
}
// All 4 images now attached to the post group
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"fileName, contentType, and postGroupId are required"` | Missing `fileName`, `contentType`, or `postGroupId` |
| 401 | `"API key is required"` | `x-publora-key` header is missing entirely |
| 401 | `"Invalid API key"` | `x-publora-key` is present but invalid |
| 401 | `"Invalid API key owner"` | API key exists but the associated user account was not found |
| 403 | `"API access is not enabled for this account"` | The user's account does not have API access enabled |
| 403 | `"MCP access is not enabled for this account"` | The `x-publora-client: mcp` header was sent but `entitlements.features.mcpAccess` is not enabled |
| 500 | `"Failed to create upload URL"` | Internal server error during URL generation |
## Server-Side Video Upload
For video files, you can use the server-side upload endpoint which handles the upload and extracts video metadata (resolution, codec, frame rate, bitrate, duration).
> **Dashboard-only endpoint.** This endpoint uses session authentication (cookies) and is not available via API key auth. It is accessible only from the Publora dashboard.
### Endpoint
```
POST https://api.publora.com/media/process-video
```
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `Cookie` | Yes | Active dashboard session cookie |
| `Content-Type` | Yes | `multipart/form-data` |
### Request Body (multipart/form-data)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `video` | file | Yes | The video file to upload |
| `postGroupId` | string | Yes | The post group to attach this video to |
This endpoint accepts `multipart/form-data` with a single video file attached (field name: `video`) and a `postGroupId`. The server uploads the file to S3 and extracts metadata automatically. Processing is asynchronous -- the endpoint returns a `sessionId` which can be used to track progress via SSE (Server-Sent Events).
> **Resolved issue:** The `process-video` endpoint now correctly passes `type: "video"` to the presigned URL generator. This was previously a bug where the missing `type` parameter resulted in an `undefined` S3 key, but it has been fixed.
>
> **Note:** The multer `fileFilter` rejection (for unsupported video formats) throws an error inside multer's callback. The resulting HTTP response format depends on Express's global error handler and may not produce a clean JSON 400 response.
### Response
```json
{
"sessionId": "1710500000000"
}
```
The `sessionId` is returned for future use, but the SSE progress endpoint (`/processing-progress/:id`) is currently disabled (commented out in source). There is no working SSE endpoint to subscribe to yet.
**Limits:** 1 video file per request, 512 MB max. Accepted formats: MP4, MOV, AVI, MKV, and WebM.
### Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"No video file uploaded"` | No file is attached to the request |
| 400 | `"Unsupported video format. Allowed: MP4, MOV, AVI, MKV, WebM"` | The uploaded file format is not one of the accepted video formats. **Note:** This error is thrown inside multer's `fileFilter` callback, so it may not be returned as a clean JSON 400 response depending on Express's error handler. |
## Cleaning Up Abandoned Uploads
If a `POST /get-upload-url` call succeeds but the subsequent `PUT` to the presigned S3 URL is cancelled or fails, the MediaFile record is persisted to the post group. An abandoned upload would otherwise leave a broken reference that blocks re-scheduling with `503 MEDIA_UPLOAD_PENDING`, or `400 MEDIA_UPLOAD_MISSING` once `complete-media` was called and the file was marked failed. See [Media scheduling codes](../guides/error-codes.md#media-scheduling-codes).
Two REST endpoints handle this by API key:
- **`DELETE /api/v1/media/:mediaId`** — delete a single media file. Detaches it from its post group and hard-deletes the row + S3 object. Returns `{ "success": true }`. If the parent post was `scheduled`, the response also includes `postGroupDemoted: true` and the group is demoted to `draft` (re-schedule with `update-post`). Errors: `400 "Invalid mediaId"` (malformed), `404 "Media file not found"`, `409` if the group is mid-publish, `400` if the group is already `published`/`failed`.
- **`DELETE /api/v1/delete-post/:postGroupId`** — removes the whole post group and all attached media (works in `draft` or `scheduled`).
- Or use the Publora dashboard.
## Finalizing an Upload (optional)
```
POST https://api.publora.com/api/v1/complete-media/:mediaFileId
```
After you `PUT` the bytes to the presigned URL, you *may* call `complete-media` to probe the file server-side immediately: it extracts authoritative metadata and advances the media from `uploading` → `ready` (or `failed`), giving you fast "is my media valid?" feedback. It is **optional** — the `update-post` scheduling gate probes any still-`uploading` media lazily when you schedule. Auth is the same `x-publora-key`.
Response:
```json
{
"success": true,
"mediaFile": { "_id": "...", "type": "image", "mimeType": "image/jpeg", "fileName": "images/...", "url": "https://...", "status": "ready", "metadata": { } }
}
```
> Note: `complete-media` only probes an already-attached file — it does **not** attach media and does **not** demote a scheduled post. Attaching media (`get-upload-url`, [`attach-media`](./attach-media.md)) or removing it (`DELETE /media/:mediaId`, `DELETE /post/:postGroupId/media/:mediaId`) demotes a scheduled post to draft; `mediaUrls` on `update-post` keeps it scheduled and re-validates it instead. See `post.demoted` in [Webhooks](./webhooks.md).
## File URLs
Uploaded file URLs use the S3 format and are returned directly as `fileUrl` in the response from the `get-upload-url` endpoint. For example:
```
https://your-bucket.s3.amazonaws.com/images/1710500000000-product-photo.jpg
```
> **Internal note:** The API internally stores two URL fields on each media record: `url` (the S3 domain URL, e.g., `https://your-bucket.s3.amazonaws.com/...`) and `urlPure` (the CDN URL via `media.publora.com`, e.g., `https://media.publora.com/...`). Only `url` is returned in API responses. The `urlPure` field is used internally for CDN-served media.
## Platform Media Limits
| Platform | Images | Videos | Notes |
|----------|--------|--------|-------|
| X / Twitter | Up to 4 | 1 per post | PNG preferred for images |
| LinkedIn | Multiple | 1 per post | WebP auto-converted to JPEG |
| Instagram | Carousel (10) | Reels or Stories | Publora connects Instagram accounts through Instagram Login for Business and requests `instagram_business_basic` plus `instagram_business_content_publish`; personal accounts are unsupported. Whether Meta accepts a particular Creator account is determined by Meta, not Publora's code. |
| Threads | Carousel | 1 per post | WebP auto-converted |
| TikTok | Up to 35 | 1 per post | Images: JPEG, PNG, WebP; video: MP4, MOV, WebM, min 23 FPS |
| YouTube | -- | 1 per post | MP4, streaming upload |
| Facebook | Multiple | 1 per post | Carousel support |
| Bluesky | Up to 4 | 1 per post | WebP auto-converted; alt text is not settable through REST |
| Mastodon | Up to 4 | 1 per post | Standard limits |
| Telegram | Multiple | 1 per post | 1024 char caption max (bot) |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/attach-media
# Attach Media
Attach one image or video to an existing **draft** or **scheduled** post by passing a file reference: an HTTPS download URL plus a stable file ID. Publora downloads the file right away, checks the actual bytes and attaches it. You don't need a presigned `PUT` or a `complete-media` call.
This endpoint backs the MCP `attach_media` tool. ChatGPT fills that tool's `file` argument from a file in the conversation through OpenAI's `openai/fileParams`; see [MCP Tools Reference](../mcp/tools-reference.md). Any API client can call the endpoint directly.
The post is **left in draft**. This endpoint always sets the status to `draft`, so a post that was `scheduled` goes back to `draft`. (By contrast, `mediaUrls` on `update-post` keeps a scheduled post scheduled and re-validates it.) To publish it, schedule it again with [`update-post`](./update-post.md).
## Endpoint
```
POST https://api.publora.com/api/v1/attach-media/:postGroupId
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `"mcp"`) |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | Recommended. With it, a retry replays the first result instead of attaching the file a second time. See [Idempotency](#idempotency). The MCP tool always sends one. |
## Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `postGroupId` | string | ID of an existing draft or scheduled post (24 hexadecimal characters). If you need a new one, first create a draft with [`create-post`](./create-post.md) and leave out `scheduledTime`. |
## Request Body
The body can contain only `file` and `fileName`. Any other top-level field, such as `status`, `scheduledTime` or `mediaUrls`, returns `400 INVALID_MEDIA_FILE`: this endpoint attaches exactly one file and never schedules or publishes.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | The file reference described below. A string is rejected, including a local path such as `/mnt/data/image.png`, base64 data or a bare URL. |
| `fileName` | string | No | A descriptive file name with an extension, 1–255 characters, e.g. `spring-launch-banner.png`. Takes precedence over `file.file_name`. See [File name](#file-name). |
**`file` object.** It must contain only these keys. Any other key is rejected.
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `download_url` | string | Yes | The HTTPS URL Publora downloads the file from. Temporary signed URLs work. It goes through the same checks as [`mediaUrls`](./create-post.md): `https://` only, no embedded credentials, only the default port 443, and no private or loopback hosts. |
| `file_id` | string | Yes | A stable identifier for the file, up to 512 characters. Together with the post ID and the final file name, it lets Publora recognise a retry. See [Idempotency](#idempotency). |
| `mime_type` | string | No | Only a hint. Publora determines the real type from the file's bytes. |
| `file_name` | string | No | The original file name. Used when `fileName` is absent. |
### File name
Publora takes the name from `fileName` if it is present, otherwise from `file.file_name`, and uses `chatgpt-media` only when both are absent. It keeps only the last path segment, trims it, replaces each run of whitespace with `_`, and removes every character other than ASCII letters, digits, `_`, `.` and `-`, so accented and non-Latin letters are dropped. If the result is empty or only dots, the request is rejected, even when the name came from `file.file_name`: an unusable `file.file_name` is not replaced by `chatgpt-media`. Pass an ASCII `fileName` to avoid this.
[`get-post`](./get-post.md) returns the cleaned name as `media[].sourceFileName`. The stored object name and the media URL end with it after a unique prefix, so two files with the same name never overwrite each other. Social networks may rename the file again when they re-host it.
## What happens
1. **Ownership and state checks** run before anything is downloaded. A post that doesn't exist or belongs to another user returns `404`. A published, failed or partially published post returns `400 POST_NOT_EDITABLE`. A post that is publishing, or that already has a live platform post or one with an unknown publish outcome, returns `409 POST_PUBLISH_IN_PROGRESS`.
2. **Rate limit.** Each attempt that gets this far uses one URL from the allowance it shares with `mediaUrls`: 60 URLs per fixed one-hour window. Idempotent replays don't count. Going over it returns `429 MEDIA_URL_RATE_LIMITED` with `Retry-After`.
3. **Download and validation.** The same pipeline as `mediaUrls`: redirects are followed with the same host checks, the type is detected from the bytes, and the file is probed. Accepted formats: JPEG, PNG, GIF, WebP, TIFF and AVIF images up to 25 MB, and MP4, MOV and WebM videos up to 150 MB. Anything else fails without changing the post.
4. **Attach.** The file is appended to the post's existing media with status `ready`, and the post's status is set to `draft`. Publora keeps its own copy, so the temporary download URL isn't needed afterwards.
As with any other media, platform rules such as media count, format and duration for each target are checked when you schedule the post.
## Idempotency
Send an `Idempotency-Key` header whose value stays the same across retries of one attachment. Publora recognises a retry by the post ID, `file_id` and the final file name. `download_url` and `mime_type` are left out, so a retry with a refreshed temporary URL counts as the same attachment.
| Situation | Result |
|---|---|
| Same key, same post, same `file_id` and file name, even with a new `download_url` | The first response is **replayed**. The file is attached only once. |
| Same key, but a different post, `file_id` or file name | `422` `IDEMPOTENCY_KEY_CONFLICT` |
| Same key while the first request is still running | `409` `IDEMPOTENCY_IN_FLIGHT` |
| Same key after the download failed | Processed again. A failed download frees the key, so retry with a fresh file reference. |
| No key | Every call attaches another copy of the file. |
Keys are scoped to the acting user and kept for **24 hours**. A replay returns the earlier result even if you have since removed the file from the post; to attach the same file again within that window, use a new key. If you don't know whether an attachment went through after the window has passed, check [`get-post`](./get-post.md) before retrying.
## Response
The response has the same shape as [`update-post`](./update-post.md#response):
```json
{
"success": true,
"message": "Post updated successfully",
"scheduledTime": null,
"postGroup": {
"_id": "507f1f77bcf86cd799439011",
"status": "draft",
"content": "Our spring collection is here.",
"platforms": ["linkedin-ABC123"]
}
}
```
`postGroup.status` is always `draft`. A post that was scheduled keeps its stored `scheduledTime` as a draft, so the top-level `scheduledTime` and `postGroup.scheduledTime` can be non-null. Unlike `get-upload-url`, this endpoint returns no `postGroupDemoted` flag and sends no [`post.demoted`](./webhooks.md) webhook. `postGroup.status` is the signal.
The response does not include the new media ID. To see the attachment, call [`get-post`](./get-post.md). Its [`media` array](./get-post.md#media-inventory-media) lists the file with `status: "ready"`:
```json
{
"mediaId": "6a0000000000000000000099",
"sourceFileName": "spring-launch-banner.png",
"fileName": "images/1790000000000-0-1a2b3c4d-spring-launch-banner.png",
"type": "image",
"mimeType": "image/png",
"status": "ready",
"failureReason": null,
"url": "https://media.publora.com/images/1790000000000-0-1a2b3c4d-spring-launch-banner.png"
}
```
## Examples
### cURL
```bash
POST_GROUP_ID="507f1f77bcf86cd799439011"
curl -sS -X POST "https://api.publora.com/api/v1/attach-media/$POST_GROUP_ID" \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: attach-$POST_GROUP_ID-file-abc123" \
-d '{
"file": {
"download_url": "https://files.example.com/download/abc123?signature=TEMPORARY",
"file_id": "file-abc123",
"mime_type": "image/png",
"file_name": "image.png"
},
"fileName": "spring-launch-banner.png"
}'
```
Then, when the post should go out, schedule it:
```bash
FUTURE_TIME=$(date -u -v+1H +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null || date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%S.000Z)
curl -sS -X PUT "https://api.publora.com/api/v1/update-post/$POST_GROUP_ID" \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: schedule-$POST_GROUP_ID-$FUTURE_TIME" \
-d "{\"status\":\"scheduled\",\"scheduledTime\":\"$FUTURE_TIME\"}"
```
### JavaScript (fetch)
```javascript
const postGroupId = '507f1f77bcf86cd799439011';
const file = {
download_url: 'https://files.example.com/download/abc123?signature=TEMPORARY',
file_id: 'file-abc123',
mime_type: 'image/png'
};
const response = await fetch(`https://api.publora.com/api/v1/attach-media/${postGroupId}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': process.env.PUBLORA_API_KEY,
// One key per logical attachment; reuse it for every retry.
'Idempotency-Key': `attach-${postGroupId}-${file.file_id}`
},
body: JSON.stringify({ file, fileName: 'spring-launch-banner.png' })
});
const result = await response.json();
if (!response.ok) {
// mediaResults explains a failed download, e.g. MEDIA_URL_HTTP_ERROR for an expired URL.
throw new Error(`${result.code || result.error}: ${JSON.stringify(result.mediaResults || [])}`);
}
console.log(result.postGroup.status); // "draft"
```
### Python (requests)
```python
import os
import requests
post_group_id = "507f1f77bcf86cd799439011"
file_ref = {
"download_url": "https://files.example.com/download/abc123?signature=TEMPORARY",
"file_id": "file-abc123",
}
response = requests.post(
f"https://api.publora.com/api/v1/attach-media/{post_group_id}",
headers={
"x-publora-key": os.environ["PUBLORA_API_KEY"],
"Idempotency-Key": f"attach-{post_group_id}-{file_ref['file_id']}",
},
json={"file": file_ref, "fileName": "spring-launch-banner.png"},
)
response.raise_for_status()
print(response.json()["postGroup"]["status"]) # draft
```
## MCP tool
The MCP `attach_media` tool takes `postGroupId`, `file`, an optional `fileName` and an optional `idempotencyKey`. It calls this endpoint and, when you don't pass a key, derives one from the post ID and `file_id`. The tool declares `_meta["openai/fileParams"]: ["file"]`, so ChatGPT supplies `download_url` and `file_id` itself. See the [MCP Tools Reference](../mcp/tools-reference.md).
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"Only file and fileName are accepted; attaching media leaves the post in draft"` — code `INVALID_MEDIA_FILE` | The body has another top-level field, such as `status` or `scheduledTime`. Nothing was downloaded. |
| 400 | `"file must be a file object with download_url and file_id, not a local path or base64 string"`, `"file.download_url must be a non-empty string"`, `"file only accepts download_url, file_id, mime_type and file_name"` and similar — code `INVALID_MEDIA_FILE` | `file` is missing, isn't an object, lacks a required field, has an unknown key or a non-string value, or `file_id` is over 512 characters |
| 400 | `"Only https:// media URLs are allowed (got http://)"` and other URL-check messages — code `INVALID_MEDIA_FILE` | `download_url` is not a valid URL, is not HTTPS, embeds credentials, uses a non-443 port, or its host is a private or loopback IP address or a `localhost`, `.local` or `.internal` name. Nothing was downloaded. A host name that only resolves to a private address is refused during the download instead, in `mediaResults[]`. |
| 400 | `"fileName must be a non-empty string of at most 255 characters"` / `"fileName must contain a valid file name"` — code `INVALID_MEDIA_FILE` | `fileName` is `null` or not a string, or the name used (`fileName`, else `file.file_name`) is over 255 characters or is empty or only dots after cleaning. An unusable `file.file_name` is not replaced by `chatgpt-media`. |
| 400 | `"Invalid post group ID"` | `postGroupId` is not a valid post ID. Use the 24-character ID from `create-post` or `list-posts`. |
| 400 | `"Media ingestion failed"` with `mediaResults[]` | Download or validation failed. The entry for the URL has `ok: false`, a `code` such as `MEDIA_URL_HTTP_ERROR` (often an expired temporary URL), `MEDIA_URL_TOO_LARGE` or `MEDIA_URL_UNSUPPORTED_FORMAT`, and an `error` message. Nothing was attached. See [`mediaUrls` per-URL codes](../guides/error-codes.md#mediaurls-per-url-codes). |
| 400 | `"Cannot update post: post is currently in {status} status"` — code `POST_NOT_EDITABLE` | The post is published, failed or partially published |
| 400 | `"Invalid platform connection(s): …"` — code `INVALID_PLATFORM_CONNECTION` | The post targets a YouTube connection that is no longer yours. YouTube targets are re-checked when the attachment is saved, and the downloaded file is discarded. The response includes `invalidPlatforms`. |
| 401 | `"API key is required"` / `"Invalid API key"` | Missing or invalid `x-publora-key` |
| 403 | `"API access is not enabled for this account"` / `"MCP access is not enabled for this account"` | The account lacks API access, or MCP access when called through MCP |
| 404 | `"Post group not found"` | No such post, or it belongs to another user |
| 409 | `"Publishing has already started; media cannot be changed. Duplicate the post to recover its content."` — code `POST_PUBLISH_IN_PROGRESS` | The post is publishing, or one of its platform posts is publishing, already live or has an unknown publish outcome. Re-read it with [`get-post`](./get-post.md) before retrying. |
| 409 | code `POST_GROUP_VERSION_CONFLICT` | Another write finished first, and this request changed nothing. Re-read the post and retry. |
| 409 | code `IDEMPOTENCY_IN_FLIGHT` | A request with the same `Idempotency-Key` is still running. Retry the same request shortly. |
| 422 | code `IDEMPOTENCY_KEY_CONFLICT` | The key was already used for a different post, `file_id` or file name |
| 429 | code `MEDIA_URL_RATE_LIMITED` | Over the limit of 60 media URLs per hour. Wait for `Retry-After` seconds. |
| 500 | `"Failed to update post"` | Internal server error |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/upload-instagram-cover
# Upload Instagram Cover
Upload a custom cover image for an Instagram **Reel**. Publora hosts the image and returns a public URL you set as `platformSettings.instagram.coverUrl`. This is the file-upload alternative to hosting the JPEG yourself — see [Instagram → Platform-Specific Settings](../platforms/instagram.md#platform-specific-settings) for the `coverUrl` field.
The uploaded image is stored as a **JPEG** regardless of input format (Instagram accepts only JPEG for Reel covers); PNG and WebP are transcoded server-side, with transparency flattened onto a white background.
## Endpoint
```
POST https://api.publora.com/api/v1/upload-instagram-cover
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `multipart/form-data` |
## Request Body
Sent as `multipart/form-data`:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cover` | file | Yes | The cover image. JPEG, PNG, or WebP, **8 MB max**. PNG/WebP are converted to JPEG. |
| `postGroupId` | string | Yes | The post group this cover belongs to. Must be an editable post (`draft` or `scheduled`) that you own. |
The target post group must be in `draft` or `scheduled` status and not currently publishing. A cover cannot be uploaded for a post that is already published, failed, or mid-publish.
## Response
```json
{
"success": true,
"cover": {
"mediaId": "665f8a1b2c3d4e5f6a7b8c9d",
"url": "https://media.publora.com/images/665f...-reel-cover.jpg"
},
"message": "Set platformSettings.instagram.coverUrl to cover.url via /update-post to use this image as the Reels cover."
}
```
| Field | Description |
|-------|-------------|
| `success` | `true` when the cover was uploaded and stored. |
| `cover.mediaId` | The unique ID of the created cover media record. |
| `cover.url` | The public JPEG URL. Set this as `platformSettings.instagram.coverUrl` via [update-post](update-post.md). |
| `message` | Reminder of the next step. |
> **Two-step flow:** uploading the cover does **not** attach it to the post by itself. After a successful upload, call [`PUT /update-post/{postGroupId}`](update-post.md) with `platformSettings.instagram.coverUrl` set to the returned `cover.url`. Deleting that media (or clearing `coverUrl`) reverts the Reel to the automatic/frame-based cover.
## Usage
### cURL
```bash
# 1. Upload the cover image
COVER_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/upload-instagram-cover \
-H "x-publora-key: $PUBLORA_API_KEY" \
-F "cover=@./reel-cover.png" \
-F "postGroupId=507f1f77bcf86cd799439011")
COVER_URL=$(echo "$COVER_RESPONSE" | jq -r '.cover.url')
# 2. Attach it to the Reel
curl -X PUT https://api.publora.com/api/v1/update-post/507f1f77bcf86cd799439011 \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"platformSettings\": {
\"instagram\": { \"coverUrl\": \"$COVER_URL\" }
}
}"
```
### JavaScript (fetch)
```javascript
// 1. Upload the cover image
const form = new FormData();
form.append('cover', coverFile); // a File/Blob (JPEG, PNG, or WebP, <= 8 MB)
form.append('postGroupId', '507f1f77bcf86cd799439011');
const uploadRes = await fetch(
'https://api.publora.com/api/v1/upload-instagram-cover',
{
method: 'POST',
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY },
body: form, // do NOT set Content-Type — fetch sets the multipart boundary
}
);
const { cover } = await uploadRes.json();
// 2. Attach it to the Reel
await fetch(
'https://api.publora.com/api/v1/update-post/507f1f77bcf86cd799439011',
{
method: 'PUT',
headers: {
'x-publora-key': process.env.PUBLORA_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
platformSettings: { instagram: { coverUrl: cover.url } },
}),
}
);
```
### Python (requests)
```python
import requests
BASE_URL = "https://api.publora.com/api/v1"
headers = {"x-publora-key": PUBLORA_API_KEY}
post_group_id = "507f1f77bcf86cd799439011"
# 1. Upload the cover image
with open("reel-cover.png", "rb") as f:
upload = requests.post(
f"{BASE_URL}/upload-instagram-cover",
headers=headers,
files={"cover": ("reel-cover.png", f, "image/png")},
data={"postGroupId": post_group_id},
)
cover_url = upload.json()["cover"]["url"]
# 2. Attach it to the Reel
requests.put(
f"{BASE_URL}/update-post/{post_group_id}",
headers={**headers, "Content-Type": "application/json"},
json={"platformSettings": {"instagram": {"coverUrl": cover_url}}},
)
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| `400` | `postGroupId is required` | The `postGroupId` field was missing. |
| `400` | `Invalid postGroupId` | The `postGroupId` is not a valid ID. |
| `400` | `cover file is required` | No `cover` file part was sent. |
| `400` | `Instagram covers must be JPEG, PNG, or WebP images` | Unsupported file type. |
| `400` | `Instagram covers must be 8 MB or smaller` | The uploaded file exceeds 8 MB. |
| `400` | `Instagram cover exceeds 8 MB after JPEG conversion; use a smaller image` | A dense PNG/WebP expanded past 8 MB when converted to JPEG. |
| `400` | `Cannot upload Instagram cover for a non-editable post` | The post is published or failed. |
| `404` | `Post group not found` | No such post group for this account. |
| `409` | `Post group is currently being published; cannot upload Instagram cover. Retry once publishing completes.` | The scheduler is mid-publish. |
## Notes
- **Reels only.** A cover applies to videos published as Reels (`videoType: "REELS"`, the default). It is ignored for Stories and image posts.
- **Precedence.** A cover set via `coverUrl` takes precedence over frame-based cover selection (`videoTimestamp`).
- **Cleanup.** Replacing or clearing the cover, or deleting the post, removes the stored cover file automatically.
---
> Source: https://docs.publora.com/endpoints/upload-youtube-thumbnail
# Upload YouTube Thumbnail
Upload a custom thumbnail for a YouTube video post. Publora stores the image as tracked media and returns a `mediaId` + `url` that you then attach via `platformSettings.youtube.thumbnail` on [update-post](update-post.md). See [YouTube → Custom Thumbnail](../platforms/youtube.md#custom-thumbnail) for the full workflow and publish-time behavior.
A thumbnail **cannot** be set on `create-post` — the upload requires an existing `postGroupId`, so the post (draft or scheduled) must exist first.
## Endpoint
```
POST https://api.publora.com/api/v1/upload-youtube-thumbnail
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `multipart/form-data` |
## Request Body
Sent as `multipart/form-data`:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `thumbnail` | file | Yes | The thumbnail image. **JPEG or PNG**, **2 MB max**, **min 640×360 px** (1280×720 / 16:9 recommended). |
| `postGroupId` | string | Yes | The post group to attach the thumbnail to. Must be an editable post (`draft` or `scheduled`) that you own and is not currently publishing. |
## Response
```json
{
"success": true,
"thumbnail": {
"mediaId": "665f8a1b2c3d4e5f6a7b8c9d",
"url": "https://media.publora.com/images/665f...-thumb.jpg"
}
}
```
| Field | Description |
|-------|-------------|
| `success` | `true` when the thumbnail was uploaded and stored. |
| `thumbnail.mediaId` | ID of the created thumbnail media record. Pass as `platformSettings.youtube.thumbnail.mediaId`. |
| `thumbnail.url` | Public URL of the stored thumbnail. Pass as `platformSettings.youtube.thumbnail.url`. |
> **Two-step flow:** uploading does **not** attach the thumbnail by itself. After a successful upload, call [`PUT /update-post/{postGroupId}`](update-post.md) with `platformSettings.youtube.thumbnail` set to the returned `mediaId` and `url`. Only Publora-tracked media from this endpoint is accepted — arbitrary URLs are rejected. It is applied best-effort after the video processes; if YouTube rejects it (unverified channel, invalid image) the video still publishes without it.
## Usage
### cURL
```bash
# 1. Create the draft post (returns postGroupId)
POST_ID=$(curl -s -X POST https://api.publora.com/api/v1/create-post \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content":"My video description","platforms":["youtube-UCxxxxxxxx"]}' \
| jq -r '.postGroupId')
# 2. Upload the thumbnail against that postGroupId
THUMB=$(curl -s -X POST https://api.publora.com/api/v1/upload-youtube-thumbnail \
-H "x-publora-key: $PUBLORA_API_KEY" \
-F "thumbnail=@./thumb.jpg" \
-F "postGroupId=$POST_ID")
MEDIA_ID=$(echo "$THUMB" | jq -r '.thumbnail.mediaId')
THUMB_URL=$(echo "$THUMB" | jq -r '.thumbnail.url')
# 3. Attach it via update-post (then schedule as usual)
curl -X PUT https://api.publora.com/api/v1/update-post/$POST_ID \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"platformSettings\":{\"youtube\":{\"thumbnail\":{\"mediaId\":\"$MEDIA_ID\",\"url\":\"$THUMB_URL\"}}}}"
```
### JavaScript (fetch)
```javascript
// postGroupId from a prior create-post call
const form = new FormData();
form.append('thumbnail', thumbFile); // File/Blob — JPEG or PNG, <= 2 MB, >= 640x360
form.append('postGroupId', postGroupId);
const res = await fetch('https://api.publora.com/api/v1/upload-youtube-thumbnail', {
method: 'POST',
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }, // do NOT set Content-Type — fetch sets the multipart boundary
body: form,
});
const { thumbnail } = await res.json();
// Attach it, then schedule
await fetch(`https://api.publora.com/api/v1/update-post/${postGroupId}`, {
method: 'PUT',
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ platformSettings: { youtube: { thumbnail } } }),
});
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| `400` | `postGroupId is required` | The `postGroupId` field was missing. |
| `400` | `Invalid postGroupId` | The `postGroupId` is not a valid ID. |
| `400` | `thumbnail file is required` | No `thumbnail` file part was sent. |
| `400` | `YouTube thumbnails must be JPEG or PNG images` | Unsupported file type, or the bytes aren't a valid JPEG/PNG. |
| `400` | `YouTube thumbnails must be 2 MB or smaller` | The file exceeds 2 MB. |
| `400` | `YouTube thumbnails must be at least 640x360 pixels` | The image is below the minimum dimensions. |
| `400` | `Cannot upload YouTube thumbnail for a non-editable post` | The post is published or failed. |
| `404` | `Post group not found` | No such post group for this account. |
| `409` | `Post group is currently being published; cannot upload YouTube thumbnail. Retry once publishing completes.` | The scheduler is mid-publish. |
| `500` | `Failed to upload YouTube thumbnail` | Storage or server error. |
## Notes
- **Clear a thumbnail** by sending `platformSettings.youtube.thumbnail` with an empty `url` via [update-post](update-post.md).
- **Verified channel required** for YouTube to accept a custom thumbnail; otherwise it is skipped at publish (the video still goes out).
- **Cleanup.** Replacing the thumbnail or deleting the post removes the stored file automatically.
---
> Source: https://docs.publora.com/endpoints/platform-connections
# Platform Connections
List all connected social media accounts.
## Endpoint
```
GET https://api.publora.com/api/v1/platform-connections
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `mcp`). Used for MCP access gating. |
> **Browser usage:** CORS permits the Publora headers above, but only requests from origins in Publora's deployment allowlist are accepted. An arbitrary integrator origin can still fail preflight. Keep the API key on a backend or serverless function; exposing it in client-side JavaScript leaks the credential.
## Response
```json
{
"success": true,
"connections": [
{
"platformId": "twitter-123456789",
"username": "yourhandle",
"displayName": "Your Name",
"profileImageUrl": "https://pbs.twimg.com/profile_images/...",
"profileUrl": null,
"accessTokenExpiresAt": null,
"tokenStatus": "valid",
"connectionStatus": "active",
"tokenExpiresIn": null,
"lastSuccessfulPost": "2026-02-20T14:30:00.000Z",
"lastError": null,
"subscriptionType": "None"
},
{
"platformId": "linkedin-Tz9W5i6ZYG",
"username": "John Doe",
"displayName": "John Doe",
"profileImageUrl": "https://media.licdn.com/...",
"profileUrl": "https://linkedin.com/in/johndoe",
"accessTokenExpiresAt": "2026-05-15T10:30:00.000Z",
"tokenStatus": "valid",
"connectionStatus": "active",
"tokenExpiresIn": "82d 4h",
"lastSuccessfulPost": "2026-02-22T09:15:00.000Z",
"lastError": null,
"subscriptionType": null
},
{
"platformId": "instagram-17841412345678",
"username": "yourinstagram",
"displayName": "Your Brand",
"profileImageUrl": "https://...",
"profileUrl": null,
"accessTokenExpiresAt": "2026-02-25T08:00:00.000Z",
"tokenStatus": "expiring_soon",
"connectionStatus": "active",
"tokenExpiresIn": "2d 12h",
"lastSuccessfulPost": null,
"lastError": {
"message": "Media upload failed: Invalid image format",
"occurredAt": "2026-02-21T16:45:00.000Z"
},
"subscriptionType": null
},
{
"platformId": "youtube-UCxxxxxxxxxxxx",
"username": "Your Channel",
"displayName": null,
"profileImageUrl": "https://...",
"profileUrl": null,
"accessTokenExpiresAt": null,
"tokenStatus": "valid",
"connectionStatus": "active",
"tokenExpiresIn": null,
"lastSuccessfulPost": "2026-02-23T18:00:00.000Z",
"lastError": null,
"subscriptionType": null
},
{
"platformId": "telegram--1001234567890",
"username": null,
"displayName": "Private news",
"profileImageUrl": "https://...",
"profileUrl": null,
"accessTokenExpiresAt": null,
"tokenStatus": "unknown",
"connectionStatus": "active",
"tokenExpiresIn": null,
"lastSuccessfulPost": "2026-02-24T08:00:00.000Z",
"lastError": null,
"subscriptionType": null
}
]
}
```
The YouTube entry above is healthy: `accessTokenExpiresAt` is `null` because there is no authoritative expiry date to report, not because anything is wrong. In the Telegram entry, a private channel, `tokenStatus` is `unknown` only because Telegram stores no expiry date; its `connectionStatus` is `active`. Read `connectionStatus` to decide whether a connection can publish.
## Connection Fields
| Field | Type | Description |
|-------|------|-------------|
| `platformId` | string | Unique ID in format `platform-id`. Use this in the `platforms` array when creating posts. |
| `username` | string/null | Platform username or handle. Note: the stored username may or may not include a `@` prefix depending on what was saved during OAuth. `null` for a Telegram channel without a public username (a private channel connected by chat ID or message link); `displayName` then holds the channel title. |
| `displayName` | string/null | Display name on the platform. Returns `null` if not set during OAuth. |
| `profileImageUrl` | string/null | Profile image URL. Returns `null` if not available. |
| `profileUrl` | string/null | URL to the user's profile on the platform. Can be null if not available for the platform. |
| `accessTokenExpiresAt` | string/null | Effective credential expiry — the same date `tokenStatus` and `tokenExpiresIn` are derived from, not the raw OAuth access-token lifetime. `null` means no authoritative expiry date exists: always for YouTube (Google does not publish a refresh-token lifetime), and for the platforms whose credentials do not expire on a schedule (Facebook, X/Twitter, Mastodon, Bluesky). A `null` here is not a problem — read `connectionStatus` and `tokenStatus`. |
| `tokenStatus` | string | Credential expiry health: `valid`, `expiring_soon`, `expired`, or `unknown`. Use it to warn ahead of expiry (`expiring_soon`) instead of comparing `accessTokenExpiresAt` against the clock yourself. To decide whether a connection can publish, read `connectionStatus`. See platform-specific rules below. |
| `connectionStatus` | string | `active` or `reconnect_required`: whether Publora can publish with this connection now. It is `active` when the connection is not flagged for reconnection (Publora sets this flag when Facebook, Instagram, Threads, LinkedIn or TikTok rejects the stored credential, and when X or YouTube reports the account suspended; on X, Bluesky, Mastodon and Telegram a rejected credential shows only in `lastError`), its credentials are stored, and its access token has not expired or can be renewed while publishing. **Read this to decide whether to prompt a reconnect.** It is computed from stored data without calling the platform; use [`test-connection`](test-connection.md) for a live check. |
| `tokenExpiresIn` | string/null | Human-readable time until expiration. Possible formats: `"7d 3h"` (days and hours), `"5h"` (hours only, when less than one day remains), `"< 1h"` (less than one hour remaining), `"expired"` (token already expired), or `null` (no expiration). |
| `lastSuccessfulPost` | string/null | Timestamp of last successful post to this platform |
| `lastError` | object/null | Last error that occurred when posting to this platform. When present, contains: `message` (string — error description) and `occurredAt` (string — ISO 8601 timestamp of when the error occurred). |
| `subscriptionType` | string/null | X only: the last tier Publora read from X, `"None"`, `"Basic"`, `"Premium"`, or `"PremiumPlus"`. It is fetched at connect time and re-checked when publishing to X, at most once every 24 hours. `"Premium"` and `"PremiumPlus"` raise the X length limit from 280 to 25,000 characters. `null` on other platforms, and on X until a fetch succeeds. |
## Token Status Values
| Status | Meaning |
|--------|---------|
| `valid` | Credential is usable. Facebook, Twitter/X, and Mastodon are treated as non-expiring. **YouTube is always `valid`** unless the connection has been flagged for reconnection — its access token is refreshed on demand before each publish, and Google publishes no refresh-token lifetime, so there is no expiry date to report. TikTok is `valid` while its refresh token is at least 30 days away. For Bluesky, this endpoint's projected connection data marks a stored username as `valid`; it does not re-check the app password. |
| `expiring_soon` | TikTok refresh token expires in under 30 days, or another OAuth platform's access token expires in under 7 days |
| `expired` | Reconnect required. Either the effective expiry has passed, or Publora flagged the connection for reconnection after Facebook, Instagram, Threads, LinkedIn or TikTok rejected its credential — the second case also covers Facebook, whose credentials never expire on a schedule, and in that case `accessTokenExpiresAt` may still be `null` or in the future. |
| `unknown` | Stored expiry data is missing or malformed. Telegram connections store no expiry date, so they always report `unknown`; read their `connectionStatus`. For Bluesky in this endpoint, it means the projected connection has no username. A missing TikTok `refreshTokenExpiresAt` is `valid`, not `unknown`. |
### `connectionStatus` and `tokenStatus`
`connectionStatus` answers one question: can Publora publish with this connection now? `tokenStatus` describes credential expiry and warns in advance with `expiring_soon`. They agree for connections in a normal state, with two systematic differences:
- **Telegram** stores no expiry date, so `tokenStatus` is always `unknown`. Publora never flags Telegram connections, so `connectionStatus` stays `active`; use [`test-connection`](test-connection.md#telegram-connections) to check the bot's channel rights.
- **Suspended accounts:** when X or YouTube reports the account suspended during a publish, `connectionStatus` becomes `reconnect_required` while `tokenStatus` stays `valid`. `lastError` carries the suspension message.
Incomplete stored data can also make them differ. Prompt a reconnect on `connectionStatus: "reconnect_required"`, and warn ahead of time on `tokenStatus: "expiring_soon"`.
> **Do not infer health from `accessTokenExpiresAt` yourself.** `tokenStatus` already accounts for per-platform refresh behaviour and for connections the platform has revoked. A connection can be `expired` while its date is `null` or in the future, and YouTube reports `null` while being perfectly healthy.
> **Note:** Pinterest has OAuth connection routes in the dashboard, but no `test-connection` validator is implemented. Calling `test-connection` for a Pinterest connection will return `"Unknown platform: pinterest"`. Pinterest is connect-only, so an `active` Pinterest connection is still not a publish target.
## Platform ID Format
The `platformId` follows the pattern `platform-id`:
| Platform | Example platformId |
|----------|-------------------|
| X / Twitter | `twitter-123456789` |
| LinkedIn | `linkedin-Tz9W5i6ZYG` |
| Instagram | `instagram-17841412345678` |
| Threads | `threads-17841412345678` |
| TikTok | `tiktok-7123456789` |
| YouTube | `youtube-UCxxxxxxxxxxxx` |
| Facebook | `facebook-112233445566` |
| Bluesky | `bluesky-did:plc:abc123` |
| Mastodon | `mastodon-109876543210` |
| Telegram | `telegram--1001234567890` |
## Examples
### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/platform-connections', {
headers: { 'x-publora-key': 'YOUR_API_KEY' }
});
const data = await response.json();
// Filter by platform
const twitterAccounts = data.connections.filter(c => c.platformId.startsWith('twitter-'));
const linkedinAccounts = data.connections.filter(c => c.platformId.startsWith('linkedin-'));
console.log(`Twitter accounts: ${twitterAccounts.length}`);
console.log(`LinkedIn accounts: ${linkedinAccounts.length}`);
```
### Python (requests)
```python
import requests
response = requests.get(
'https://api.publora.com/api/v1/platform-connections',
headers={'x-publora-key': 'YOUR_API_KEY'}
)
connections = response.json()['connections']
# Get all platform IDs for cross-platform posting
all_platform_ids = [c['platformId'] for c in connections]
print(f"Connected to {len(all_platform_ids)} accounts")
# Check health — read connectionStatus and tokenStatus, never compare the date yourself
for conn in connections:
if conn.get('connectionStatus') == 'reconnect_required':
print(f"⚠️ {conn['platformId']} needs reconnecting in the dashboard.")
elif conn.get('tokenStatus') == 'expiring_soon':
print(f"⏳ {conn['platformId']} expires in {conn.get('tokenExpiresIn')}")
```
### cURL
```bash
curl https://api.publora.com/api/v1/platform-connections \
-H "x-publora-key: YOUR_API_KEY"
```
### Node.js (axios)
```javascript
const axios = require('axios');
const { data } = await axios.get(
'https://api.publora.com/api/v1/platform-connections',
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
// Build a map of platform → connection IDs
const platforms = {};
for (const conn of data.connections) {
const platform = conn.platformId.split('-')[0];
if (!platforms[platform]) platforms[platform] = [];
platforms[platform].push(conn.platformId);
}
console.log(platforms);
// { twitter: ["twitter-123"], linkedin: ["linkedin-ABC"], ... }
```
### With Error Handling
```javascript
async function getConnections() {
try {
const response = await fetch('https://api.publora.com/api/v1/platform-connections', {
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
});
if (response.status === 401) {
throw new Error('Invalid API key. Check your PUBLORA_API_KEY.');
}
if (!response.ok) {
const data = await response.json();
throw new Error(data.error || `HTTP ${response.status}`);
}
const data = await response.json();
// Check health — read connectionStatus and tokenStatus, never compare the date yourself
for (const conn of data.connections) {
if (conn.connectionStatus === 'reconnect_required') {
console.warn(`⚠️ ${conn.platformId} needs reconnecting in the dashboard`);
} else if (conn.tokenStatus === 'expiring_soon') {
console.warn(`⏳ ${conn.platformId} expires in ${conn.tokenExpiresIn}`);
}
}
return data.connections;
} catch (error) {
console.error('Failed to fetch connections:', error.message);
throw error;
}
}
```
```python
import os
import requests
def get_connections():
"""Get all connected platforms with error handling and a credential health check."""
try:
response = requests.get(
'https://api.publora.com/api/v1/platform-connections',
headers={'x-publora-key': os.environ['PUBLORA_API_KEY']}
)
if response.status_code == 401:
raise ValueError('Invalid API key. Check your PUBLORA_API_KEY.')
response.raise_for_status()
data = response.json()
# Check health — read connectionStatus and tokenStatus, never compare the date yourself
for conn in data['connections']:
if conn.get('connectionStatus') == 'reconnect_required':
print(f"⚠️ {conn['platformId']} needs reconnecting in the dashboard")
elif conn.get('tokenStatus') == 'expiring_soon':
print(f"⏳ {conn['platformId']} expires in {conn.get('tokenExpiresIn')}")
return data['connections']
except requests.RequestException as e:
print(f'Failed to fetch connections: {e}')
raise
# Usage
connections = get_connections()
platform_ids = [c['platformId'] for c in connections]
print(f"Connected to {len(platform_ids)} platforms: {platform_ids}")
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 401 | `"API key is required"` | Missing `x-publora-key` header |
| 401 | `"Invalid API key"` | `x-publora-key` value is not a valid key |
| 401 | `"Invalid API key owner"` | The API key's owner account could not be found |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 403 | `"MCP access is not enabled for this account"` | MCP access is not enabled when `x-publora-client: mcp` is sent |
| 500 | `"Internal server error"` | Unexpected error in middleware |
| 500 | `"Failed to fetch platform connections"` | Server error while fetching connections |
## Connecting Accounts
Social accounts are connected via the Publora dashboard (OAuth flow). The API does not support connecting new accounts programmatically -- use the dashboard at [app.publora.com](https://app.publora.com).
### Pinterest connection limitation
Pinterest can be connected through OAuth, but it is connect-only. The scheduler has no Pinterest dispatch branch, so do not target a Pinterest connection in create/update scheduling requests.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/platform-limits
# Platform Limits
Return Publora's per-platform posting limits (character counts, image / video / document / GIF / thumbnail rules, and platform requirements) as live JSON. These are the **API-specific** limits Publora validates against before scheduling — fetch them to drive client-side validation instead of hard-coding values. For the human-readable tables and the API-vs-native-app differences, see the [Platform Limits guide](../guides/platform-limits.md).
The limits come from the shared `@publora/platform-limits` package, so this endpoint always reflects the same rules the scheduler enforces.
## Endpoint
```
GET https://api.publora.com/api/v1/platform-limits
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
No query parameters or request body.
## Response
The JSON below is abridged: only `twitter` is shown under `platforms`. The live response includes an object for every one of the 11 `supportedPlatforms` keys.
```json
{
"success": true,
"schemaVersion": 1,
"source": "@publora/platform-limits",
"packageVersion": "1.0.0",
"limitsLastUpdated": "2026-03-11",
"supportedPlatforms": ["twitter", "instagram", "threads", "tiktok", "linkedin", "youtube", "facebook", "mastodon", "bluesky", "telegram", "pinterest"],
"platforms": {
"twitter": {
"platform": "twitter",
"displayName": "Twitter/X",
"characters": { "standard": 280, "premium": 25000 },
"images": { "supported": true, "maxSizeBytes": 5242880, "maxCount": 4, "formats": ["image/jpeg", "image/png", "image/gif", "image/webp"] },
"videos": { "supported": true, "maxDurationSeconds": 140, "minDurationSeconds": 0.5, "maxSizeBytes": 536870912, "maxCount": 1, "formats": ["video/mp4", "video/quicktime"], "aspectRatioRange": { "min": 0.3333333333333333, "max": 3 } },
"requirements": { "requiresMedia": false, "requiresVideo": false, "supportsTextOnly": true, "supportsThreading": true },
"documents": null,
"gifs": null,
"thumbnails": null
}
}
}
```
| Field | Description |
|-------|-------------|
| `success` | `true` when the limits were returned. |
| `schemaVersion` | Response schema version (currently `1`); bumped on breaking shape changes. |
| `source` | Always `"@publora/platform-limits"` — the package the values come from. |
| `packageVersion` | Version of that package (e.g. `"1.0.0"`). |
| `limitsLastUpdated` | ISO date the limit values were last revised. |
| `supportedPlatforms` | Array of platform keys included in `platforms`. |
| `platforms` | Object keyed by platform. Each value carries `platform`, `displayName`, `characters`, `images`, `videos`, `requirements`, plus `documents`, `gifs`, and `thumbnails` (each `null` when the platform has no distinct spec). |
> **Pinterest is present** in `supportedPlatforms` and `platforms` as an internal reference key, but Pinterest is **not currently available** for posting — treat the other 10 platforms as active.
## Usage
### cURL
```bash
curl https://api.publora.com/api/v1/platform-limits \
-H "x-publora-key: $PUBLORA_API_KEY"
```
### JavaScript (fetch)
```javascript
const res = await fetch('https://api.publora.com/api/v1/platform-limits', {
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY },
});
const { platforms } = await res.json();
const twitterMax = platforms.twitter.characters.standard; // 280
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| `401` | `Invalid API key` | Missing or invalid `x-publora-key`. |
## Notes
- **Cache friendly.** Limits change rarely — cache the response and refresh when `limitsLastUpdated` changes rather than calling per request.
- **API limits, not native-app limits.** These reflect what the third-party APIs accept, which is often stricter than the platforms' own apps. See the [guide](../guides/platform-limits.md) for the differences.
- **Units.** `maxSizeBytes` is in bytes; durations are in seconds.
---
> Source: https://docs.publora.com/endpoints/account-context
# Account Context
Read the plan, available features, publishing quotas, schedule horizon and allowed platforms of the account behind your API key. Call it before a batch of posts and again after a quota or feature error, so your integration knows how many platform posts it can still publish and how far ahead it can schedule.
The response is a read-only, **advisory** snapshot: it reserves nothing, and every write is still checked against the limits when it is made. The MCP tool [`account_context`](../mcp/tools-reference.md#account_context) returns the same object.
## Endpoint
```
GET https://api.publora.com/api/v1/account-context
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
## Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scheduledTime` | string | No | ISO 8601 date-time with `Z` or an explicit offset, e.g. `2026-11-03T09:00:00Z` or `2026-11-03T10:00:00+01:00`. Selects the monthly quota period of a planned batch. Omit it for the current period. |
> **`scheduledTime` only selects the quota period.** A past time resolves to the current period, and `effectiveQuotaTime` in the response shows the date that was used. It does not make a past schedule valid: `create-post` and `update-post` still apply their own rules to the time you send.
## Response
```json
{
"success": true,
"context": {
"plane": "personal",
"actorUserId": "665f1c2ab3e4d5f6a7b8c9d0",
"snapshotAt": "2026-10-02T08:37:17.484Z",
"serverTime": "2026-10-02T08:37:17.484Z",
"effectiveQuotaTime": "2026-10-02T08:37:17.484Z",
"plan": { "key": "starter", "name": "Starter", "source": "starter" },
"features": {
"publishing": true,
"apiAccess": true,
"mcpAccess": true,
"analytics": false,
"mentionables": false
},
"quotas": {
"monthlyPosts": {
"metric": "posts.platform_monthly",
"scope": "account",
"usageScope": "legacy_workspace",
"unit": "platform_post",
"limit": 15,
"used": 4,
"remaining": 11,
"periodStart": "2026-10-01T00:00:00.000Z",
"periodEnd": "2026-11-01T00:00:00.000Z",
"resetAt": "2026-11-01T00:00:00.000Z",
"periodTimeZone": "UTC",
"connections": []
},
"scheduledPosts": {
"metric": "posts.scheduled_active",
"scope": "account",
"usageScope": "legacy_workspace",
"unit": "platform_post",
"limit": 3,
"used": 1,
"remaining": 2,
"resetAt": null
},
"scheduleHorizon": {
"metric": "posts.schedule_horizon_days",
"unit": "day",
"limit": 7,
"maxScheduledDate": "2026-10-09T23:59:59.999Z",
"resetAt": null
},
"connections": {
"metric": "connections.total",
"scope": "account",
"usageScope": "legacy_workspace",
"unit": "channel",
"limit": 3,
"used": 2,
"remaining": 1
}
},
"allowedPlatforms": ["threads", "bluesky", "mastodon", "tiktok", "instagram", "youtube", "linkedin", "facebook", "pinterest", "telegram"],
"advisory": true
}
}
```
This Starter account has 11 of its 15 platform posts left this month (the count starts over at `resetAt`), room for 2 more scheduled platform posts, a schedule horizon that ends on 2026-10-09, and no X (`twitter`) in `allowedPlatforms`.
### Response fields (inside `context`)
| Field | Type | Description |
|-------|------|-------------|
| `plane` / `actorUserId` | string | Always `personal`, and the ID of the user the snapshot describes |
| `snapshotAt` / `serverTime` | string | When the snapshot was taken |
| `effectiveQuotaTime` | string | The date used to select the monthly quota period |
| `plan` | object | `key`, `name` and `source` of the plan in effect |
| `features` | object | `true` or `false` for `publishing`, `apiAccess`, `mcpAccess`, `analytics` (needed by [Mastodon and Bluesky Statistics](platform-statistics.md)) and `mentionables` (needed by [LinkedIn Mentionables](linkedin-mentionables.md)) |
| `quotas.monthlyPosts` | object | Platform posts in the monthly period: `limit`, `used`, `remaining`, `periodStart`, `periodEnd`, `resetAt` (the end of the period), `periodTimeZone`, and `connections[]` for per-connection limits |
| `quotas.scheduledPosts` | object | Platform posts waiting to publish at a future time, against the plan's queue limit: `limit`, `used`, `remaining`. Posts sent with [`publishNow`](create-post.md#publish-now) are not counted. `resetAt` is `null`. |
| `quotas.scheduleHorizon` | object | `limit` in days and `maxScheduledDate`, the latest time a post can be scheduled (`null` when there is no horizon). `resetAt` is `null`. |
| `quotas.connections` | object | Connected channels: `limit`, `used`, `remaining` |
| `metric`, `scope`, `usageScope`, `unit` | string | Identify each quota. `unit` is `platform_post`, `day` or `channel`; `scope` is `account` (one shared limit) or `connection` (a limit for each connection) |
| `allowedPlatforms` | string[]/null | Platform types the plan allows; `null` means all platforms |
| `advisory` | boolean | Always `true`: the snapshot reserves nothing |
> **Units are platform posts.** A post to three platforms uses three from `monthlyPosts`, and three from `scheduledPosts` while it waits to publish. `limit: null` means unlimited.
> **Per-connection limits.** When `quotas.monthlyPosts.scope` is `"connection"`, the limit applies to each connection separately. Read `quotas.monthlyPosts.connections[]`: each entry has `platformSelection` (the connection ID you pass to `create-post`), `used`, `limit` and `remaining`. The aggregate `remaining` is `null` in that case, which does not mean unlimited.
## Examples
### cURL
```bash
curl https://api.publora.com/api/v1/account-context \
-H "x-publora-key: YOUR_API_KEY"
# Quota period of a batch planned for November
curl "https://api.publora.com/api/v1/account-context?scheduledTime=2026-11-03T09:00:00Z" \
-H "x-publora-key: YOUR_API_KEY"
```
### JavaScript (fetch)
```javascript
const res = await fetch('https://api.publora.com/api/v1/account-context', {
headers: { 'x-publora-key': 'YOUR_API_KEY' }
});
const { context } = await res.json();
const { remaining, limit } = context.quotas.monthlyPosts;
console.log(limit === null ? 'Unlimited posts' : `${remaining} of ${limit} platform posts left`);
```
### Python (requests)
```python
import requests
res = requests.get(
'https://api.publora.com/api/v1/account-context',
headers={'x-publora-key': 'YOUR_API_KEY'},
params={'scheduledTime': '2026-11-03T09:00:00Z'},
)
context = res.json()['context']
print(context['plan']['name'], context['quotas']['scheduleHorizon']['maxScheduledDate'])
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"scheduledTime must be a valid ISO date-time"` | `code: "INVALID_SCHEDULED_TIME"`, `retryable: false`, `nextAction: "CHANGE_SCHEDULE"`. The value has no `Z` or offset, or is an impossible date such as `2026-02-30`. |
| 401 | `"API key is required"` / `"Invalid API key"` | Missing or invalid `x-publora-key` |
| 403 | `"API access is not enabled for this account"` | The plan has no API access |
| 500 | `"Failed to read account context"` | Internal server error; retry later |
## Notes
- **A snapshot, not a reservation.** Every write is checked again when it is made, so a write can still hit a limit if the quota was used in the meantime.
- **Same numbers as enforcement.** The quotas use the same counting as `create-post` and `update-post`, including the [Publish Now](create-post.md#publish-now) exemption from the scheduled-post queue.
---
> Source: https://docs.publora.com/endpoints/list-posts
# List Posts
Retrieve a paginated list of all your scheduled, draft, published, and failed posts.
## Endpoint
```
GET https://api.publora.com/api/v1/list-posts
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `mcp` for MCP integrations). Affects which access controls are checked. |
## Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | number | `1` | Page number (1-indexed). Values less than 1 are silently clamped to 1. |
| `limit` | number | `20` | Items per page. Values are clamped to the range 1–100, with falsy values (0, NaN, empty) defaulting to 20. |
| `status` | string | all | Filter by status: `draft`, `scheduled`, `published`, `failed`, `partially_published`. Note: `pending` and `processing` are valid per-platform ScheduledPost statuses (not ScheduledPostGroup statuses) and cannot be used as filter values here. |
| `platform` | string | all | Filter by platform: `twitter`, `linkedin`, `instagram`, `threads`, `tiktok`, `youtube`, `facebook`, `bluesky`, `mastodon`, `telegram`, `pinterest`. Internally, the filter applies a case-insensitive regex against stored compound platform IDs (e.g., `twitter-123`). The filter uses a regex anchored to the start of the string (`^platform-`), so passing a bare platform name like `twitter` matches all Twitter connections. Passing a full compound ID like `twitter-123` would generate regex `^twitter-123-` which requires a trailing dash and will likely return no results — use bare platform names instead. No validation is performed on the value — invalid names (e.g., `?platform=foobar`) silently return an empty result set rather than an error. |
| `sortBy` | string | `createdAt` | Sort field: `createdAt`, `scheduledTime`, `updatedAt` |
| `sortOrder` | string | `desc` | Sort order: `asc` or `desc`. Invalid values silently default to `desc`. |
| `fromDate` | string | - | Filter posts scheduled on or after this date (inclusive, uses `$gte`). Accepts any date string parseable by JavaScript's `new Date()`, though ISO 8601 is recommended for consistency. Filters on `scheduledTime` only — drafts without a `scheduledTime` are excluded when this parameter is used. |
| `toDate` | string | - | Filter posts scheduled on or before this date (inclusive, uses `$lte`). Accepts any date string parseable by JavaScript's `new Date()`, though ISO 8601 is recommended for consistency. Filters on `scheduledTime` only — drafts without a `scheduledTime` are excluded when this parameter is used. |
## Response
```json
{
"success": true,
"posts": [
{
"postGroupId": "507f1f77bcf86cd799439011",
"content": "Excited to share our new product launch!",
"status": "scheduled",
"scheduledTime": "2026-03-15T14:30:00.000Z",
"createdAt": "2026-03-10T09:00:00.000Z",
"updatedAt": "2026-03-10T09:00:00.000Z",
"platforms": [
{
"platformId": "twitter-123456789",
"platform": "twitter",
"status": "scheduled"
},
{
"platformId": "linkedin-ABC123",
"platform": "linkedin",
"status": "scheduled"
}
],
"mediaUrls": ["https://your-media-url.example.com/images/abc123.jpg"]
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalItems": 47,
"totalPages": 3,
"hasNextPage": true,
"hasPrevPage": false
}
}
```
> **Note:** The `platformId` field in list-posts uses a compound format (e.g., `"twitter-123456789"`), combining the platform name with the raw ID. This differs from the [get-post](./get-post) endpoint, which returns only the raw platform ID (e.g., `"123456789"`).
> **Note:** Filtering by `?status=published` returns only posts where all platforms published successfully. It does **not** include `partially_published` posts. This is an exact match and differs from dashboard behavior, which may group these statuses together.
## Pagination Fields
| Field | Type | Description |
|-------|------|-------------|
| `page` | number | Current page number |
| `limit` | number | Items per page |
| `totalItems` | number | Total number of posts matching filters |
| `totalPages` | number | Total number of pages |
| `hasNextPage` | boolean | Whether more pages exist after current |
| `hasPrevPage` | boolean | Whether pages exist before current |
## Examples
### JavaScript - Fetch All Scheduled Posts with Pagination
```javascript
async function fetchAllScheduledPosts(apiKey) {
const posts = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const url = new URL('https://api.publora.com/api/v1/list-posts');
url.searchParams.set('page', page);
url.searchParams.set('limit', 100);
url.searchParams.set('status', 'scheduled');
url.searchParams.set('sortBy', 'scheduledTime');
url.searchParams.set('sortOrder', 'asc');
const response = await fetch(url, {
headers: { 'x-publora-key': apiKey }
});
const data = await response.json();
posts.push(...data.posts);
hasMore = data.pagination.hasNextPage;
page++;
console.log(`Fetched page ${data.pagination.page} of ${data.pagination.totalPages}`);
}
console.log(`Total scheduled posts: ${posts.length}`);
return posts;
}
// Usage
const scheduledPosts = await fetchAllScheduledPosts('YOUR_API_KEY');
```
### JavaScript - Paginated List with UI Controls
```javascript
class PostListPaginator {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://api.publora.com/api/v1/list-posts';
this.currentPage = 1;
this.limit = 20;
this.filters = {};
}
setFilters({ status, platform, fromDate, toDate }) {
this.filters = { status, platform, fromDate, toDate };
this.currentPage = 1; // Reset to first page when filters change
}
async fetchPage(page = this.currentPage) {
const url = new URL(this.baseUrl);
url.searchParams.set('page', page);
url.searchParams.set('limit', this.limit);
// Apply filters
if (this.filters.status) url.searchParams.set('status', this.filters.status);
if (this.filters.platform) url.searchParams.set('platform', this.filters.platform);
if (this.filters.fromDate) url.searchParams.set('fromDate', this.filters.fromDate);
if (this.filters.toDate) url.searchParams.set('toDate', this.filters.toDate);
const response = await fetch(url, {
headers: { 'x-publora-key': this.apiKey }
});
const data = await response.json();
this.currentPage = data.pagination.page;
return data;
}
async nextPage() {
return this.fetchPage(this.currentPage + 1);
}
async prevPage() {
return this.fetchPage(Math.max(1, this.currentPage - 1));
}
async goToPage(page) {
return this.fetchPage(page);
}
}
// Usage
const paginator = new PostListPaginator('YOUR_API_KEY');
// Get first page of scheduled posts
paginator.setFilters({ status: 'scheduled' });
const firstPage = await paginator.fetchPage();
console.log(`Showing ${firstPage.posts.length} of ${firstPage.pagination.totalItems} posts`);
// Navigate pages
if (firstPage.pagination.hasNextPage) {
const secondPage = await paginator.nextPage();
}
```
### Python - Fetch All Posts with Pagination
```python
import requests
from typing import Generator, Dict, Any, Optional
def fetch_posts_paginated(
api_key: str,
status: Optional[str] = None,
platform: Optional[str] = None,
limit: int = 100
) -> Generator[Dict[str, Any], None, None]:
"""
Generator that yields posts one by one, handling pagination automatically.
Args:
api_key: Your Publora API key
status: Filter by status (draft, scheduled, published, failed, partially_published)
platform: Filter by platform (twitter, linkedin, etc.)
limit: Items per page (max 100)
Yields:
Individual post objects
"""
base_url = 'https://api.publora.com/api/v1/list-posts'
headers = {'x-publora-key': api_key}
page = 1
while True:
params = {
'page': page,
'limit': limit,
'sortBy': 'scheduledTime',
'sortOrder': 'asc'
}
if status:
params['status'] = status
if platform:
params['platform'] = platform
response = requests.get(base_url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
for post in data['posts']:
yield post
if not data['pagination']['hasNextPage']:
break
page += 1
def fetch_all_scheduled_posts(api_key: str) -> list:
"""Fetch all scheduled posts into a list."""
posts = list(fetch_posts_paginated(api_key, status='scheduled'))
print(f"Fetched {len(posts)} scheduled posts")
return posts
# Usage
api_key = 'YOUR_API_KEY'
# Iterate through all scheduled posts
for post in fetch_posts_paginated(api_key, status='scheduled'):
print(f"{post['postGroupId']}: {post['content'][:50]}...")
print(f" Scheduled for: {post['scheduledTime']}")
print(f" Platforms: {[p['platform'] for p in post['platforms']]}")
# Or fetch all at once
all_posts = fetch_all_scheduled_posts(api_key)
```
### Python - Filter Posts by Date Range
```python
import requests
from datetime import datetime, timedelta, timezone
def get_posts_for_week(api_key: str, start_date: datetime) -> list:
"""Get all posts scheduled for a specific week."""
end_date = start_date + timedelta(days=7)
params = {
'status': 'scheduled',
'fromDate': start_date.isoformat(),
'toDate': end_date.isoformat(),
'sortBy': 'scheduledTime',
'sortOrder': 'asc',
'limit': 100
}
response = requests.get(
'https://api.publora.com/api/v1/list-posts',
headers={'x-publora-key': api_key},
params=params
)
return response.json()['posts']
# Usage: Get posts scheduled for next week
next_monday = datetime.now(timezone.utc).replace(
hour=0, minute=0, second=0, microsecond=0
)
# Adjust to next Monday
days_until_monday = (7 - next_monday.weekday()) % 7
next_monday += timedelta(days=days_until_monday)
posts = get_posts_for_week('YOUR_API_KEY', next_monday)
print(f"Posts scheduled for next week: {len(posts)}")
```
### Node.js (axios) - Paginated Fetch with Async Iterator
```javascript
const axios = require('axios');
async function* paginatedPosts(apiKey, options = {}) {
const { status, platform, limit = 100 } = options;
let page = 1;
let hasMore = true;
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: { 'x-publora-key': apiKey }
});
while (hasMore) {
const params = { page, limit, sortBy: 'scheduledTime', sortOrder: 'asc' };
if (status) params.status = status;
if (platform) params.platform = platform;
const { data } = await api.get('/list-posts', { params });
for (const post of data.posts) {
yield post;
}
hasMore = data.pagination.hasNextPage;
page++;
}
}
// Usage
(async () => {
// Iterate through all scheduled posts
for await (const post of paginatedPosts('YOUR_API_KEY', { status: 'scheduled' })) {
console.log(`${post.postGroupId}: ${post.content.slice(0, 50)}...`);
console.log(` Scheduled: ${post.scheduledTime}`);
}
})();
```
### cURL - Basic Pagination
```bash
# Get first page of scheduled posts
curl "https://api.publora.com/api/v1/list-posts?page=1&limit=20&status=scheduled" \
-H "x-publora-key: YOUR_API_KEY"
# Get second page
curl "https://api.publora.com/api/v1/list-posts?page=2&limit=20&status=scheduled" \
-H "x-publora-key: YOUR_API_KEY"
# Filter by platform and date range
curl "https://api.publora.com/api/v1/list-posts?status=scheduled&platform=twitter&fromDate=2026-03-01T00:00:00Z&toDate=2026-03-31T23:59:59Z" \
-H "x-publora-key: YOUR_API_KEY"
# Get all posts sorted by scheduled time
curl "https://api.publora.com/api/v1/list-posts?sortBy=scheduledTime&sortOrder=asc&limit=100" \
-H "x-publora-key: YOUR_API_KEY"
```
### Bash - Fetch All Pages
```bash
#!/bin/bash
API_KEY="YOUR_API_KEY"
BASE_URL="https://api.publora.com/api/v1/list-posts"
PAGE=1
LIMIT=100
ALL_POSTS="[]"
while true; do
RESPONSE=$(curl -s "${BASE_URL}?page=${PAGE}&limit=${LIMIT}&status=scheduled" \
-H "x-publora-key: ${API_KEY}")
POSTS=$(echo "$RESPONSE" | jq '.posts')
HAS_NEXT=$(echo "$RESPONSE" | jq '.pagination.hasNextPage')
TOTAL=$(echo "$RESPONSE" | jq '.pagination.totalItems')
# Merge posts
ALL_POSTS=$(echo "$ALL_POSTS" "$POSTS" | jq -s 'add')
echo "Fetched page $PAGE (Total items: $TOTAL)"
if [ "$HAS_NEXT" = "false" ]; then
break
fi
PAGE=$((PAGE + 1))
done
echo "Total posts fetched: $(echo "$ALL_POSTS" | jq 'length')"
echo "$ALL_POSTS" > scheduled_posts.json
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"Invalid status. Must be one of: draft, scheduled, published, failed, partially_published"` | Invalid status filter value |
| 400 | `"Invalid sortBy. Must be one of: createdAt, updatedAt, scheduledTime"` | Invalid sortBy field |
| 400 | `"Invalid fromDate format"` | fromDate is not a valid date string (not parseable by `new Date()`) |
| 400 | `"Invalid toDate format"` | toDate is not a valid date string (not parseable by `new Date()`) |
| 401 | `"API key is required"` | Missing `x-publora-key` header |
| 401 | `"Invalid API key"` | The provided API key is not valid |
| 401 | `"Invalid API key owner"` | API key exists but its user could not be resolved |
| 403 | `"API access is not enabled for this account"` | The account does not have API access enabled |
| 403 | `"MCP access is not enabled for this account"` | Returned when `x-publora-client: mcp` is set but MCP access is not enabled |
| 500 | `"Failed to list posts"` | Internal server error |
> **Note:** The `page` and `limit` parameters do not return errors for out-of-range values. Instead, they are silently clamped to valid ranges: `page` is clamped to a minimum of 1, and `limit` is clamped to the range 1–100 (with falsy values like 0 defaulting to 20).
## Best Practices
1. **Use reasonable page sizes.** For UI pagination, 20-50 items is typical. For bulk exports, use the max of 100.
2. **Always handle pagination.** Don't assume all posts fit on one page. Check `hasNextPage` or loop until `page >= totalPages`.
3. **Cache total counts.** The `totalItems` count is useful for UI but may be expensive. Cache it for paginated UIs.
4. **Filter server-side.** Use query parameters to filter by status and platform rather than fetching all posts and filtering client-side.
5. **Use date ranges for calendars.** When building calendar views, use `fromDate` and `toDate` to fetch only the visible range.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/platform-statistics
# Mastodon and Bluesky Statistics
Engagement counters for published Mastodon and Bluesky posts, and follower counts for the connected accounts. Values are read from the platform when you ask for them and cached for about 2 hours.
Two endpoints:
```
POST https://api.publora.com/api/v1/post-statistics
POST https://api.publora.com/api/v1/profile-statistics
```
Both require a plan that includes analytics (Pro, or a legacy Premium plan). A Starter key receives `403 ANALYTICS_PLAN_REQUIRED`.
> LinkedIn analytics live on separate endpoints with a different contract — see [LinkedIn Statistics](https://docs.publora.com/endpoints/linkedin-statistics).
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `application/json` |
## What can be queried
- **Only posts Publora published for you.** A `postedId` that does not belong to one of your own published posts is answered `null` without contacting the platform. That includes posts published from another account, invented IDs, and posts Publora published before it began storing platform IDs for these two platforms (2026-09-07) — those older posts have no `postedId` and cannot be queried.
- **Threads: the root post only.** `GET /get-post` returns one `postedId` per platform post, which for a thread is the first part. The remaining parts are not addressable.
- Take `postedId` from [`GET /get-post`](https://docs.publora.com/endpoints/get-post) or [`GET /list-posts`](https://docs.publora.com/endpoints/list-posts), and `platformId` from [`GET /platform-connections`](https://docs.publora.com/endpoints/platform-connections).
## Post Statistics
### Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `posts` | object[] | Yes | 1–50 entries. Each entry is one post on one connection. |
| `posts[].platform` | string | Yes | `mastodon` or `bluesky` |
| `posts[].platformId` | string | Yes | Connection ID, with or without the platform prefix: `bluesky-did:plc:abc123` or `did:plc:abc123` |
| `posts[].postedId` | string | Yes | Platform post ID: a Bluesky AT-URI (`at://did:plc:.../app.bsky.feed.post/3k...`) or a Mastodon status ID (`117232239423110999`) |
One request may mix both platforms and several connections. Every string is capped at 512 characters.
```json
{
"posts": [
{
"platform": "bluesky",
"platformId": "bluesky-did:plc:3xcxmi4aiok5zyghylsa4dzw",
"postedId": "at://did:plc:3xcxmi4aiok5zyghylsa4dzw/app.bsky.feed.post/3muxmedtwxd2k"
},
{
"platform": "mastodon",
"platformId": "mastodon-110300915972205108",
"postedId": "117232239423110999"
}
]
}
```
### Response
```json
{
"success": true,
"stats": {
"at://did:plc:3xcxmi4aiok5zyghylsa4dzw/app.bsky.feed.post/3muxmedtwxd2k": {
"reactions": 42,
"comments": 3,
"reposts": 7,
"quotes": 1,
"saves": 2,
"impressions": null,
"reach": null,
"clicks": null
},
"117232239423110999": null
}
}
```
| Field | Type | Description |
|-------|------|-------------|
| `stats` | object | Keyed by `postedId`. The value is a metrics object, or `null` when there is no data right now. |
| `rateLimited` | boolean | Present and `true` only when at least one connection was in a rate-limit cooldown |
| `issues` | object | Present only when non-empty. Keyed by connection ID in the `-` form, value is one of the codes below. |
`null` in `stats` is not an error. It means: the post was deleted on the platform, the ID is not one of your published posts, or the connection hit one of the conditions reported in `issues`. Retry later rather than treating it as a permanent zero.
### Metrics
Every key is always present; a metric the platform does not expose is `null`, never `0`.
| Field | Mastodon | Bluesky |
|-------|----------|---------|
| `reactions` | Favourites | Likes |
| `comments` | Replies | Replies |
| `reposts` | Boosts | Reposts |
| `quotes` | Quotes (Mastodon 4.5+, otherwise `null`) | Quote posts |
| `saves` | `null` | Bookmarks |
| `impressions` | `null` | `null` |
| `reach` | `null` | `null` |
| `clicks` | `null` | `null` |
### Connection issues
| Code | Meaning | What to do |
|------|---------|------------|
| `CONNECTION_NOT_FOUND` | No connection of yours matches that `platform` + `platformId` | Re-read `GET /platform-connections` |
| `AUTH_REVOKED` | Mastodon rejected the stored token (HTTP 401) | Reconnect the account; the connection is also flagged in `GET /platform-connections` |
| `FORBIDDEN` | Mastodon refused analytics access (HTTP 403, scope or moderation). Publishing is unaffected. | Reconnect if it persists; otherwise retry later |
| `RATE_LIMITED` | The platform is in a cooldown after answering 429 | Retry later. Mastodon cooldowns are per connection; Bluesky cooldowns apply to the whole platform. |
| `FETCH_FAILED` | A transient failure reaching the platform | Retry later |
## Profile Statistics
### Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platform` | string | Yes | `mastodon` or `bluesky` |
| `platformId` | string | Yes | Connection ID, prefix optional |
```json
{
"platform": "mastodon",
"platformId": "mastodon-110300915972205108"
}
```
### Response
```json
{
"success": true,
"profile": {
"followers": 1234,
"following": 321,
"posts": 987
},
"cached": true,
"fetchedAt": "2026-09-08T09:00:00.000Z"
}
```
| Field | Type | Description |
|-------|------|-------------|
| `profile` | object \| null | `followers`, `following`, `posts`. Each value is a number or `null`. `profile` itself is `null` when the account could not be read. |
| `cached` | boolean | `true` when the answer came from the ~2-hour cache |
| `fetchedAt` | string \| null | ISO 8601 timestamp of the value that was returned |
| `rateLimited` | boolean | Present and `true` only during a cooldown |
| `unavailable` | string | Present only when the connection is marked unavailable: `AUTH_REVOKED` or `FORBIDDEN` |
Unlike post statistics, an unknown connection is a hard error here: `404 connection not found`.
## Caching and load
- Post and profile values are cached for about 2 hours per connection. Two Publora users who connected the same account share that cache.
- A post that no longer exists on the platform is remembered as missing for the same period.
- After a platform answers `429`, Publora stops calling it until the reset time it reported (at most one hour) and answers `rateLimited: true` in the meantime.
## Examples
### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
posts: [
{
platform: 'bluesky',
platformId: 'bluesky-did:plc:3xcxmi4aiok5zyghylsa4dzw',
postedId: 'at://did:plc:3xcxmi4aiok5zyghylsa4dzw/app.bsky.feed.post/3muxmedtwxd2k'
}
]
})
});
const data = await response.json();
for (const [postedId, metrics] of Object.entries(data.stats)) {
if (!metrics) {
console.log(`${postedId}: no data right now`);
continue;
}
console.log(`${postedId}: ${metrics.reactions} likes, ${metrics.comments} replies`);
}
```
### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/post-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'posts': [
{
'platform': 'mastodon',
'platformId': 'mastodon-110300915972205108',
'postedId': '117232239423110999'
}
]
}
)
data = response.json()
for posted_id, metrics in data['stats'].items():
if metrics is None:
print(f'{posted_id}: no data right now')
else:
print(f"{posted_id}: {metrics['reactions']} favourites, {metrics['reposts']} boosts")
for connection_id, code in data.get('issues', {}).items():
print(f'{connection_id} needs attention: {code}')
```
### cURL
```bash
curl -X POST https://api.publora.com/api/v1/post-statistics \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"posts": [
{
"platform": "bluesky",
"platformId": "bluesky-did:plc:3xcxmi4aiok5zyghylsa4dzw",
"postedId": "at://did:plc:3xcxmi4aiok5zyghylsa4dzw/app.bsky.feed.post/3muxmedtwxd2k"
}
]
}'
```
```bash
curl -X POST https://api.publora.com/api/v1/profile-statistics \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"platform": "mastodon",
"platformId": "mastodon-110300915972205108"
}'
```
### Node.js (axios) — stats for a page of published posts
```javascript
const axios = require('axios');
const client = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
});
async function statsForPublishedPage() {
const { data: list } = await client.get('/list-posts', {
params: { status: 'published', limit: 25 }
});
const posts = list.posts
.flatMap((group) => group.posts || [])
.filter((post) => ['mastodon', 'bluesky'].includes(post.platform) && post.postedId)
.map((post) => ({
platform: post.platform,
platformId: post.platformId,
postedId: post.postedId
}));
if (posts.length === 0) return {};
// Never send more than 50 in one request.
const { data } = await client.post('/post-statistics', { posts: posts.slice(0, 50) });
if (data.issues) console.warn('Connections needing attention:', data.issues);
return data.stats;
}
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"posts array is required"` | `posts` missing, not an array, or empty |
| 400 | `"Maximum 50 posts per request"` | More than 50 entries in `posts` |
| 400 | `"Each post must have string platform, platformId and postedId"` | An entry is missing a field, has a non-string value, or exceeds 512 characters |
| 400 | `"platform and platformId are required"` | Profile statistics called without both fields |
| 400 | `"Unsupported platform \"x\". Supported: mastodon, bluesky"` | `platform` is neither `mastodon` nor `bluesky` |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 403 | `"Analytics requires a Pro or Premium plan"` | Code `ANALYTICS_PLAN_REQUIRED`; the plan has no analytics feature |
| 404 | `"mastodon connection not found"` | Profile statistics only — no connection of yours matches. Post statistics report this as `issues[…] = "CONNECTION_NOT_FOUND"` with `200`. |
| 504 | `"Analytics request timed out"` | Code `ANALYTICS_REQUEST_TIMEOUT`; the request exceeded its 90-second budget. Retry with fewer posts. |
| 500 | `"Failed to fetch post statistics"` | Unexpected server error |
| 500 | `"Failed to fetch profile statistics"` | Unexpected server error |
Per-connection failures are **not** errors: the response stays `200` and reports them in `issues` (post statistics) or `unavailable` / `rateLimited` (profile statistics).
## MCP
The same two operations are available over the [MCP server](https://docs.publora.com/guides/mcp-server) as `post_stats` and `profile_stats` — see the [MCP Tools Reference](https://docs.publora.com/mcp/tools-reference).
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/linkedin-statistics
# LinkedIn Post Statistics
Retrieve analytics for your LinkedIn posts: impressions, reach, reactions, comments, and reshares.
## Endpoint
```
POST https://api.publora.com/api/v1/linkedin-post-statistics
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `application/json` |
## Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN (e.g., `urn:li:share:123456789`) or share ID |
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123`) |
| `queryType` | string | No | Single metric: `IMPRESSION`, `MEMBERS_REACHED`, `RESHARE`, `REACTION`, `COMMENT` |
| `queryTypes` | string[] or `"ALL"` | No | Multiple metrics at once. Use `"ALL"` for all 5 metrics. |
Use either `queryType` (single) or `queryTypes` (multiple), not both.
> **Note:** The `queryTypes` (plural) and `aggregation` parameters are **case-insensitive** — e.g., `"impression"`, `"Impression"`, and `"IMPRESSION"` are all accepted. However, `queryType` (single metric) **must be UPPERCASE** — only `"IMPRESSION"` is valid, not `"impression"` or `"Impression"`.
## Available Metrics
| Metric | Description |
|--------|-------------|
| `IMPRESSION` | Total number of times the post was displayed |
| `MEMBERS_REACHED` | Unique LinkedIn members who saw the post |
| `RESHARE` | Number of times the post was reposted |
| `REACTION` | Total reactions (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT) |
| `COMMENT` | Total number of comments |
## Response (Single Metric)
```json
{
"success": true,
"count": 1542,
"cached": false
}
```
## Response (Multiple Metrics)
```json
{
"success": true,
"metrics": {
"IMPRESSION": 15420,
"MEMBERS_REACHED": 8234,
"RESHARE": 23,
"REACTION": 456,
"COMMENT": 89
},
"cachedMetrics": ["IMPRESSION", "REACTION"],
"cached": true
}
```
The `cachedMetrics` field lists which individual metrics were served from cache. It is only present when at least one metric was served from cache (i.e., the array is non-empty). Results are cached for 2 hours. `cached: true` means at least one metric was served from cache.
### Partial Failure (Multiple Metrics)
When requesting multiple metrics, some may succeed while others fail. The response includes an `errors` array:
```json
{
"success": false,
"metrics": {
"IMPRESSION": 15420,
"MEMBERS_REACHED": null,
"REACTION": 456,
"COMMENT": 89,
"RESHARE": null
},
"errors": [
{ "metric": "MEMBERS_REACHED", "error": "Failed to fetch metric from LinkedIn" },
{ "metric": "RESHARE", "error": "Failed to fetch metric from LinkedIn" }
],
"cached": false
}
```
Failed metrics are included in the `metrics` object with `null` values (they are not omitted). The error message is always `"Failed to fetch metric from LinkedIn"` regardless of the underlying cause. Check the `errors` array to identify which metrics failed.
> **Note:** A metric value may be `null` in the `metrics` object without a corresponding entry in the `errors` array. This occurs when LinkedIn returns a `-1` count (interpreted as unavailable data), as opposed to a fetch failure which produces both a `null` metric and an `errors` entry.
## Examples
### Get all metrics for a post
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
platformId: 'linkedin-Tz9W5i6ZYG',
queryTypes: 'ALL'
})
});
const data = await response.json();
console.log(`Impressions: ${data.metrics.IMPRESSION}`);
console.log(`Reactions: ${data.metrics.REACTION}`);
console.log(`Comments: ${data.metrics.COMMENT}`);
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-post-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7123456789012345678',
'platformId': 'linkedin-Tz9W5i6ZYG',
'queryTypes': 'ALL'
}
)
metrics = response.json()['metrics']
print(f"Impressions: {metrics['IMPRESSION']}")
print(f"Reach: {metrics['MEMBERS_REACHED']}")
print(f"Engagement: {metrics['REACTION'] + metrics['COMMENT'] + metrics['RESHARE']}")
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-post-statistics \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:share:7123456789012345678",
"platformId": "linkedin-Tz9W5i6ZYG",
"queryTypes": "ALL"
}'
```
### Get a single metric
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
platformId: 'linkedin-Tz9W5i6ZYG',
queryType: 'IMPRESSION'
})
});
const data = await response.json();
console.log(`Impressions: ${data.count}`); // 1542
```
### Get specific metrics
```python
response = requests.post(
'https://api.publora.com/api/v1/linkedin-post-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7123456789012345678',
'platformId': 'linkedin-Tz9W5i6ZYG',
'queryTypes': ['IMPRESSION', 'REACTION', 'COMMENT']
}
)
```
## LinkedIn Account Statistics
Get aggregated metrics across all published LinkedIn posts for an account.
### Endpoint
```
POST https://api.publora.com/api/v1/linkedin-account-statistics
```
### Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123`) |
| `queryType` | string | No | Single metric (same options as post statistics) |
| `queryTypes` | string[] or `"ALL"` | No | Multiple metrics at once |
| `aggregation` | string | No | `"TOTAL"` (default) or `"DAILY"` |
| `dateRange` | object | No | `{ start: { year, month, day }, end: { year, month, day } }` |
> **Note:** The `queryTypes` (plural) and `aggregation` parameters are **case-insensitive** — e.g., `"total"`, `"Total"`, and `"TOTAL"` are all accepted. However, `queryType` (single metric) **must be UPPERCASE** — only `"IMPRESSION"` is valid, not `"impression"` or `"Impression"`.
```json
{
"platformId": "linkedin-Tz9W5i6ZYG",
"queryTypes": "ALL",
"aggregation": "TOTAL"
}
```
### Response (Single Metric)
When using `queryType` (single metric), the account statistics response includes the raw data and aggregation type. The `data` field type depends on the aggregation:
- **TOTAL aggregation:** `data` is a **number** (the aggregated total), or `null` when LinkedIn returns `-1` (indicating data is unavailable for that metric).
- **DAILY aggregation:** `data` is an **array of objects**, each with `count` and `dateRange` fields.
#### TOTAL aggregation example
```json
{
"success": true,
"data": 15420,
"aggregation": "TOTAL",
"cached": false
}
```
#### DAILY aggregation example
```json
{
"success": true,
"data": [
{ "count": 1200, "dateRange": { "start": { "year": 2024, "month": 1, "day": 15 }, "end": { "year": 2024, "month": 1, "day": 16 } } },
{ "count": 980, "dateRange": { "start": { "year": 2024, "month": 1, "day": 16 }, "end": { "year": 2024, "month": 1, "day": 17 } } }
],
"aggregation": "DAILY",
"cached": false
}
```
### Response (Multiple Metrics — Total Aggregation)
When using `queryTypes` (multiple metrics), the response uses the same format as post statistics but also includes the `aggregation` field:
```json
{
"success": true,
"metrics": {
"IMPRESSION": 45230,
"MEMBERS_REACHED": 22150,
"RESHARE": 89,
"REACTION": 1234,
"COMMENT": 256
},
"aggregation": "TOTAL",
"cachedMetrics": ["IMPRESSION"],
"cached": true
}
```
### Response (Daily Aggregation)
When `aggregation` is `"DAILY"`, each metric value is an array of daily data points instead of a single number:
```json
{
"success": true,
"metrics": {
"IMPRESSION": [
{ "count": 1200, "dateRange": { "start": { "year": 2024, "month": 1, "day": 15 }, "end": { "year": 2024, "month": 1, "day": 16 } } },
{ "count": 980, "dateRange": { "start": { "year": 2024, "month": 1, "day": 16 }, "end": { "year": 2024, "month": 1, "day": 17 } } }
]
},
"aggregation": "DAILY",
"cached": false
}
```
### JavaScript
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-account-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-Tz9W5i6ZYG',
queryTypes: 'ALL',
aggregation: 'TOTAL'
})
});
const data = await response.json();
console.log(`Total impressions: ${data.metrics.IMPRESSION}`);
console.log(`Total engagement: ${data.metrics.REACTION + data.metrics.COMMENT}`);
```
### Python
```python
response = requests.post(
'https://api.publora.com/api/v1/linkedin-account-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'platformId': 'linkedin-Tz9W5i6ZYG',
'queryTypes': 'ALL',
'aggregation': 'TOTAL'
}
)
stats = response.json()
print(f"Total impressions: {stats['metrics']['IMPRESSION']}")
print(f"Total engagement: {stats['metrics']['REACTION'] + stats['metrics']['COMMENT']}")
```
### Node.js (axios)
```javascript
const axios = require('axios');
const client = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
});
// Get post statistics
async function getPostStats(postedId, platformId) {
const { data } = await client.post('/linkedin-post-statistics', {
postedId,
platformId,
queryTypes: 'ALL'
});
return data.metrics;
}
// Get account statistics
async function getAccountStats(platformId) {
const { data } = await client.post('/linkedin-account-statistics', {
platformId,
queryTypes: 'ALL',
aggregation: 'TOTAL'
});
return data.metrics;
}
// Usage
const postMetrics = await getPostStats('urn:li:share:123', 'linkedin-ABC');
const accountMetrics = await getAccountStats('linkedin-ABC');
console.log(`Post impressions: ${postMetrics.IMPRESSION}`);
console.log(`Account total impressions: ${accountMetrics.IMPRESSION}`);
```
### With Error Handling
```javascript
async function getLinkedInStats(platformId, postedId = null) {
try {
const endpoint = postedId
? '/linkedin-post-statistics'
: '/linkedin-account-statistics';
const payload = {
platformId,
queryTypes: 'ALL',
...(postedId && { postedId }),
...(!postedId && { aggregation: 'TOTAL' })
};
const response = await fetch(`https://api.publora.com/api/v1${endpoint}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': process.env.PUBLORA_API_KEY
},
body: JSON.stringify(payload)
});
const data = await response.json();
if (!response.ok) {
switch (response.status) {
case 400:
throw new Error(`Invalid request: ${data.error}`);
case 404:
throw new Error('LinkedIn account not found. Check your platformId.');
default:
throw new Error(data.error || `HTTP ${response.status}`);
}
}
return {
metrics: data.metrics,
cached: data.cached,
engagementRate: calculateEngagementRate(data.metrics)
};
} catch (error) {
console.error('Failed to fetch LinkedIn stats:', error.message);
throw error;
}
}
function calculateEngagementRate(metrics) {
const engagement = metrics.REACTION + metrics.COMMENT + metrics.RESHARE;
const reach = metrics.MEMBERS_REACHED || metrics.IMPRESSION;
return reach > 0 ? ((engagement / reach) * 100).toFixed(2) + '%' : '0%';
}
```
```python
import os
import requests
def get_linkedin_stats(platform_id, posted_id=None):
"""Get LinkedIn statistics with error handling."""
endpoint = 'linkedin-post-statistics' if posted_id else 'linkedin-account-statistics'
url = f'https://api.publora.com/api/v1/{endpoint}'
payload = {
'platformId': platform_id,
'queryTypes': 'ALL'
}
if posted_id:
payload['postedId'] = posted_id
else:
payload['aggregation'] = 'TOTAL'
try:
response = requests.post(
url,
headers={
'Content-Type': 'application/json',
'x-publora-key': os.environ['PUBLORA_API_KEY']
},
json=payload
)
data = response.json()
if response.status_code == 400:
raise ValueError(f"Invalid request: {data.get('error')}")
if response.status_code == 404:
raise ValueError('LinkedIn account not found. Check your platformId.')
response.raise_for_status()
metrics = data['metrics']
engagement = metrics['REACTION'] + metrics['COMMENT'] + metrics['RESHARE']
reach = metrics.get('MEMBERS_REACHED', metrics['IMPRESSION'])
engagement_rate = (engagement / reach * 100) if reach > 0 else 0
return {
'metrics': metrics,
'cached': data['cached'],
'engagement_rate': f"{engagement_rate:.2f}%"
}
except requests.RequestException as e:
print(f'Failed to fetch LinkedIn stats: {e}')
raise
# Usage
stats = get_linkedin_stats('linkedin-Tz9W5i6ZYG')
print(f"Total impressions: {stats['metrics']['IMPRESSION']}")
print(f"Engagement rate: {stats['engagement_rate']}")
```
## Errors
### Post Statistics Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"postedId and platformId are required"` | Missing postedId or platformId |
| 400 | `"postedId and platformId must be strings"` | postedId or platformId is not a string type |
| 400 | `"queryType or queryTypes is required"` | Neither queryType nor queryTypes provided |
| 400 | `"Invalid queryType. Must be one of: IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT"` | queryType not one of the 5 valid types |
| 400 | `"Invalid queryTypes: ${invalidTypes}. Must be one of: IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT, or \"ALL\""` | queryTypes contains invalid values |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 500 | `"Failed to fetch metric from LinkedIn"` | Server error while fetching a single metric (queryType) — LinkedIn returned null data |
| 500 | `"Failed to fetch LinkedIn post statistics"` | Catch-all server error from outer try/catch |
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403, 429), so you may receive error codes other than those listed above.
### Account Statistics Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"platformId is required"` | Missing platformId |
| 400 | `"platformId must be a string"` | platformId is not a string type |
| 400 | `"queryType or queryTypes is required"` | Neither queryType nor queryTypes provided |
| 400 | `"Invalid queryType. Must be one of: IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT"` | queryType not one of the 5 valid types |
| 400 | `"Invalid queryTypes: ${invalidTypes}. Must be one of: IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT, or \"ALL\""` | queryTypes contains invalid values |
| 400 | `"aggregation must be a string"` | aggregation parameter was provided but is not a string type |
| 400 | `"Invalid aggregation. Must be one of: DAILY, TOTAL"` | aggregation not TOTAL or DAILY |
| 400 | `"dateRange must be an object"` | dateRange parameter was provided but is not an object type |
| 400 | `"dateRange must have both 'start' and 'end' objects"` | dateRange provided but missing start or end |
| 400 | `"dateRange.start and dateRange.end must have: year, month, day"` | dateRange start/end missing required fields |
| 400 | `"MEMBERS_REACHED with DAILY aggregation is not supported by LinkedIn API"` | Unsupported metric/aggregation combination |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 500 | `"Failed to fetch metric from LinkedIn"` | Single-metric request (queryType) returned null data from LinkedIn |
| 500 | `"Failed to fetch LinkedIn account statistics"` | Catch-all server error from outer try/catch |
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403, 429), so you may receive error codes other than those listed above.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/linkedin-reactions
# LinkedIn Reactions
Add or remove reactions on LinkedIn posts programmatically.
## Add Reaction
```
POST https://api.publora.com/api/v1/linkedin-reactions
```
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `application/json` |
### Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn URN (e.g., `urn:li:share:123`, `urn:li:ugcPost:456`, `urn:li:activity:789`) |
| `reactionType` | string | Yes | One of: `LIKE`, `PRAISE`, `EMPATHY`, `INTEREST`, `APPRECIATION`, `ENTERTAINMENT` |
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123`) |
### Reaction Types
| Type | Emoji | Description |
|------|-------|-------------|
| `LIKE` | 👍 | Thumbs up |
| `PRAISE` | 🔥 | Celebrate / Fire |
| `EMPATHY` | ❤️ | Love / Heart |
| `INTEREST` | 💡 | Insightful / Light bulb |
| `APPRECIATION` | 👏 | Support / Clapping hands |
| `ENTERTAINMENT` | 😄 | Funny / Laughing |
> **Note:** The `reactionType` parameter is **case-insensitive** — e.g., `"like"`, `"Like"`, and `"LIKE"` are all accepted.
### Response (HTTP 201 Created)
```json
{
"success": true,
"reaction": { ... },
"urnTranslated": {
"from": "urn:li:activity:7123456789012345678",
"to": "urn:li:ugcPost:7123456789012345678"
}
}
```
> **Note:** Creating a reaction returns HTTP **201**, not 200. The `urnTranslated` field is an object `{ from, to }` showing the original and canonical URN when translation occurred (e.g., `urn:li:activity:*` translated to `urn:li:ugcPost:*`). It is absent/undefined when no translation was needed.
### Examples
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-reactions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
reactionType: 'LIKE',
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
const data = await response.json();
console.log(data.success); // true
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-reactions',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7123456789012345678',
'reactionType': 'PRAISE',
'platformId': 'linkedin-Tz9W5i6ZYG'
}
)
print(response.json()['success'])
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-reactions \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:share:7123456789012345678",
"reactionType": "LIKE",
"platformId": "linkedin-Tz9W5i6ZYG"
}'
```
#### Node.js (axios)
```javascript
const axios = require('axios');
await axios.post(
'https://api.publora.com/api/v1/linkedin-reactions',
{
postedId: 'urn:li:share:7123456789012345678',
reactionType: 'EMPATHY',
platformId: 'linkedin-Tz9W5i6ZYG'
},
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
```
---
## Remove Reaction
```
DELETE https://api.publora.com/api/v1/linkedin-reactions
```
### Request Body or Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn URN |
| `platformId` | string | Yes | LinkedIn connection ID |
> **Note:** Unlike creating a reaction, deleting does not require `reactionType`.
### Response
```json
{
"success": true,
"reaction": null,
"urnTranslated": {
"from": "urn:li:activity:7123456789012345678",
"to": "urn:li:ugcPost:7123456789012345678"
}
}
```
The `reaction` field contains the LinkedIn API response data, or `null`. The `urnTranslated` field follows the same format as the create response (object or absent).
### Examples
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-reactions', {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
```
#### Python (requests)
```python
response = requests.delete(
'https://api.publora.com/api/v1/linkedin-reactions',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7123456789012345678',
'platformId': 'linkedin-Tz9W5i6ZYG'
}
)
```
#### cURL
```bash
curl -X DELETE "https://api.publora.com/api/v1/linkedin-reactions?postedId=urn:li:share:7123456789012345678&platformId=linkedin-Tz9W5i6ZYG" \
-H "x-publora-key: YOUR_API_KEY"
```
## Errors
### Create Reaction Errors (POST)
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"postedId, reactionType, and platformId are required"` | Missing one or more required fields |
| 400 | `"platformId must be a string"` | platformId is not a string type |
| 400 | `"postedId must be a valid LinkedIn URN"` | Not a valid LinkedIn URN format |
| 400 | `"reactionType must be one of: LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT"` | Not one of the 6 valid types |
| 400 | `"Invalid platformId"` | platformId format is invalid |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 409 | `"REACTION_ALREADY_EXISTS"` | A reaction by this account already exists on the post (any type). LinkedIn keys reactions by `(actor, entity)`, so delete the existing reaction before applying a different one. |
| 500 | `"Failed to create LinkedIn reaction"` | Server error while adding reaction |
> **Note:** The 500 error response includes `details` and `status` fields: `{ "error": "Failed to create LinkedIn reaction", "details": { ... }, "status": }`. The `details` field contains the full LinkedIn API error response object, whose structure depends on what LinkedIn returns (e.g., it may include `message`, `status`, `serviceErrorCode`, etc.). The `status` field reflects the HTTP status code returned by the LinkedIn API.
> **Note:** POSTing a reaction that already exists returns **409** with body `{ "error": "REACTION_ALREADY_EXISTS", "message": "A reaction already exists on this post. Delete it before applying ''.", "requestedReactionType": "" }`. Publora cannot read your existing reaction type back (LinkedIn scope limitation), so the conflict is surfaced rather than silently overwritten. To change reaction type, [remove the reaction](#remove-reaction) first, then POST the new one.
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403, 429), so you may receive error codes other than those listed above.
### Delete Reaction Errors (DELETE)
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"postedId and platformId are required"` | Missing postedId or platformId |
| 400 | `"platformId must be a string"` | platformId is not a string type |
| 400 | `"postedId must be a valid LinkedIn URN"` | Not a valid LinkedIn URN format |
| 400 | `"Invalid platformId"` | platformId format is invalid |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 500 | `"Failed to delete LinkedIn reaction"` | Server error while removing reaction |
> **Note:** The 500 error response includes `details` and `status` fields: `{ "error": "Failed to delete LinkedIn reaction", "details": { ... }, "status": }`. The `details` field contains the full LinkedIn API error response object, whose structure depends on what LinkedIn returns (e.g., it may include `message`, `status`, `serviceErrorCode`, etc.). The `status` field reflects the HTTP status code returned by the LinkedIn API.
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403, 429), so you may receive error codes other than those listed above.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/linkedin-followers
# LinkedIn Followers
Retrieve follower statistics for your LinkedIn account, including total follower count and daily growth data.
## Endpoint
```
POST https://api.publora.com/api/v1/linkedin-followers
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `application/json` |
## Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123`) |
| `period` | string | No | `"lifetime"` (default) or `"daily"` |
| `dateRange` | object | Conditional | Required when `period="daily"`. Contains `start` and `end` date objects. |
### Date Range Format
> **Note:** The `period` parameter is **case-insensitive** — e.g., `"daily"`, `"Daily"`, and `"DAILY"` are all accepted.
When using `period="daily"`, you must provide a `dateRange` object:
```json
{
"dateRange": {
"start": { "year": 2024, "month": 1, "day": 1 },
"end": { "year": 2024, "month": 1, "day": 31 }
}
}
```
## Response (Lifetime)
When `period="lifetime"` (or omitted), returns the total follower count:
```json
{
"success": true,
"followersCount": 1234,
"cached": false
}
```
## Response (Daily)
When `period="daily"`, returns daily follower growth data:
```json
{
"success": true,
"data": [
{ "date": "2024-01-15", "count": 10 },
{ "date": "2024-01-16", "count": 15 },
{ "date": "2024-01-17", "count": 8 }
],
"totalGrowth": 33,
"cached": false
}
```
Results are cached for 2 hours. `cached: true` means the data was served from cache.
## Examples
### Get total follower count
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-followers', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
const data = await response.json();
console.log(`Total followers: ${data.followersCount}`);
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-followers',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'platformId': 'linkedin-Tz9W5i6ZYG'
}
)
data = response.json()
print(f"Total followers: {data['followersCount']}")
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-followers \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"platformId": "linkedin-Tz9W5i6ZYG"
}'
```
### Get daily follower growth
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-followers', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-Tz9W5i6ZYG',
period: 'daily',
dateRange: {
start: { year: 2024, month: 1, day: 1 },
end: { year: 2024, month: 1, day: 31 }
}
})
});
const data = await response.json();
console.log(`Total growth: ${data.totalGrowth} new followers`);
data.data.forEach(day => {
console.log(`${day.date}: +${day.count} followers`);
});
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-followers',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'platformId': 'linkedin-Tz9W5i6ZYG',
'period': 'daily',
'dateRange': {
'start': {'year': 2024, 'month': 1, 'day': 1},
'end': {'year': 2024, 'month': 1, 'day': 31}
}
}
)
data = response.json()
print(f"Total growth: {data['totalGrowth']} new followers")
for day in data['data']:
print(f"{day['date']}: +{day['count']} followers")
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-followers \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"platformId": "linkedin-Tz9W5i6ZYG",
"period": "daily",
"dateRange": {
"start": { "year": 2024, "month": 1, "day": 1 },
"end": { "year": 2024, "month": 1, "day": 31 }
}
}'
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"platformId is required"` | Missing platformId in request body |
| 400 | `"platformId must be a string"` | platformId is not a string type |
| 400 | `"Invalid platformId"` | platformId is a string but has an invalid format (empty or unrecognized) |
| 400 | `"period must be a string"` | period parameter is not a string type |
| 400 | `"Invalid period. Must be one of: lifetime, daily"` | period is not "lifetime" or "daily" |
| 400 | `"dateRange is required for daily period"` | period is "daily" but dateRange is missing |
| 400 | `"dateRange must be an object"` | dateRange is not a plain object (e.g., it is null, an array, or a non-object type) |
| 400 | `"dateRange must have both 'start' and 'end' objects"` | dateRange provided but missing start or end |
| 400 | `"dateRange.start and dateRange.end must have: year, month, day"` | dateRange start/end missing required fields |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 500 | `"Failed to fetch LinkedIn followers statistics"` | LinkedIn API error or internal server error |
> **Note:** The "Invalid platformId" error only triggers for empty or unrecognized string values. Non-string values are caught earlier by the `"platformId must be a string"` check. Any non-empty string passes validation here. By contrast, `create-post` parses a compound key at the first `-`: its prefix must be lowercase letters, and its non-empty ID rejects whitespace, `/`, `?`, and `#` (colons are allowed). This applies to followers, reactions, comments, and profile summary endpoints — but **not** statistics endpoints, which use inline extraction and never return this error.
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403, 429), so you may receive error codes other than those listed above.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) -- the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/linkedin-profile-summary
# LinkedIn Profile Summary
Retrieve a summary of your LinkedIn profile analytics including follower counts and aggregated post engagement metrics.
## Endpoint
```
POST https://api.publora.com/api/v1/linkedin-profile-summary
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `application/json` |
## Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-{id}`) |
| `dateRange` | object | No | Date range filter for metrics |
| `dateRange.start` | object | Conditional | Start date: `{ year, month, day }` |
| `dateRange.end` | object | Conditional | End date: `{ year, month, day }` |
> **Note:** Both `start` and `end` are required when `dateRange` is provided. You cannot specify only one of them.
## Response
### Success Response
```json
{
"success": true,
"profile": {
"followers": {
"total": 5000,
"periodGrowth": 150
},
"posts": {
"totalImpressions": 25000,
"totalMembersReached": 12500,
"totalReactions": 500,
"totalComments": 75,
"totalReshares": 30
}
}
}
```
### Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `profile.followers.total` | integer | Total follower count |
| `profile.followers.periodGrowth` | integer | Follower growth during date range (only present when `dateRange` is provided) |
| `profile.posts.totalImpressions` | integer or null | Total post impressions (null if LinkedIn returns unavailable) |
| `profile.posts.totalMembersReached` | integer or null | Total unique members who saw your posts (null if LinkedIn returns unavailable) |
| `profile.posts.totalReactions` | integer or null | Total reactions across all posts (null if LinkedIn returns unavailable) |
| `profile.posts.totalComments` | integer or null | Total comments across all posts (null if LinkedIn returns unavailable) |
| `profile.posts.totalReshares` | integer or null | Total reshares across all posts (null if LinkedIn returns unavailable) |
> **Note:** Metric fields become `null` only when LinkedIn explicitly returns `-1` for that metric. If an API call fails entirely, the field defaults to `0` in the profile output (and the failure is reported in the `errors` array).
### Partial Failure Response
When some data was fetched successfully but other requests failed:
```json
{
"success": false,
"partialData": true,
"profile": {
"followers": {
"total": 5000
},
"posts": {
"totalImpressions": 25000,
"totalMembersReached": 0,
"totalReshares": 30,
"totalReactions": 500,
"totalComments": 75
}
},
"errors": [
{ "metric": "followersPeriod", "error": "Failed to fetch follower growth" },
{ "metric": "post_MEMBERS_REACHED", "error": "Failed to fetch members_reached count" }
]
}
```
The `partialData: true` flag indicates some metrics are available despite the failure. Check the `errors` array for details on what failed. Each error object contains:
- `metric`: The metric that failed to fetch (uses prefixed format: `followersLifetime`, `followersPeriod`, `post_IMPRESSION`, `post_MEMBERS_REACHED`, `post_REACTION`, `post_COMMENT`, `post_RESHARE`)
- `error`: The error message describing what went wrong. For post metrics, the format is `"Failed to fetch {metric} count"` where `{metric}` uses **lowercase with underscores** (e.g., `"Failed to fetch impression count"`, `"Failed to fetch members_reached count"`, `"Failed to fetch reaction count"`). For follower metrics, it is `"Failed to fetch follower count"` or `"Failed to fetch follower growth"`.
## Examples
### Get full profile summary
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-profile-summary', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
const data = await response.json();
console.log(`Followers: ${data.profile.followers.total}`);
console.log(`Total Impressions: ${data.profile.posts.totalImpressions}`);
console.log(`Total Engagement: ${data.profile.posts.totalReactions + data.profile.posts.totalComments}`);
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-profile-summary',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'platformId': 'linkedin-Tz9W5i6ZYG'
}
)
data = response.json()
profile = data['profile']
print(f"Followers: {profile['followers']['total']}")
print(f"Total Impressions: {profile['posts']['totalImpressions']}")
print(f"Total Reactions: {profile['posts']['totalReactions']}")
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-profile-summary \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"platformId": "linkedin-Tz9W5i6ZYG"
}'
```
### Get profile summary with date range
Track follower growth and metrics for a specific time period:
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-profile-summary', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-Tz9W5i6ZYG',
dateRange: {
start: { year: 2026, month: 1, day: 1 },
end: { year: 2026, month: 1, day: 31 }
}
})
});
const data = await response.json();
console.log(`Follower growth in January: ${data.profile.followers.periodGrowth}`);
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-profile-summary',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'platformId': 'linkedin-Tz9W5i6ZYG',
'dateRange': {
'start': {'year': 2026, 'month': 1, 'day': 1},
'end': {'year': 2026, 'month': 1, 'day': 31}
}
}
)
data = response.json()
print(f"Follower growth: {data['profile']['followers']['periodGrowth']}")
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-profile-summary \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"platformId": "linkedin-Tz9W5i6ZYG",
"dateRange": {
"start": { "year": 2026, "month": 1, "day": 1 },
"end": { "year": 2026, "month": 1, "day": 31 }
}
}'
```
### Handle partial failures
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-profile-summary', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
const data = await response.json();
if (data.partialData) {
console.warn('Some data could not be fetched:', data.errors);
// Still use available data
if (data.profile.posts) {
console.log(`Impressions: ${data.profile.posts.totalImpressions}`);
}
} else if (data.success) {
console.log(`Full profile data received`);
}
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"platformId is required"` | Missing platformId in request body |
| 400 | `"platformId must be a string"` | platformId is not a string type |
| 400 | `"Invalid platformId"` | platformId format is invalid |
| 400 | `"dateRange must be an object"` | dateRange parameter was provided but is not an object type |
| 400 | `"dateRange must have both 'start' and 'end' objects"` | dateRange provided but missing start or end |
| 400 | `"dateRange.start and dateRange.end must have: year, month, day"` | dateRange start/end missing required fields |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 500 | `"Failed to fetch LinkedIn profile summary"` | Server error |
| 502 | `"Failed to fetch LinkedIn profile data"` | Unable to fetch any data from LinkedIn |
The 502 error response includes an `errors` array with details on each failed metric:
```json
{
"success": false,
"error": "Failed to fetch LinkedIn profile data",
"errors": [
{ "metric": "followersLifetime", "error": "Failed to fetch follower count" },
{ "metric": "post_IMPRESSION", "error": "Failed to fetch impression count" }
]
}
```
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403, 429), so you may receive error codes other than those listed above.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) -- the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/linkedin-comments
# LinkedIn Comments
Create and delete comments on LinkedIn posts programmatically.
## Create Comment
```
POST https://api.publora.com/api/v1/linkedin-comments
```
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `application/json` |
### Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN: `urn:li:share:xxx`, `urn:li:ugcPost:xxx`, or `urn:li:activity:xxx` |
| `message` | string | Yes | May be `""` when `imageUrl` is provided; otherwise must contain non-whitespace text. Raw input up to 10,000 characters. After mention syntax is converted, the text sent to LinkedIn must be at most 1,250 characters. |
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123`) |
| `parentComment` | string | No | Parent comment URN for threaded replies |
| `imageUrl` | string | No | Public HTTPS URL of one JPEG, PNG or GIF image, up to 10 MB. |
`message` remains a required string, including for image-only comments. Text and image URLs are trimmed; an empty or whitespace-only message without a non-blank `imageUrl` returns HTTP 400. No placeholder text is inserted. Image validation and upload must succeed before the comment is sent to LinkedIn.
LinkedIn image limits also apply: fewer than 36,152,320 pixels and at most 250 frames for GIFs. A successful creation response does not guarantee how LinkedIn renders the image.
### Response (HTTP 201 Created)
```json
{
"success": true,
"comment": {
"id": "6636062862760562688",
"commentUrn": "urn:li:comment:(urn:li:activity:7123456789012345678,6636062862760562688)",
"message": "Great post! Thanks for sharing.",
"created": {
"time": 1710345600000
}
}
}
```
> **Note:** The `id` field is the numeric comment ID extracted from the LinkedIn API's `x-restli-id` response header. The full comment URN is in the `commentUrn` field. The `comment` object also includes data returned by the LinkedIn API spread into it, so additional fields from the LinkedIn response may be present.
> **Note:** Fields like `created` are passed through from LinkedIn's API response and may vary. They are not guaranteed to always be present.
### Examples
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
message: 'Great post! Thanks for sharing.',
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
const data = await response.json();
console.log(data.comment.id);
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-comments',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7123456789012345678',
'message': 'Great post! Thanks for sharing.',
'platformId': 'linkedin-Tz9W5i6ZYG'
}
)
print(response.json()['comment']['id'])
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-comments \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:share:7123456789012345678",
"message": "Great post! Thanks for sharing.",
"platformId": "linkedin-Tz9W5i6ZYG"
}'
```
### Image-Only Comment
Use the same request with an explicitly empty message:
```json
{
"postedId": "urn:li:share:7123456789012345678",
"platformId": "linkedin-Tz9W5i6ZYG",
"message": "",
"imageUrl": "https://cdn.example.com/reaction.png"
}
```
This works for connected personal profiles and organization pages. A successful response includes `comment.imageUrn`, the LinkedIn image URN attached to the comment.
### Reply to a Comment
To create a threaded reply, include the `parentComment` parameter:
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
message: 'Thanks for the kind words!',
platformId: 'linkedin-Tz9W5i6ZYG',
parentComment: 'urn:li:comment:(urn:li:activity:7123456789012345678,6636062862760562688)'
})
});
```
---
## Delete Comment
```
DELETE https://api.publora.com/api/v1/linkedin-comments
```
### Request Body or Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN |
| `commentId` | string | Yes | Comment ID or URN to delete |
| `platformId` | string | Yes | LinkedIn connection ID |
### Response
```json
{
"success": true,
"deleted": "6636062862760562688"
}
```
The `deleted` field contains the comment ID that was removed. This can be a numeric ID or a full URN (e.g., `urn:li:comment:(urn:li:activity:123,6636062862760562688)`), depending on what was passed as `commentId`.
### Examples
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
commentId: '6636062862760562688',
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
```
#### Python (requests)
```python
response = requests.delete(
'https://api.publora.com/api/v1/linkedin-comments',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7123456789012345678',
'commentId': '6636062862760562688',
'platformId': 'linkedin-Tz9W5i6ZYG'
}
)
```
#### cURL
```bash
curl -X DELETE "https://api.publora.com/api/v1/linkedin-comments" \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:share:7123456789012345678",
"commentId": "6636062862760562688",
"platformId": "linkedin-Tz9W5i6ZYG"
}'
```
## Mentions in Comments
You can @mention LinkedIn members and organizations in comments using the same syntax as posts:
```
@{urn:li:person:MEMBER_ID|Display Name} # Mention a person
@{urn:li:organization:ORG_ID|Company Name} # Mention an organization
```
Publora automatically converts this to LinkedIn's comment mention format (`message.attributes`). The mention renders as a clickable link and notifies the mentioned user.
### Example with Mention
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
message: 'Great point @{urn:li:person:ACoAABcD1234EfG|Jane Smith}! Totally agree.',
platformId: 'linkedin-Tz9W5i6ZYG'
})
});
```
**Result on LinkedIn:** `Great point @Jane Smith! Totally agree.` — with "Jane Smith" as a clickable profile link.
> **Important:** You must use a valid LinkedIn URN ID. Invalid IDs will cause LinkedIn to reject the comment with a `400` error. See the [LinkedIn Mentions Guide](../guides/linkedin-mentions.md) for how to find URN IDs.
### postedId Format
Publora accepts `urn:li:share:xxx`, `urn:li:ugcPost:xxx`, and `urn:li:activity:xxx`. It first sends the supplied URN to LinkedIn. If LinkedIn rejects an activity URN with a retryable target error, Publora also attempts the corresponding `ugcPost` and `share` URNs with the same ID. LinkedIn can still reject a URN based on the target post or account permissions.
For posts created via Publora, prefer the exact `postedId` returned by [get-post](get-post.md).
---
## Errors
### Create Comment Errors (POST)
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"postedId, message, and platformId are required"` | Missing required fields |
| 400 | `"platformId must be a string"` | platformId is not a string type |
| 400 | `"postedId must be a valid LinkedIn URN"` | Not a valid LinkedIn URN format |
| 400 | `"message cannot be empty without imageUrl"` | Message is empty or whitespace-only and `imageUrl` is missing or blank |
| 400 | `"message must be a string"` | Message is not a string |
| 400 | `"imageUrl must be a string"` | Supplied imageUrl is not a string |
| 400 | `"comment text cannot exceed 10000 characters"` | Raw input exceeds the defensive pre-processing cap |
| 400 | `"comment text cannot exceed 1250 characters after mention processing"` | Converted LinkedIn comment text exceeds the platform limit |
| 400 | `"parentComment must be a valid LinkedIn URN"` | parentComment is not a valid URN format |
| 400 | `"Invalid platformId"` | platformId format is invalid |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 500 | `"Failed to create LinkedIn comment"` | Server error while creating comment |
### Delete Comment Errors (DELETE)
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"postedId, commentId, and platformId are required"` | Missing required fields |
| 400 | `"platformId must be a string"` | platformId is not a string type |
| 400 | `"postedId must be a valid LinkedIn URN"` | Not a valid LinkedIn URN format |
| 400 | `"commentId must be a valid LinkedIn URN or numeric ID"` | commentId format is invalid |
| 400 | `"Invalid platformId"` | platformId format is invalid |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"Invalid API key owner"` | API key owner user not found in database |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that platformId |
| 500 | `"Failed to delete LinkedIn comment"` | Server error while deleting comment |
> **Note:** The 500 error response includes a `details` field with the underlying error message: `{ "error": "Failed to delete LinkedIn comment", "details": "" }`.
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403, 429), so you may receive error codes other than those listed above.
## Implementation Notes
- **Create comment response field precedence:** The create comment response constructs the `comment` object by spreading `...response.data` from the LinkedIn API, then explicitly setting `id`, `commentUrn`, and `message`. If LinkedIn ever returns fields named `id`, `commentUrn`, or `message` in its response body, the explicit values will override them. However, if LinkedIn adds new fields with those names in a different format, the spread could briefly surface unexpected data before the override. In practice this is unlikely but worth noting for defensive parsing.
- **Delete comment `commentId` format:** The REST API accepts both a full URN (e.g., `urn:li:comment:(urn:li:activity:123,456)`) and a plain numeric comment ID (e.g., `"6636062862760562688"`). The MCP tool description only mentions URN format, but both formats work identically via the REST API.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) -- the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/linkedin-reshare
# LinkedIn Reshare
Reshare (repost) an existing LinkedIn post to your own feed, with optional commentary. Works for both **personal profile** and **company page** connections.
There are two ways to repost on LinkedIn via Publora:
1. **Immediate reshare** — `POST /linkedin-reshare` (this page). The repost is published right away.
2. **Scheduled reshare** — set `platformSettings.linkedin.repostParentUrn` on [create-post](create-post.md) / [update-post](update-post.md). The repost goes through the normal scheduling pipeline (see [Scheduled Reshares](#scheduled-reshares) below).
## Reshare a Post
```
POST https://api.publora.com/api/v1/linkedin-reshare
```
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `Content-Type` | Yes | `application/json` |
### Request Body
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123` — the `linkedin-` prefix is accepted and stripped). Determines who authors the reshare — a personal connection reshares as the member, a company-page connection reshares as the organization. |
| `parent` | string | Yes | URN of the post to reshare. Must be a `urn:li:share:` or `urn:li:ugcPost:` — **not** a `urn:li:activity:` URN (see [parent Format](#parent-format)). |
| `commentary` | string | No | Text added above the reshared post. Max **3000** characters (checked both on the raw input and again after mention/text formatting). Defaults to empty (a plain reshare with no added text). Supports the `@{urn:li:person:ID\|Name}` / `@{urn:li:organization:ID\|Name}` mention syntax — same rules as posts, see the [LinkedIn Mentions Guide](../guides/linkedin-mentions.md). |
| `visibility` | string | No | `PUBLIC` or `CONNECTIONS` (case-insensitive), default `PUBLIC`. Organization/company-page reshares must use `PUBLIC`; `CONNECTIONS` is rejected. |
> **Note:** The reshare is authored automatically as the correct entity for the connection — `urn:li:person:*` for a personal profile, `urn:li:organization:*` for a company page. You do not pass the author yourself.
> **Mentions in commentary:** Person mentions must use LinkedIn's **native member id** (e.g. `Dk968RHxiO`), not the `ACoAA…` web-profile ids from linkedin.com URLs — those are rejected with a `400` error. See the [LinkedIn Mentions Guide](../guides/linkedin-mentions.md) for where to find native ids and the name-matching rules.
### Response (HTTP 201 Created)
```json
{
"success": true,
"reshare": {
"lifecycleState": "PUBLISHED",
"id": "urn:li:share:7123456789012345678"
}
}
```
> **Note:** Creating a reshare returns HTTP **201**, not 200. The `reshare.id` is the URN of the newly created reshare post (read from LinkedIn's `x-restli-id` response header); the rest of the `reshare` object is the LinkedIn API response body.
### Examples
#### JavaScript (fetch)
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-reshare', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-Tz9W5i6ZYG',
parent: 'urn:li:share:7123456789012345678',
commentary: 'Great read — sharing with my network!',
visibility: 'PUBLIC'
})
});
const data = await response.json();
console.log(data.reshare.id); // urn:li:share:...
```
#### Python (requests)
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-reshare',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'platformId': 'linkedin-Tz9W5i6ZYG',
'parent': 'urn:li:share:7123456789012345678',
'commentary': 'Great read — sharing with my network!'
}
)
print(response.json()['reshare']['id'])
```
#### cURL
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-reshare \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"platformId": "linkedin-Tz9W5i6ZYG",
"parent": "urn:li:share:7123456789012345678",
"commentary": "Great read — sharing with my network!",
"visibility": "PUBLIC"
}'
```
#### Node.js (axios)
```javascript
const axios = require('axios');
await axios.post(
'https://api.publora.com/api/v1/linkedin-reshare',
{
platformId: 'linkedin-Tz9W5i6ZYG',
parent: 'urn:li:ugcPost:7123456789012345678'
},
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
```
### parent Format
Use `urn:li:share:xxx` or `urn:li:ugcPost:xxx` — **not** `urn:li:activity:xxx`.
The `urn:li:activity:` URN is what appears in LinkedIn post URLs (e.g. `linkedin.com/feed/update/urn:li:activity:123`), but it is rejected by this endpoint with a 400 error.
To get the correct URN:
- For posts created via Publora, use the `postedId` field from the [get-post](get-post.md) response — it is already a `share` / `ugcPost` URN, so pass it straight through.
- For any other post, prefer the post's **actual** `shareUrn` / `ugcPost` URN when you can read it (most LinkedIn post scrapers return it directly alongside the activity URN). Reach for the URL's `urn:li:activity:` id only as a fallback.
> **Caveat on the activity → share swap.** The activity id and the share/ugcPost id are *often* the same number, so replacing `urn:li:activity:` with `urn:li:share:` frequently works (e.g. `urn:li:activity:7451373349668282369` → `urn:li:share:7451373349668282369`). But they are **not guaranteed** to match — real posts exist where the activity id and the share/ugcPost id differ. When they differ, the swap yields a valid-looking URN that either reshares the wrong post or is rejected. Use the post's real `shareUrn` when you have it; treat the prefix swap as a best-effort fallback only.
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"platformId and parent are required"` | Missing `platformId` or `parent` |
| 400 | `"platformId must be a string"` | `platformId` is not a string |
| 400 | `"platformId cannot be empty"` | `platformId` is blank/whitespace |
| 400 | `"parent must be a string"` | `parent` is not a string |
| 400 | `"parent cannot be empty"` | `parent` is blank/whitespace |
| 400 | `"parent must be a valid LinkedIn post URN (urn:li:share: or urn:li:ugcPost:)"` | `parent` is not a `share`/`ugcPost` URN |
| 400 | `"commentary must be a string"` | `commentary` is not a string |
| 400 | `"commentary cannot exceed 3000 characters"` | `commentary` is longer than 3000 characters |
| 400 | `"commentary exceeds 3000 characters after mention/text formatting — shorten the text"` | `commentary` fits the raw limit but exceeds 3000 characters once mention syntax is converted and reserved characters are escaped |
| 400 | `"LinkedIn cannot render mentions that use web-profile ids (urn:li:person:ACoAA…). Use the native member id LinkedIn returns to Publora…"` | A person mention in `commentary` uses a web-profile `ACoAA…` id instead of the native member id |
| 400 | `"visibility must be a string"` | `visibility` is not a string |
| 400 | `"visibility must be one of: PUBLIC, CONNECTIONS"` | `visibility` is not a valid value |
| 400 | `"LinkedIn organization reposts cannot use CONNECTIONS visibility; choose PUBLIC"` | A company-page connection requested member-only visibility |
| 400 | `"Invalid platformId"` | `platformId` format is invalid |
| 400 | `"LinkedIn company connection is missing organizationId. Please reconnect the LinkedIn page."` | Company-page connection has no stored organization id — reconnect the page |
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 401 | `"LINKEDIN_TOKEN_EXPIRED"` | The LinkedIn access token is expired/invalid — reconnect the account |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 404 | `"LinkedIn connection not found"` | No LinkedIn account with that `platformId` for this user |
| 500 | `"Failed to create LinkedIn reshare"` | Server error while creating the reshare |
> **Note:** The error response for a failed LinkedIn call includes a `details` **string** with the underlying LinkedIn error message: `{ "error": "Failed to create LinkedIn reshare", "details": "" }` (unlike the reactions endpoint, there is no separate `status` field in the body).
> **Note:** Error status codes from the LinkedIn API may be forwarded directly (e.g., 403 if the post's author disabled resharing, 429 on rate limits), so you may receive error codes other than those listed above.
## Scheduled Reshares
To schedule a repost for a future time instead of publishing immediately, use the normal scheduling pipeline with LinkedIn platform settings:
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'My commentary on this great post.',
platforms: ['linkedin-Tz9W5i6ZYG'],
scheduledTime: '2026-08-01T14:00:00.000Z',
platformSettings: {
linkedin: {
repostParentUrn: 'urn:li:share:7123456789012345678',
repostVisibility: 'PUBLIC'
}
}
})
});
```
The post `content` becomes the reshare commentary. **Media is not allowed on repost groups.** See [Create Post → LinkedIn Repost Settings](create-post.md#linkedin-repost-settings) for the full field reference and validation rules.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/linkedin-mentionables
# LinkedIn Mentionables
List the LinkedIn members you can @mention — a per-user directory of people whose **native member ids** Publora has captured from engagement on your connected company pages. Each entry includes a ready-to-paste `mention` token for [create-post](create-post.md) content, [comment](linkedin-comments.md) messages, or [reshare commentary](linkedin-reshare.md).
Why this exists: person mentions require LinkedIn's native member id (e.g. `Dk968RHxiO`), which cannot be derived from a linkedin.com profile URL. This directory is where Publora surfaces every native id it has seen for you. See the [LinkedIn Mentions Guide](../guides/linkedin-mentions.md) for the full id explanation and name-matching rules.
> **Paid plans only.** Free plans receive a `403 UPGRADE_REQUIRED` error (see [Errors](#errors)).
## List Mentionable People
```
GET https://api.publora.com/api/v1/linkedin-mentionables
```
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Case-insensitive substring filter on the person's name (regex characters are treated literally). Omit to list everyone. |
| `limit` | number | No | Maximum number of entries to return, `1`–`100`. Default `25`. |
Results are sorted by `lastSeenAt` descending — the most recently engaged people first.
### Response (HTTP 200)
```json
{
"success": true,
"people": [
{
"personId": "Dk968RHxiO",
"name": "Daria Bulaeva",
"profileUrl": "",
"profilePicture": "",
"source": "comment",
"lastSeenAt": "2026-07-16T10:00:00.000Z",
"mention": "@{urn:li:person:Dk968RHxiO|Daria Bulaeva}"
}
]
}
```
| Field | Type | Description |
|-------|------|-------------|
| `personId` | string | The person's **native member id** — the only id form that works in mentions. |
| `name` | string | The display name as captured from LinkedIn. |
| `profileUrl` | string | Currently always an empty string (reserved for future use). |
| `profilePicture` | string | Currently always an empty string (reserved for future use). |
| `source` | string | How the person was last captured: `comment` or `reaction`. The most recent engagement wins. |
| `lastSeenAt` | string | ISO 8601 timestamp of the most recent captured engagement. |
| `mention` | string \| null | Ready-to-paste mention token (`@{urn:li:person:ID\|Name}`) for post content or comment messages. `null` when no usable name is stored. Names containing `\|` or `}` are sanitized in the token. |
> **Note:** The `mention` token uses the person's full captured name. LinkedIn matches display names strictly — if you edit the name part, follow the [name matching rules](../guides/linkedin-mentions.md#critical-name-matching-requirements) (first name, last name, or full name; exact case; nothing extra).
### Examples
#### JavaScript (fetch)
```javascript
const params = new URLSearchParams({ q: 'daria', limit: '10' });
const response = await fetch(
`https://api.publora.com/api/v1/linkedin-mentionables?${params}`,
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
for (const person of data.people) {
if (person.mention) {
console.log(`${person.name}: ${person.mention}`);
}
}
```
#### cURL
```bash
curl "https://api.publora.com/api/v1/linkedin-mentionables?q=daria&limit=10" \
-H "x-publora-key: YOUR_API_KEY"
```
## How the Directory Fills
The directory is populated **automatically** — there is no endpoint to add people manually:
- When comments or reactions are read on posts of your connected **company pages** (via the Publora app's engagement views or the [feed-retrieval API](linkedin-feed-retrieval.md)), LinkedIn returns each engaging member's native app-scoped person id, and Publora persists it in your directory.
- No extra LinkedIn API calls are made — the ids are captured as a side effect of reads you already perform.
- Engagement on **personal-profile posts is not capturable** — LinkedIn restricts the required scope. Only company-page engagement feeds the directory.
- Placeholder/unresolved actors (entries LinkedIn returns without a resolvable member) are skipped.
There is **no way to add an arbitrary person by profile URL** — the `ACoAA…` web-profile ids visible on linkedin.com cannot be converted to native ids. See [Finding LinkedIn URNs](../guides/linkedin-mentions.md#finding-linkedin-urns) for the full explanation of native vs web-profile ids.
## MCP Tool
The same directory is available to MCP clients as the `linkedin_list_mentionables` tool, with the same `q`/`limit` parameters and the same paid-plan requirement. See the [MCP Tools Reference](../mcp/tools-reference.md#linkedin-mentionables-tool).
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 401 | `"API key is required"` | No `x-publora-key` header provided |
| 401 | `"Invalid API key"` | Bad `x-publora-key` |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 403 | `"The mentionable-people directory is available on paid plans — upgrade to access it"` | Free plan — the response also includes `"code": "UPGRADE_REQUIRED"` |
> **Note:** The free Starter plan includes API and MCP access, so a Starter key is authenticated and then receives `403 UPGRADE_REQUIRED` here. The `403` API-access error appears only for an account whose API access was disabled.
## Related
- [LinkedIn Mentions Guide](../guides/linkedin-mentions.md) — mention syntax, native vs web-profile ids, name matching
- [LinkedIn Comments](linkedin-comments.md) — mention people in comments
- [LinkedIn Reshare](linkedin-reshare.md) — mention people in reshare commentary
- [Create Post](create-post.md) — mention people in scheduled posts
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/post-logs
# Post Logs
Get detailed publish attempt history for a post group. Useful for debugging failed posts and understanding the publish timeline.
Events are retained for **90 days by event `createdAt`**. Responses include only
events from that rolling window. The post group and published post history are
kept independently of these diagnostic events.
## Endpoint
```
GET https://api.publora.com/api/v1/post-logs/:postGroupId
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Set to `mcp` for MCP tool access |
> **MCP access:** If the `x-publora-client: mcp` header is sent, the server validates `entitlements.features.mcpAccess` and returns `403 "MCP access is not enabled for this account"` if the feature is not enabled.
## Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `postGroupId` | string | The post group ID |
> **Note:** Results are limited to the first 100 log entries per post group (sorted ascending by creation time, oldest first).
A valid post group owned by the authenticated user returns HTTP 200 with
`{ "success": true, "logs": [] }` when no events remain in the 90-day window.
An empty log list does not mean the post group is missing or publishing failed.
Missing or inaccessible groups still return HTTP 404. Physical deletion of old
events is asynchronous; the API excludes expired events even while they await
deletion.
## Response
```json
{
"success": true,
"logs": [
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d0",
"postGroupId": "507f1f77bcf86cd799439011",
"postId": "507f1f77bcf86cd799439012",
"platform": "linkedin",
"event": "processing",
"createdAt": "2026-02-22T14:30:00.000Z"
},
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d1",
"postGroupId": "507f1f77bcf86cd799439011",
"postId": "507f1f77bcf86cd799439012",
"platform": "linkedin",
"event": "publish_attempted",
"retryCount": 0,
"createdAt": "2026-02-22T14:30:01.000Z"
},
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d2",
"postGroupId": "507f1f77bcf86cd799439011",
"postId": "507f1f77bcf86cd799439012",
"platform": "linkedin",
"event": "publish_succeeded",
"createdAt": "2026-02-22T14:30:03.000Z"
},
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d3",
"postGroupId": "507f1f77bcf86cd799439011",
"event": "processing",
"createdAt": "2026-02-22T14:30:00.000Z"
},
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d4",
"postGroupId": "507f1f77bcf86cd799439011",
"postId": "507f1f77bcf86cd799439013",
"platform": "threads",
"event": "publish_attempted",
"retryCount": 1,
"createdAt": "2026-02-22T14:30:01.000Z"
},
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d5",
"postGroupId": "507f1f77bcf86cd799439011",
"postId": "507f1f77bcf86cd799439013",
"platform": "threads",
"event": "publish_failed",
"error": "Error validating access token",
"httpStatus": 401,
"retryCount": 1,
"metadata": {
"errorCode": "PLATFORM_AUTH_EXPIRED",
"retryable": false
},
"createdAt": "2026-02-22T14:30:02.000Z"
}
]
}
```
> **Note:** Response also includes `updatedAt` (auto-managed by Mongoose) and `__v` (Mongoose version key) fields, omitted from examples for brevity.
## Log Fields
| Field | Type | Description |
|-------|------|-------------|
| `_id` | string | Unique log entry ID |
| `postGroupId` | string | Parent post group ID |
| `postId` | string/undefined | Individual platform post ID. May be absent for group-level events (e.g., initial `processing`). |
| `platform` | string/undefined | Platform name (twitter, linkedin, etc.). May be absent for group-level events. |
| `event` | string | Event type (see table below) |
| `error` | string or absent | Error message (for failed events). Absent from the response when there is no error (not `null`). |
| `httpStatus` | number/null/absent | HTTP status code from the platform. Scheduler-created logs may store it explicitly as `null`; other logs may omit it when not applicable. |
| `retryCount` | number or absent | Number of retry attempts. Absent if no retries have occurred -- do not assume it defaults to 0. |
| `metadata` | object or absent | Additional event data. Absent from the response when there is no metadata (not `null`). |
| `createdAt` | string | Event timestamp |
| `updatedAt` | string | Last update timestamp (auto-managed by Mongoose) |
| `__v` | number | Mongoose version key. Present in responses but not part of the documented schema — can be safely ignored. |
## Event Types
| Event | Description |
|-------|-------------|
| `scheduled` | Post was scheduled |
| `processing` | Post started processing |
| `publish_attempted` | Publish request sent to platform |
| `publish_succeeded` | Successfully published |
| `publish_failed` | Publishing failed |
| `publish_retry` | A publish retry was recorded |
| `status_changed` | Post status changed |
| `media_finalize_succeeded` | Attached media finalization succeeded |
| `media_finalize_failed` | Attached media finalization failed |
| `linkedin_document_upload_succeeded` | LinkedIn PDF/document upload succeeded |
| `linkedin_document_upload_failed` | LinkedIn PDF/document upload failed |
## Examples
### JavaScript (fetch)
```javascript
const postGroupId = '507f1f77bcf86cd799439011';
const response = await fetch(
`https://api.publora.com/api/v1/post-logs/${postGroupId}`,
{ headers: { 'x-publora-key': 'YOUR_API_KEY' } }
);
const { logs } = await response.json();
// Group logs by platform
const byPlatform = logs.reduce((acc, log) => {
if (!acc[log.platform]) acc[log.platform] = [];
acc[log.platform].push(log);
return acc;
}, {});
// Check for failures
const failures = logs.filter(l => l.event === 'publish_failed');
if (failures.length > 0) {
console.log('Failed platforms:');
failures.forEach(f => {
console.log(` ${f.platform}: ${f.error} (HTTP ${f.httpStatus})`);
});
}
```
### Python (requests)
```python
import requests
post_group_id = '507f1f77bcf86cd799439011'
response = requests.get(
f'https://api.publora.com/api/v1/post-logs/{post_group_id}',
headers={'x-publora-key': 'YOUR_API_KEY'}
)
logs = response.json()['logs']
# Find failed publish attempts
failures = [l for l in logs if l['event'] == 'publish_failed']
for failure in failures:
print(f"❌ {failure['platform']}: {failure['error']}")
if failure.get('metadata', {}).get('retryable'):
print(" (This error may succeed on retry)")
```
### cURL
```bash
curl https://api.publora.com/api/v1/post-logs/507f1f77bcf86cd799439011 \
-H "x-publora-key: YOUR_API_KEY"
```
### Debug Failed Post
```javascript
async function debugFailedPost(postGroupId) {
const [postResponse, logsResponse] = await Promise.all([
fetch(`https://api.publora.com/api/v1/get-post/${postGroupId}`, {
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
}),
fetch(`https://api.publora.com/api/v1/post-logs/${postGroupId}`, {
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
})
]);
const postData = await postResponse.json();
const logsData = await logsResponse.json();
console.log('=== Post Status ===');
for (const post of postData.posts) {
console.log(`${post.platform}: ${post.status}`);
if (post.error) {
console.log(` Error: ${post.error.code} - ${post.error.message}`);
console.log(` Retryable: ${post.error.retryable}`);
}
}
console.log('\n=== Timeline ===');
for (const log of logsData.logs) {
const time = new Date(log.createdAt).toISOString();
console.log(`[${time}] ${log.platform}: ${log.event}`);
if (log.error) {
console.log(` └─ ${log.error}`);
}
}
}
```
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"Invalid post group ID"` | `postGroupId` is not a valid ObjectId |
| 401 | `"API key is required"` | `x-publora-key` header is missing entirely |
| 401 | `"Invalid API key"` | `x-publora-key` is present but invalid |
| 401 | `"Invalid API key owner"` | API key exists but the associated user account was not found |
| 403 | `"API access is not enabled for this account"` | The user's account does not have API access enabled |
| 403 | `"MCP access is not enabled for this account"` | The `x-publora-client: mcp` header was sent but `entitlements.features.mcpAccess` is not enabled |
| 404 | `"Post group not found"` | No post with this ID belongs to the acting user |
| 500 | `"Failed to get post logs"` | Server error |
> **Note:** A `postGroupId` that is not a valid MongoDB ObjectId returns `400 { "error": "Invalid post group ID" }` before any lookup.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/test-connection
# Test Connection
Validate that a platform connection is working before scheduling posts.
## Endpoint
```
POST https://api.publora.com/api/v1/test-connection/:platformId
```
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
| `x-publora-client` | No | Client identifier (e.g., `mcp`). Used for MCP access gating. |
## Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `platformId` | string | The platform ID (e.g., `linkedin-Tz9W5i6ZYG`) |
## Response
### Successful Connection
```json
{
"platform": "linkedin",
"platformId": "linkedin-Tz9W5i6ZYG",
"username": "John Doe",
"status": "ok",
"message": "Connected as John Doe",
"permissions": ["w_member_social", "w_member_social_feed", "r_basicprofile", "r_member_postAnalytics", "r_member_profileAnalytics"],
"tokenExpiresIn": "45d 3h",
"lastSuccessfulPost": "2026-02-22T09:15:00.000Z",
"lastError": null
}
```
### Failed Connection
```json
{
"platform": "threads",
"platformId": "threads-17841412345678",
"username": "yourthreads",
"status": "error",
"message": "Error validating access token: Session has expired",
"permissions": [],
"tokenExpiresIn": "expired",
"lastSuccessfulPost": "2026-02-15T14:30:00.000Z",
"lastError": {
"message": "Session has expired",
"occurredAt": "2026-02-22T10:00:00.000Z"
}
}
```
> **Important:** All validation results — both success and failure — return HTTP 200. The connection test outcome is indicated by the `status` field (`"ok"` or `"error"`), not the HTTP status code. Only infrastructure errors (404 connection not found, 500 server error) use non-200 status codes.
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `platform` | string | Platform name (twitter, linkedin, threads, etc.) |
| `platformId` | string | Full platform ID |
| `username` | string/null | Connected account username. `null` for a Telegram channel without a public username (a private channel). |
| `status` | string | `ok` or `error` |
| `message` | string | Human-readable status message |
| `permissions` | array | List of granted permissions/scopes. With the YouTube update in #490, these are Google's recorded full scope URIs; an unknown grant returns `[]`. |
| `permissionsKnown` | boolean | YouTube only, added in #490. Whether the granted scopes are recorded. `false` means unknown, not permission denied. |
| `tokenExpiresIn` | string/null | Time until token expiry. Possible values: `"7d 3h"` (days and hours), `"5h"` (hours only, when less than one day remains), `"< 1h"` (less than one hour remaining), `"expired"` (token already expired), or `null` (no expiration). |
| `lastSuccessfulPost` | string/null | Timestamp of last successful post |
| `lastError` | object/null | Last error details if any. When present, contains: `message` (string — error description) and `occurredAt` (string — ISO 8601 timestamp of when the error occurred). |
### YouTube permissions — #490 update
[Publora #490](https://github.com/publora/publora.com/issues/490) corrects the
previous fixed `["youtube.upload", "youtube.readonly"]` list. Since 2026-10-01,
YouTube responses return the actual scopes recorded from Google's OAuth response,
using their full URIs. For a canonical broad grant, the relevant response fields are:
```json
{
"status": "ok",
"permissions": ["https://www.googleapis.com/auth/youtube"],
"permissionsKnown": true
}
```
A broad `youtube` grant covers uploading videos and adding them to a playlist;
it is not expanded into separately granted `youtube.upload` or `youtube.readonly`
entries. See Google's [scope definitions](https://developers.google.com/youtube/v3/guides/auth/installed-apps#identify-access-scopes)
and [playlist-write authorization](https://developers.google.com/youtube/v3/docs/playlistItems/insert#authorization).
Older connections without a recorded grant, or a reconnect where Google omits
scopes, return `permissions: []` and `permissionsKnown: false`. Do not interpret
that empty array as proof that permission was denied. If your integration gates
operations by scopes, handle unknown grants separately and recognize broad
`youtube` access; checking for the old short `youtube.upload` string is insufficient.
Use `status` for the connection health result. Other platforms' responses keep
their current format.
## Examples
### JavaScript (fetch)
```javascript
const platformId = 'linkedin-Tz9W5i6ZYG';
const response = await fetch(
`https://api.publora.com/api/v1/test-connection/${platformId}`,
{
method: 'POST',
headers: { 'x-publora-key': 'YOUR_API_KEY' }
}
);
const result = await response.json();
if (result.status === 'ok') {
console.log(`✅ ${result.message}`);
console.log(`Token expires in: ${result.tokenExpiresIn}`);
} else {
console.log(`❌ Connection failed: ${result.message}`);
}
```
### Python (requests)
```python
import requests
platform_id = 'linkedin-Tz9W5i6ZYG'
response = requests.post(
f'https://api.publora.com/api/v1/test-connection/{platform_id}',
headers={'x-publora-key': 'YOUR_API_KEY'}
)
result = response.json()
if result['status'] == 'ok':
print(f"✅ {result['message']}")
print(f"Permissions: {', '.join(result['permissions'])}")
else:
print(f"❌ {result['message']}")
```
### cURL
```bash
curl -X POST https://api.publora.com/api/v1/test-connection/linkedin-Tz9W5i6ZYG \
-H "x-publora-key: YOUR_API_KEY"
```
### Pre-flight Check Before Scheduling
```javascript
async function validateConnectionsBeforePost(platformIds) {
const results = await Promise.all(
platformIds.map(async (platformId) => {
const response = await fetch(
`https://api.publora.com/api/v1/test-connection/${platformId}`,
{
method: 'POST',
headers: { 'x-publora-key': process.env.PUBLORA_API_KEY }
}
);
return response.json();
})
);
const failed = results.filter(r => r.status === 'error');
if (failed.length > 0) {
console.log('⚠️ Some connections need attention:');
failed.forEach(r => console.log(` - ${r.platformId}: ${r.message}`));
return false;
}
console.log('✅ All connections healthy');
return true;
}
// Usage
const platforms = ['twitter-123', 'linkedin-ABC', 'threads-456'];
const healthy = await validateConnectionsBeforePost(platforms);
if (healthy) {
// Proceed with scheduling
}
```
### Telegram Connections
For a Telegram bot connection, the check verifies the bot token, that the bot can still read the saved channel, and that the bot is an administrator allowed to post there. A private channel without a public username returns `"username": null`.
| `status` | `message` | Meaning |
|----------|-----------|---------|
| `ok` | `Bot can post to ` | The token works and the bot is an administrator with posting rights |
| `error` | `Bot needs channel administrator posting rights` | The bot is no longer an administrator, or lost the **Post Messages** right in a channel |
| `error` | `Channel is unavailable` | The saved chat is not a channel or supergroup |
| `error` | `Invalid bot token` | Telegram answered without confirming the bot. A revoked token normally fails with `Request failed with status code 401` instead (see below) |
| `error` | `Invalid bot connection` | Not a usable bot connection (no bot token or chat ID). Every MTProto connection returns this |
Errors returned by the Telegram API itself, such as a revoked bot token or a private channel the bot was removed from, come back as `Request failed with status code `.
> **Note:** Telegram MTProto connections will always fail the test-connection check because the validator only checks bot connections. They return `"Invalid bot connection"`, but still publish normally.
### Unknown Platform
If the platform has no test-connection validator implemented (e.g., Pinterest), the endpoint returns HTTP 200 with a full response structure but error status:
```json
{
"platform": "pinterest",
"platformId": "pinterest-abc123",
"username": "unknown",
"status": "error",
"message": "Unknown platform: pinterest",
"permissions": [],
"tokenExpiresIn": null,
"lastSuccessfulPost": null,
"lastError": null
}
```
> **Note:** The public API route returns only `{ error: "Failed to test connection" }` for 500 errors without a `message` field. The internal dashboard endpoint may include an additional `message` field in error responses.
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"Invalid platformId format"` | `platformId` doesn't contain a dash or is malformed. **Note:** Parsed the same way as in `create-post`: split at the first dash (so a Telegram bot ID such as `telegram--1001234567890` is valid), with a lowercase-letter prefix; the non-empty ID may not contain whitespace, `/`, `?`, or `#`; colons are allowed. |
| 401 | `"API key is required"` | Missing `x-publora-key` header |
| 401 | `"Invalid API key"` | `x-publora-key` value is not a valid key |
| 401 | `"Invalid API key owner"` | The API key's owner account could not be found |
| 403 | `"API access is not enabled for this account"` | Account does not have API access enabled |
| 403 | `"MCP access is not enabled for this account"` | MCP access is not enabled when `x-publora-client: mcp` is sent |
| 500 | `"Internal server error"` | Unexpected error in middleware |
| 404 | `"Connection not found"` | Invalid platformId or connection doesn't exist |
| 500 | `"Failed to test connection"` | Server error during validation |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/endpoints/webhooks
# Webhooks
Receive real-time post lifecycle notifications, including scheduled, published, failed, and demotion events. `token.expiring` is defined and subscribable but is not currently dispatched, so do not depend on it for token monitoring.
## Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/webhooks` | List all webhooks |
| POST | `/webhooks` | Create a webhook |
| PATCH | `/webhooks/:id` | Update a webhook |
| DELETE | `/webhooks/:id` | Delete a webhook |
| POST | `/webhooks/:id/regenerate-secret` | Regenerate signing secret |
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `x-publora-key` | Yes | Your API key |
---
## List Webhooks
```
GET https://api.publora.com/api/v1/webhooks
```
### Response
```json
{
"success": true,
"webhooks": [
{
"_id": "65f8a1b2c3d4e5f6a7b8c9d0",
"name": "Production Notifications",
"url": "https://your-app.com/webhooks/publora",
"events": ["post.published", "post.failed"],
"isActive": true,
"failureCount": 0,
"lastTriggeredAt": "2026-02-22T14:30:00.000Z",
"createdAt": "2026-02-20T10:00:00.000Z",
"updatedAt": "2026-02-22T14:30:00.000Z",
"__v": 0
}
]
}
```
> **Note:** Both API and dashboard list responses may include `__v` (Mongoose version key). This field can be safely ignored.
---
## Create Webhook
```
POST https://api.publora.com/api/v1/webhooks
```
### Request Body
```json
{
"name": "Production Notifications",
"url": "https://your-app.com/webhooks/publora",
"events": ["post.published", "post.failed", "post.demoted"]
}
```
### Response
```json
{
"success": true,
"webhook": {
"_id": "65f8a1b2c3d4e5f6a7b8c9d0",
"name": "Production Notifications",
"url": "https://your-app.com/webhooks/publora",
"events": ["post.published", "post.failed", "post.demoted"],
"secret": "a1b2c3d4e5f6...your-signing-secret...x9y0z1",
"isActive": true,
"createdAt": "2026-02-22T10:00:00.000Z"
}
}
```
> **Note:** The Create Webhook endpoint returns HTTP **201 (Created)**, not 200.
> **Important:** The `secret` is only returned once when creating the webhook. Store it securely for signature verification.
### Available Events
| Event | Description |
|-------|-------------|
| `post.scheduled` | Post was scheduled |
| `post.published` | Post was successfully published |
| `post.failed` | Post failed to publish |
| `post.demoted` | A scheduled post was returned to draft, after a media change or when a check before publishing failed (not emitted by `attach-media`) |
| `token.expiring` | Defined and subscribable, but not currently dispatched; do not build flows that depend on it |
---
## Update Webhook
```
PATCH https://api.publora.com/api/v1/webhooks/:id
```
### Request Body
```json
{
"name": "Updated Name",
"url": "https://new-url.com/webhook",
"events": ["post.failed"],
"isActive": false
}
```
All fields are optional. Only provided fields will be updated.
> **Note:** The API uses truthy checks on `name`, `url`, and `events`. Passing an empty string `""` for any of these fields will be silently ignored (not treated as an update). Only non-empty values trigger updates.
> **Note:** The `isActive` field requires a strict boolean type (`typeof isActive === "boolean"`). Passing a string like `"false"` or `"true"` will be silently ignored — only literal `true` or `false` values are accepted.
### Response
```json
{
"success": true,
"webhook": {
"_id": "65f8a1b2c3d4e5f6a7b8c9d0",
"name": "Updated Name",
"url": "https://new-url.com/webhook",
"events": ["post.failed"],
"isActive": false,
"updatedAt": "2026-02-22T15:00:00.000Z"
}
}
```
---
## Delete Webhook
```
DELETE https://api.publora.com/api/v1/webhooks/:id
```
### Response
```json
{
"success": true
}
```
---
## Regenerate Secret
```
POST https://api.publora.com/api/v1/webhooks/:id/regenerate-secret
```
### Response
```json
{
"success": true,
"secret": "new-secret-here..."
}
```
---
## Dashboard vs API Differences
Webhook management has two implementations: the **public API** (`/api/v1/webhooks`) and a **dashboard route** (`/webhooks`). They share the same underlying data but differ in several behaviors:
| Behavior | API (`/api/v1/webhooks`) | Dashboard (`/webhooks`) |
|----------|--------------------------|-------------------------|
| **Create error (invalid events)** | Returns a flat `{ "error": "Invalid events" }` — submitted event names are **not** echoed back (to avoid leaking admin-only event names to non-admin probes). | Error echoes the invalid event names: `"Invalid events: foo"` |
| **Update field checks** | Uses truthy checks on `name`/`url`/`events` — empty string `""` is silently ignored | Uses `!== undefined` checks — empty string is treated as a value |
| **`isActive` type check** | Requires strict boolean (`typeof isActive === "boolean"`) — strings like `"false"` are silently ignored | Uses `isActive !== undefined` — accepts any truthy/falsy value |
| **Re-enable webhook** | Sets `isActive: true` but does **not** reset `failureCount` | Sets `isActive: true` **and** resets `failureCount` to 0 |
| **List response** | Excludes `userId` and `secret` from response; does **not** sort by `createdAt`; may include `__v` (Mongoose version key) | Excludes only `secret` from response; sorts by `createdAt` descending |
| **URL validation error** | Returns `"URL must use HTTPS"` for non-HTTP/HTTPS protocols | Returns `"Only HTTP and HTTPS URLs are allowed"` for non-HTTP/HTTPS protocols |
| **Update response fields** | Update response omits `failureCount` and `lastTriggeredAt` | Update response includes `failureCount` and `lastTriggeredAt` |
| **`::1` / `.localhost` blocking** | Does **not** block `::1` (IPv6 loopback) or `.localhost` subdomains | Blocks both `::1` and `.localhost` subdomains |
> **Tip:** If you need to fully reset a webhook's failure state through the API, delete and recreate it. The dashboard UI handles this automatically.
---
## Webhook Payload
> **Note:** The webhook delivery system operates as a separate internal service. The behavior described in the Webhook Payload, Signature Verification, and Webhook Reliability sections below reflects the production implementation.
When an event occurs, Publora sends a POST request to your webhook URL:
### Headers
| Header | Description |
|--------|-------------|
| `Content-Type` | `application/json` |
| `X-Publora-Signature` | HMAC-SHA256 signature of the payload |
| `X-Publora-Event` | Event type (e.g., `post.published`) |
### Payload Structure
```json
{
"version": "1",
"event": "post.published",
"timestamp": "2026-02-22T14:30:00.000Z",
"data": {
"postId": "507f1f77bcf86cd799439012",
"postGroupId": "507f1f77bcf86cd799439011",
"platform": "linkedin",
"platformId": "ABC123",
"postedId": "urn:li:share:7654321",
"permalink": null,
"publishedAt": "2026-02-22T14:30:00.000Z"
}
}
```
`version` is currently the string `"1"`. The HMAC covers the raw bytes of this complete envelope: `{ version, event, timestamp, data }`.
### Event-Specific Data
#### post.scheduled
```json
{
"postGroupId": "507f1f77bcf86cd799439011",
"scheduledTime": "2026-02-23T09:00:00.000Z",
"platforms": ["linkedin-ABC123", "twitter-123456789"]
}
```
#### post.demoted
```json
{
"postGroupId": "507f1f77bcf86cd799439011",
"reason": "media_changed",
"changeType": "attach",
"mediaFileId": "507f1f77bcf86cd799439013"
}
```
The event is emitted when a scheduled group is returned to draft. `reason` says why, and `changeType` names the trigger:
| `changeType` | `reason` | Trigger |
|--------------|----------|---------|
| `attach` | `media_changed` | Media added with [`get-upload-url`](./upload-media.md) (MCP `get_upload_url`) or uploaded in the Publora dashboard |
| `detach` | `media_changed` | Media deleted with `DELETE /media/:mediaId` (MCP `delete_media`) or in the dashboard |
| `prune_reference` | `media_changed` | A stale media reference removed with `DELETE /post/:postGroupId/media/:mediaId` (MCP `prune_media_reference`) or in the dashboard |
| `reorder` | `media_changed` | Media reordered in the Publora dashboard. This payload has no `mediaFileId` |
| `scheduler_media_backstop` | `media_backstop` | The media check made just before publishing found an attached file that cannot be published. `mediaFileId` names the file, and `errorCode` carries the media code, such as `MEDIA_REFERENCE_MISSING` or `MEDIA_VALIDATION_FAILED` |
| `scheduler_state_repair` | `state_mismatch` | Publishing found the group in an inconsistent state (a scheduled group that still held a draft platform post) and returned it to draft. `mediaFileId` is `null` |
The last two payloads come from the publishing scheduler and always carry `mediaFileId` (`null` when there is none), `errorCode` (`null` when there is none) and `demotedAt`, the ISO 8601 time of the demotion. More `changeType` and `reason` values may be added: treat an unknown value as a generic demotion and re-read the post with `GET /get-post`.
[`attach-media`](./attach-media.md) also leaves a scheduled post in draft, but it does so by setting the status explicitly and does not emit this event.
#### post.published
```json
{
"postId": "507f1f77bcf86cd799439012",
"postGroupId": "507f1f77bcf86cd799439011",
"platform": "linkedin",
"platformId": "ABC123",
"postedId": "urn:li:share:7654321",
"permalink": null,
"publishedAt": "2026-02-22T14:30:00.000Z"
}
```
| Field | Type | Description |
|-------|------|-------------|
| `postId` | string | Publora's ID for the individual platform post |
| `postGroupId` | string | Publora's ID for the parent post group |
| `platform` | string | Platform name (e.g., `linkedin`) |
| `platformId` | string/null | Raw platform account ID the post was published to — `null` when absent |
| `postedId` | string/null | **The platform's own ID for the live post** — use this to map the event to the real post on the platform |
| `permalink` | string/null | Public URL of the published post — `null` when unavailable |
| `publishedAt` | string | ISO-8601 timestamp of when the event was emitted |
> **Stable shape:** all seven keys are **always present** on `post.published`. Unavailable values are explicitly `null` rather than omitted, so no existence checks are needed. This holds on both delivery paths — the normal publish path and the recovered/reconciled publish path (where the scheduler re-emits a success it had already committed).
> **`permalink` is not yet populated.** The field is delivered on every `post.published` event, but is currently `null` for essentially all posts pending a separate backfill. If you need the live post today, resolve it from `platform` + `platformId` + `postedId`.
> **Publication identity:** `post.published` previously carried only Publora-internal IDs (`postId`, `postGroupId`), which gave receivers no way to locate the actual live post on the platform. `platformId`, `postedId` and `permalink` close that gap.
#### post.failed
```json
{
"postId": "507f1f77bcf86cd799439012",
"postGroupId": "507f1f77bcf86cd799439011",
"platform": "threads",
"error": {
"code": "PLATFORM_AUTH_EXPIRED",
"message": "Token expired"
},
"failedAt": "2026-02-22T14:30:00.000Z"
}
```
#### token.expiring
> **Planned shape:** this event is defined and can be selected when creating a webhook, but no production code currently dispatches it. Do not depend on receiving it.
```json
{
"platform": "instagram",
"platformId": "instagram-17841412345678",
"username": "yourinstagram",
"expiresAt": "2026-02-25T08:00:00.000Z"
}
```
---
## Signature Verification
Verify webhook authenticity using HMAC-SHA256:
### Node.js
```javascript
const crypto = require('crypto');
function verifyWebhookSignature(rawBody, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Express middleware
app.post('/webhooks/publora', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-publora-signature'];
const event = req.headers['x-publora-event'];
if (!verifyWebhookSignature(req.body, signature, process.env.PUBLORA_WEBHOOK_SECRET)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const payload = JSON.parse(req.body.toString('utf8'));
console.log(`Received ${event}:`, payload.data);
// Handle the event
switch (event) {
case 'post.published':
// Update your database, send notification, etc.
break;
case 'post.failed':
// Alert your team, retry logic, etc.
break;
}
res.status(200).json({ received: true });
});
```
### Python (Flask)
```python
import os
import hmac
import hashlib
from flask import Flask, request, jsonify
app = Flask(__name__)
WEBHOOK_SECRET = os.environ['PUBLORA_WEBHOOK_SECRET']
def verify_signature(raw_body, signature, secret):
expected = hmac.new(
secret.encode(),
raw_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
@app.route('/webhooks/publora', methods=['POST'])
def handle_webhook():
signature = request.headers.get('X-Publora-Signature')
event = request.headers.get('X-Publora-Event')
raw_body = request.get_data()
if not verify_signature(raw_body, signature, WEBHOOK_SECRET):
return jsonify({'error': 'Invalid signature'}), 401
payload = request.get_json()
print(f"Received {event}: {payload['data']}")
if event == 'post.failed':
# Alert team about failed post
send_slack_alert(payload['data'])
return jsonify({'received': True}), 200
```
---
## Webhook Reliability
- Webhooks timeout after 10 seconds
- Each event gets one delivery attempt; failed deliveries are not retried automatically
- After 5 consecutive failures, the webhook is automatically disabled
- A successful delivery resets `failureCount`; in a concurrent in-flight race it may also restore `isActive`. An already-disabled webhook receives no further deliveries and must be re-enabled explicitly with an update request.
- Re-enable a disabled webhook by updating `isActive: true`
- **Note:** Re-enabling a webhook via the API does **not** reset `failureCount`. The counter persists, meaning the webhook may be disabled again after fewer new failures. However, re-enabling a webhook via the **dashboard** does reset `failureCount` to 0. If you need to reset the counter through the API, delete and recreate the webhook.
> **Signature verification:** Compute the HMAC-SHA256 over the exact raw request body bytes. Capture and verify the raw body before parsing JSON; parsing and re-serializing can change the signed bytes.
## Limits
- Maximum 10 webhooks per user
- URL must use HTTPS (`"URL must use HTTPS"`) — note: despite the error message text, the API actually accepts both HTTP and HTTPS URLs
- Localhost URLs are blocked (`"Localhost URLs are not allowed"` — localhost, 127.0.0.1)
- Private IP addresses are blocked (`"Private IP addresses are not allowed"` — 10.x.x.x, 172.16-31.x.x, 192.168.x.x)
- Link-local addresses are blocked (`"Link-local addresses are not allowed"` — 169.254.x.x)
- Cloud metadata endpoints are blocked (`"Cloud metadata endpoints are not allowed"`)
> **Note:** The API route does not block `::1` (IPv6 loopback) or `.localhost` subdomains. These are only blocked by the dashboard route. This is a known difference — always use HTTP or HTTPS URLs with public hostnames.
---
## Examples
### Create Webhook with cURL
```bash
curl -X POST https://api.publora.com/api/v1/webhooks \
-H "x-publora-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Webhook",
"url": "https://my-app.com/webhooks/publora",
"events": ["post.published", "post.failed"]
}'
```
### List Webhooks
```bash
curl https://api.publora.com/api/v1/webhooks \
-H "x-publora-key: YOUR_API_KEY"
```
### Delete Webhook
```bash
curl -X DELETE https://api.publora.com/api/v1/webhooks/65f8a1b2c3d4e5f6a7b8c9d0 \
-H "x-publora-key: YOUR_API_KEY"
```
---
## Errors
| Status | Error | Cause |
|--------|-------|-------|
| 400 | `"Name, URL, and at least one event are required"` | Missing required fields |
| 400 | `"Invalid URL format"` | Malformed URL |
| 400 | `"Invalid events"` | One or more submitted event names is not in the allowed-events list for this caller. Names are **not** echoed back (admin-only events would otherwise leak to non-admin probes). Applies to both create and update. |
| 400 | `"URL must use HTTPS"` | URL uses unsupported protocol (note: both HTTP and HTTPS are actually accepted) |
| 400 | `"Localhost URLs are not allowed"` | URL points to localhost or 127.0.0.1 |
| 400 | `"Private IP addresses are not allowed"` | URL points to private network (10.x, 172.16-31.x, 192.168.x) |
| 400 | `"Link-local addresses are not allowed"` | URL points to 169.254.x.x |
| 400 | `"Cloud metadata endpoints are not allowed"` | URL targets cloud metadata service |
| 400 | `"Maximum of 10 webhooks per user"` | Webhook limit reached |
| 401 | `"Invalid API key"` | Bad or missing `x-publora-key` |
| 404 | `"Webhook not found"` | Invalid webhook ID |
| 500 | `"Failed to list webhooks"` | Server error listing webhooks |
| 500 | `"Failed to create webhook"` | Server error creating webhook |
| 500 | `"Failed to update webhook"` | Server error updating webhook |
| 500 | `"Failed to delete webhook"` | Server error deleting webhook |
| 500 | `"Failed to regenerate secret"` | Server error regenerating secret |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/agency-quickstart
# Agency quickstart (Company API and MCP)
Agencies manage client posts through the **Company API** and the `company_*` MCP
tools. Each client is a **Workspace** with its own connected channels. Every call
runs with the signed-in member's own role, and Publora checks permissions in each
Workspace. The personal API (`/create-post`, MCP `create_post`) is a separate
surface: never retry a refused Company command through it.
This page walks through one post end to end: context → channels → draft → media →
client review → schedule → result and recovery.
## Access
| | REST | MCP |
|---|---|---|
| Endpoint | `https://api.publora.com/api/v1/company` | `https://mcp.publora.com/mcp` |
| Authentication | `x-publora-key: ` | `Authorization: Bearer ` or the member's Publora login |
| Client Workspace | `X-Publora-Workspace-Id` header on post, channel, media and review calls | `workspaceId` argument |
| Retry key | `Idempotency-Key` header | `idempotencyKey` argument |
| Draft fields | JSON request body | inside the `draft` argument |
| Channel key | build `platform + "-" + platformId` from each channel | returned as `channelKey` |
| Review reads | send the approval `Accept` header (step 5) | sent by the tool |
| Validation details | add `?includeValidationDetails=true` to schedule calls | always requested |
The key is the member's own Publora API key. A personal key never grants Owner
authority. MCP clients read current tool schemas from `tools/list`; the
[MCP tools reference](../mcp/tools-reference.md#company-tools-52) lists all
Company tools.
## 1. Pick the Agency and the client Workspace
```bash
curl https://api.publora.com/api/v1/company/contexts/v2 \
-H "x-publora-key: $PUBLORA_API_KEY"
```
MCP: `company_list_contexts`.
`data.accounts[]` lists each Company the member belongs to, with `id`, `kind`,
`accountRole`, `capabilities` and `workspaces[]`. Each Workspace has `id`, `name`,
`roleSlug` and `capabilities` such as `canWriteDrafts`, `canUploadMedia` and
`canScheduleOrPublish`. `data.defaultContext` is set only when exactly one
Account/Workspace pair exists.
Confirm with the user which client they mean. Never guess a Workspace or reuse one
from another conversation. Check the capability before each step instead of
retrying a refused command.
## 2. List the client's channels
```bash
curl https://api.publora.com/api/v1/company/connections \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: 64b000000000000000000201"
```
MCP: `company_list_channels` with `workspaceId`.
Channels are in `data.items[]` (`[]` when none are connected), each with `id`,
`platform`, `platformId`, `username`, `displayName` and `status`. A channel key is
`platform + "-" + platformId`, for example `linkedin-abc123`; MCP adds it as
`channelKey`. Copy it exactly. A channel with `status: "reconnect_required"` cannot
publish until the client reconnects it. `GET /platforms` (MCP
`company_get_platforms`) returns the formats and settings Company posts support.
## 3. Create the draft
```bash
curl -X POST https://api.publora.com/api/v1/company/post-groups \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: 64b000000000000000000201" \
-H "Idempotency-Key: acme-launch-draft-1" \
-H "Content-Type: application/json" \
-d '{"content": "Our new product is live.", "platforms": ["linkedin-abc123"]}'
```
The response is `201` with `data.groupId`, the post group ID used in every later
step. A draft takes no `scheduledTime` or `status`; `platforms: []` is a valid
channel-less draft. Edit it with `PATCH /post-groups/{postGroupId}`.
MCP `company_create_post` wraps the same fields in `draft`:
```json
{
"workspaceId": "64b000000000000000000201",
"idempotencyKey": "acme-launch-draft-1",
"draft": { "content": "Our new product is live.", "platforms": ["linkedin-abc123"] }
}
```
Edit with `company_update_post` (`workspaceId`, `postGroupId`, `idempotencyKey`,
`draft`). Platform options go in `platformSettings` ([Agency platform
settings](agency-platform-settings.md)); one first comment goes in `firstComment`
([Agency first comment](agency-first-comments.md)).
## 4. Attach media
Instagram, TikTok and YouTube need media before scheduling.
1. Reserve: `POST /post-groups/{postGroupId}/media/reservations` with an
`Idempotency-Key` and `{"fileName", "contentType", "sizeBytes"}` (MCP
`company_reserve_media`). The response has `mediaFileId`, `uploadUrl`,
`uploadHeaders` and `expiresAt`.
2. Upload the exact bytes with HTTP `PUT` to `uploadUrl`, sending **all**
`uploadHeaders` and **no** Publora key.
3. Complete: `POST /post-groups/{postGroupId}/media/{mediaFileId}/complete` with
`{}` and no idempotency key (MCP `company_complete_media`).
`409 AGENCY_CORE_MEDIA_UPLOAD_PENDING` means the upload is still being inspected:
retry **complete** after the `Retry-After` header, do not reserve again. After
`AGENCY_CORE_MEDIA_RESERVATION_EXPIRED`, delete the reservation and reserve again.
## 5. Client review (optional)
Request a review when the client approves posts before publishing:
```bash
curl -X POST https://api.publora.com/api/v1/company/post-groups/$POST_GROUP_ID/approval \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: 64b000000000000000000201" \
-H "Idempotency-Key: acme-launch-review-1" \
-H "Content-Type: application/json" \
-d '{"managerComment": "Launch post for Thursday", "scheduledTime": "2026-11-20T09:00:00.000Z"}'
```
MCP: `company_request_post_approval`.
- The response contains `data.reviewUrl`, a private review page valid until
`data.expiresAt` (30 days). Publora does not send it to the client: deliver it
yourself, treat it as a bearer credential and keep it out of logs.
- When the client decides, Publora emails the user who requested the review. If
`notificationStatus` is `failed`, retry with `POST .../approval/notification`
(MCP `company_retry_approval_notification`).
- Save all edits and complete media first. The command needs
`canScheduleOrPublish`; both fields are optional.
- With a future `scheduledTime` (UTC, with milliseconds), the post is **scheduled
automatically once approved**: do not schedule it again. If that time passes
before the decision, the post stays a draft and needs a new time.
- Without `scheduledTime`, the approved post stays a draft until you schedule it.
- While a review is requested, the post can be scheduled only with the client's
current approval. Changing text, channels, media or settings invalidates it;
request a new round. `DELETE .../approval` (MCP `company_cancel_post_approval`)
removes the requirement; use it only when the user asks.
- REST reads of the review (`GET .../approval`, or post reads with
`includeApproval=true`) need
`Accept: application/vnd.publora.company-approval.v2+json, application/json`.
Without it, `GET .../approval` returns
`409 COMPANY_APPROVAL_CLIENT_UPDATE_REQUIRED` for declined and timed reviews,
and post reads leave out a declined review. MCP sends the header itself.
## 6. Schedule
```bash
curl -X POST "https://api.publora.com/api/v1/company/post-groups/$POST_GROUP_ID/schedule?includeValidationDetails=true" \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: 64b000000000000000000201" \
-H "Idempotency-Key: acme-launch-schedule-1" \
-H "Content-Type: application/json" \
-d '{"scheduledTime": "2026-11-20T09:00:00.000Z"}'
```
MCP: `company_schedule_post`. The body is exactly `{"scheduledTime"}` in UTC. To
publish now, schedule at the current UTC time and keep that same time on retries.
Confirm text, channels, client and time with the user first. Change the time with
`/reschedule` or return the post to a draft with `/unschedule` (MCP
`company_reschedule_post`, `company_unschedule_post`).
## 7. Check the result and recover failures
Scheduling only queues the post; delivery is asynchronous.
`GET /post-groups/{postGroupId}` (MCP `company_get_post`) returns the group in
`data.group` and each target in `data.posts[]`, each with its `status`.
For failed targets, `POST /post-groups/{postGroupId}/recover` with `{}` and an
`Idempotency-Key` (MCP `company_recover_post`) creates a **new draft**, returned as
`data.groupId`, with only the failed targets and their media. Published parts are
never sent again. Inspect the new draft before scheduling it.
## Retries
These commands need an idempotency key: draft create, update and delete; schedule,
reschedule, unschedule and recover; media reservation; requesting or cancelling a
client review; channel disconnect; Workspace create, rename and archive; ownership
transfer; webhook changes. Completing or deleting media, retrying a review
notification and connection-link commands take no key.
After a lost response, retry with the **same key, body and time**, then read the
resource. `409 AGENCY_CORE_IDEMPOTENCY_IN_FLIGHT` means the first request is still
running: wait for `Retry-After` and retry unchanged.
`409 AGENCY_CORE_IDEMPOTENCY_KEY_CONFLICT` means the key was used for a different
request. A new intended operation gets a new key.
## Errors
Company commands return `{"success": false, "code", "message"}`; API-key
authentication failures return `{"error"}`. `402 COMPANY_BILLING_REQUIRED` means
the Agency's billing does not allow the command: tell the user instead of retrying.
See [Error handling](error-handling.md) for HTTP status handling.
## Corporate accounts
A Corporate account (`kind: "team"`, `presentationMode: "people"`) has
`workspaces: []`: it has no client Workspaces, channels or reviews in the Company
API. Corporate employees publish their own posts through the personal API or MCP
tools.
## Related guides
- [Agency platform settings](agency-platform-settings.md): formats, media rules and per-platform options
- [Agency first comment](agency-first-comments.md)
- [Agency LinkedIn Page reshares](agency-linkedin-reshares.md)
- [Agency LinkedIn Page reads](agency-linkedin-page-reads.md)
- [Agency webhooks](agency-webhooks.md)
- [MCP tools reference](../mcp/tools-reference.md#company-tools-52)
---
> Source: https://docs.publora.com/guides/agency-platform-settings
# Agency publishing formats and settings
Agency client posts use the Company API at `https://api.publora.com/api/v1/company`
and the `company_*` MCP tools. Discover available formats with
`GET /api/v1/company/platforms` or `company_get_platforms` before using
these settings. The returned registry is authoritative
for your environment.
Use `company_list_contexts` and `company_get_workspace_context` to choose an accessible Company and Workspace, then
`company_list_channels` to copy each exact `channelKey`. API requests use
`x-publora-key` and the selected `X-Publora-Workspace-Id`; MCP commands take
`workspaceId`. Permissions follow the caller's current Workspace role.
Personal post tools and personal upload endpoints do not access Agency posts.
## Save platform settings
Create a draft with `POST /api/v1/company/post-groups`; update it with
`PATCH /api/v1/company/post-groups/:postGroupId`. Send JSON and a stable
`Idempotency-Key`: choose a unique key for each new intended change and keep it
only for retries of the identical request. The MCP equivalents are `company_create_post` and
`company_update_post`, with fields inside `draft` and top-level `workspaceId`,
`idempotencyKey` and, for updates, `postGroupId`.
`platformSettings` replaces the complete settings map. Preserve settings for the
other selected platforms when changing one. Only selected platforms may carry
settings; unknown fields and nested properties are rejected. Drafts may be
incomplete; scheduling validates the full saved post and ready uploaded media.
| Platform | Company settings | Rules |
| --- | --- | --- |
| Instagram | `videoType`: `REELS` or `STORIES`, `coverUrl`, `shareToFeed`, `aiGenerated` | A Story requires exactly one image or one video; captions are omitted. Reels accept a public JPEG cover URL and feed sharing. Image albums remain feed posts. `aiGenerated` adds Instagram's "AI info" label, which cannot change after publishing. |
| Threads | `replyControl`: `everyone`, `accounts_you_follow`, `mentioned_only` or empty | Empty uses the provider default. Reply controls do not enable post chains. |
| LinkedIn | `repostEnabled`, `repostParentUrn`, `repostVisibility` | Use a canonical `urn:li:share:…` or `urn:li:ugcPost:…`. Commentary is optional and media is forbidden. Visibility is `PUBLIC`, `CONNECTIONS` or empty; Pages require `PUBLIC`. |
| TikTok | `commercialContent`, `brandOrganic`, `brandedContent`, `autoAddMusic`, `aiGenerated` | All are booleans. Commercial content requires your brand, a paid partnership, or both. Paid partnerships cannot use `SELF_ONLY`. Automatic music can be enabled for photo Direct Post only. `aiGenerated` adds TikTok's AI-generated label. Existing creator privacy and interaction options still apply; scheduling requires `viewerSetting`. |
| YouTube | `tags`, `playlist`, `thumbnail`, `aiGenerated` | Tags are a string array. Playlist and thumbnail references use the exact objects below. `aiGenerated` sets `status.containsSyntheticMedia`. |
| X | `aiGenerated` | Boolean. Sent as `made_with_ai` only when the post attaches media, on the head tweet of a thread. Replies and quotes remain personal-API only. |
YouTube tags are trimmed and limited to 500 characters in total, including commas
and quotation marks around tags containing spaces. A playlist is
`{id:"PL…",platformId:"youtube-CHANNEL_ID"}`: select exactly one YouTube channel
and use its complete channel key. IDs are at most 200 characters and channel keys
at most 300. Send `{id:"",platformId:""}` to clear it. Choose a new playlist when
changing the YouTube channel.
A thumbnail is `{mediaId:"24_HEX_MEDIA_ID"}` belonging to this draft and Workspace.
Send `{mediaId:""}` to clear it. External URLs and personal media IDs are rejected.
Playlist addition and thumbnail setting run after video processing and are best
effort: a failure of either does not republish a successfully uploaded video.
Example: an Instagram Story draft, followed by the ordinary Company media upload
flow for a single image or video. Set `STORY_CREATE_KEY` once for this new draft;
when retrying, keep its value and rerun only the curl command:
```bash
STORY_CREATE_KEY="$(uuidgen)"
curl -X POST 'https://api.publora.com/api/v1/company/post-groups' \
-H 'x-publora-key: sk_YOUR_API_KEY' \
-H 'X-Publora-Workspace-Id: YOUR_WORKSPACE_ID' \
-H "Idempotency-Key: $STORY_CREATE_KEY" \
-H 'Content-Type: application/json' \
-d '{"platforms":["instagram-YOUR_ACCOUNT_ID"],"platformSettings":{"instagram":{"videoType":"STORIES"}}}'
```
For a Reel, set the cover and feed sharing in the same draft settings map:
```json
{
"platformSettings":{
"instagram":{
"videoType":"REELS",
"coverUrl":"https://cdn.example.com/covers/reel.jpg",
"shareToFeed":false
}
}
}
```
`coverUrl` is trimmed, limited to 2,048 characters and must be a publicly reachable
HTTP(S) JPEG URL. An empty string clears the custom cover. Extensionless CDN URLs
are accepted; URLs with a known non-JPEG image suffix are rejected. Instagram
fetches the cover when publishing, so keep it accessible until then. The Company
API does not expose the personal cover-upload endpoint; supply your own public
JPEG URL. Omitted `shareToFeed` means `true`; set `false` to publish only as a Reel.
Both options apply only to Reel videos and are ignored for Stories and feed images.
A LinkedIn repost can have empty content and no attachments:
```json
{
"content":"",
"platforms":["linkedin-YOUR_ACCOUNT_ID"],
"platformSettings":{
"linkedin":{
"repostEnabled":true,
"repostParentUrn":"urn:li:share:123456789",
"repostVisibility":"PUBLIC"
}
}
}
```
Supplying a LinkedIn parent without `repostEnabled` infers repost mode. Explicitly
setting `repostEnabled:false` with a nonempty parent, or `repostEnabled:true`
without one, is invalid. To reshare a post of a connected Company Page, find its
`postedId` with `POST /api/v1/company/linkedin-page-posts` and optionally save the
returned `sourceSnapshot` as top-level `repostSourceSnapshot` for the client
review; see [Agency LinkedIn Page reshares](agency-linkedin-reshares.md). For TikTok,
a true disclosure category infers `commercialContent:true` when that flag is
omitted; an explicit false flag with a true category is invalid.
## TikTok automatic photo music
Opt in on a photo draft through REST with:
```json
{"platformSettings":{"tiktok":{"viewerSetting":"PUBLIC_TO_EVERYONE","autoAddMusic":true}}}
```
For `company_create_post`/`company_update_post`, place this settings object inside
`draft`. TikTok will automatically choose the music. You cannot select or preview
a specific track in Publora. Explicit `false` is preserved and sent for photos;
omission preserves existing behavior and does not silently enable music.
Company updates replace the full settings map, so retain any other desired
settings. Draft saving, loading, editing, duplication and scheduling preserve
the value.
Attaching known video/document media automatically clears a previously enabled
photo-music setting.
Only JSON booleans are accepted; strings, numbers and `null` fail validation.
Enabling the setting for known non-photo media fails validation. Send `false`
to disable music when switching a draft to video. Incomplete drafts without
media are allowed. The publisher sends an explicit value as `post_info.auto_add_music`
only for photo Direct Post and never in video requests. No additional OAuth
scope is needed. See [TikTok automatic photo music](../platforms/tiktok.md#automatic-music-for-photo-posts).
Changing this setting invalidates an existing client approval. Request approval
of the changed draft before scheduling/publishing when review is required.
## AI-generated content disclosure
Instagram, TikTok, YouTube and X accept the optional boolean `aiGenerated`
(default `false`) to self-disclose realistic AI-generated or AI-altered media:
```json
{"platformSettings":{"instagram":{"aiGenerated":true},"tiktok":{"viewerSetting":"PUBLIC_TO_EVERYONE","aiGenerated":true},"youtube":{"aiGenerated":true},"twitter":{"aiGenerated":true}}}
```
For `company_create_post`/`company_update_post`, place the settings object inside
`draft`. Only JSON booleans are accepted; strings, numbers and `null` fail with
`400 AGENCY_CORE_CONTENT_INPUT_INVALID`. `twitter` accepts no other Company
setting: `replyTo` and `quoteTweet` remain personal-API only. Company updates
replace the full settings map, so retain the other desired settings.
The publisher sends Instagram `is_ai_generated` on the published container (the
carousel parent, never its children), TikTok `is_aigc`, YouTube
`status.containsSyntheticMedia` and X `made_with_ai` (only when the post attaches
media, on the head tweet of a thread). Instagram cannot change the label after
publishing. Each platform publishes its own disclosure rules; Publora forwards the
flag and does not detect AI content. See
[AI-Generated Content Disclosure](../endpoints/create-post.md#ai-generated-content-disclosure).
Changing this setting invalidates an existing client approval. Request approval
of the changed draft before scheduling/publishing when review is required.
## Upload an Agency YouTube thumbnail
1. Save a draft with its selected YouTube channel and video.
2. Reserve an auxiliary image at
`POST /api/v1/company/post-groups/:postGroupId/media/reservations`, using the
Company headers and a stable `Idempotency-Key`:
```json
{
"fileName":"thumbnail.png",
"contentType":"image/png",
"sizeBytes":24576,
"type":"image",
"purpose":"youtube_thumbnail"
}
```
3. PUT the exact bytes to the returned `uploadUrl`, using **all** `uploadHeaders`
and **no** Publora API key. JPEG or PNG is required, at most 2 MiB and at least
640×360 pixels. Your YouTube channel must be eligible for custom thumbnails.
4. Complete with
`POST /api/v1/company/post-groups/:postGroupId/media/:mediaFileId/complete`
and `{}`. Completion uses the same Company headers and no idempotency key.
A pending result means retry completion for the same reservation.
5. PATCH the draft's settings, preserving any other desired options:
```json
{
"platformSettings":{
"youtube":{
"privacy":"public",
"tags":["restaurant","weekly menu"],
"playlist":{"id":"PL_example","platformId":"youtube-YOUR_CHANNEL_ID"},
"thumbnail":{"mediaId":"64b000000000000000000501"}
}
}
}
```
MCP uses `company_reserve_media` with `purpose:"youtube_thumbnail"`, then
HTTP PUT, `company_complete_media`, and `company_update_post`.
Arguments are top-level; the saved thumbnail reference belongs inside
`draft.platformSettings.youtube.thumbnail.mediaId`.
The thumbnail is auxiliary: it is excluded from ordinary video/image attachments.
`GET /api/v1/company/post-groups/:postGroupId/media` includes the selected
`youtubeThumbnail` preview when present. Delete an auxiliary asset with
`DELETE /api/v1/company/post-groups/:postGroupId/media/:mediaFileId` and `{}`;
deleting the selected asset also clears its reference. Ordinary uploads omit
`purpose` and keep their existing contract. Recovering failed channels into a
new draft clears the source thumbnail reference; upload/select it on the new draft.
## Validation, approvals and retries
Publishing-affecting settings and the selected thumbnail are included in client
review. Editing the Story placement, Reels cover/feed sharing, reply audience, repost, commercial or AI-generated content disclosure, TikTok automatic photo music, tags,
playlist, thumbnail or LinkedIn source snapshot invalidates existing approval.
Finish uploads and edits before requesting a new review. Approval schedules a post
only when the review was requested with a future `scheduledTime`; otherwise the
approved post stays a draft until you schedule it.
| Response | Meaning | Action |
| --- | --- | --- |
| `400 AGENCY_CORE_CONTENT_INPUT_INVALID` | Unknown field, invalid settings shape, wrong playlist channel or untrusted thumbnail reference | Correct the draft and use a new key for the changed request. |
| `422 AGENCY_CORE_MEDIA_TYPE_MISMATCH` | Invalid reservation or uploaded thumbnail metadata | Use a JPEG/PNG within the thumbnail requirements; follow the returned media state before retrying. |
| `422 AGENCY_CORE_MEDIA_SIZE_EXCEEDED` | The file is larger than allowed (2 MiB for a thumbnail) | Reserve a smaller file. |
| `429 AGENCY_CORE_MEDIA_WORKSPACE_QUOTA_EXCEEDED` | Workspace upload budget or pending-upload limit reached | Respect `Retry-After`; complete or delete pending uploads. |
| `403 AGENCY_CORE_ACCESS_DENIED` | Workspace or role access is unavailable | Refresh Company context and select an accessible Workspace. |
| `409` Company content/media conflict | Draft or upload state changed, or the retry body differs | Refetch the current state; retry an uncertain operation with the identical body and key. |
After a lost response, retain the same workspace, resource IDs, body and
idempotency key. Never send Company requests through personal tools as a fallback.
Workspace post-event webhooks are described in [Agency webhooks](agency-webhooks.md).
X `aiGenerated` is the only X setting in this contract; Twitter replies/quotes, Threads chains and YouTube `categoryId` remain outside this extension.
See [Agency first comments](agency-first-comments.md) and the
[Agency MCP tools](../mcp/tools-reference.md#company-tools-52).
---
> Source: https://docs.publora.com/guides/agency-first-comments
# Agency first comment
Agency Workspace posts support one text comment under the Company's own
published post. Save it with the ordinary Company draft create or update
command:
- `POST /api/v1/company/post-groups`
- `PATCH /api/v1/company/post-groups/:postGroupId`
- MCP `company_create_post` or `company_update_post` with `draft.firstComment`
Use the existing Company authentication and exact
`X-Publora-Workspace-Id`. The draft field is
`firstComment: { "text": "Details: https://example.com", "platforms": ["linkedin"] }`.
`platforms` contains platform **types**, never Company channel keys; omit it
for every supported target. The same shape, 25,000-character absolute cap and
per-platform length rules as the [personal first comment](../endpoints/create-post.md#first-comment)
apply. `firstComment: null` clears it on update. A comment cannot be added after
publishing.
Read `GET /api/v1/company/post-groups/:postGroupId` or MCP `company_get_post` for the stored `firstComment` and each target's
`firstCommentResult` (`pending`, `posted`, `failed`, or `skipped`). A result can
include `commentId`, `skipReason`, and `error.outcomeUnknown`. When the outcome
is unknown, inspect the live target before any manual comment. Tenant posts
are attempted only while the target connection and Workspace policy still
authorize publishing; otherwise the comment is skipped with a reason.
Agency currently accepts **one** comment. `firstComments[]` and
`delaySeconds` apply only to personal posts.
---
> Source: https://docs.publora.com/guides/agency-linkedin-reshares
# Agency LinkedIn Page reshares
Use this flow when employees reshare a post published by their company's LinkedIn
Page from their own profiles, each after their own approval. The Page and the
employee profiles are connected channels of the same Agency Workspace. Each
employee gets a separate draft and a separate review link; no Publora account or
Agency seat is needed to approve.
Company API paths are relative to `https://api.publora.com/api/v1/company`. Send
your own `x-publora-key` and the selected `X-Publora-Workspace-Id` on every
request. Mutations need a unique `Idempotency-Key` for each intended operation;
retry an uncertain request with the identical body and key. MCP clients use the
`company_*` tools with top-level `workspaceId`.
1. Subscribe a Workspace webhook to `approval.decided`, `post.published` and
`post.failed` before requesting reviews. See [Agency webhooks](agency-webhooks.md).
2. Find the source post on the connected Company Page.
3. Create one draft per employee profile with the repost settings and the source snapshot.
4. Request a review for each draft, optionally with a publication time.
5. Distribute each review link privately and track decisions and publication results.
## Find a Company Page post
`POST /linkedin-page-posts` lists published posts authored by one connected
Company Page. It is read-only: it creates no draft, review or publication. The
MCP equivalent is `company_list_linkedin_page_posts`.
```bash
curl -X POST 'https://api.publora.com/api/v1/company/linkedin-page-posts' \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
-d '{"connectionId":"64b000000000000000000301","start":0,"count":10,"sortBy":"LAST_MODIFIED"}'
```
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionId` | string | Yes | The Company Page connection's database ID from Company `/connections` (`id` in `company_list_channels`), not a channel key, provider ID or personal connection |
| `start` | integer | No | Offset from 0 to 2147483647, default 0. Pass the previous `paging.nextStart` |
| `count` | integer | No | Page size from 1 to 100, default 10 |
| `sortBy` | string | No | `LAST_MODIFIED` (default) or `CREATED` |
No other body fields are accepted. The author is derived from the authorized
connection: you cannot select another organization, author or URL.
```json
{
"success":true,
"data":{
"connectionId":"64b000000000000000000301",
"authorUrn":"urn:li:organization:2414183",
"items":[{
"postedId":"urn:li:share:7520484550762942467",
"permalink":"https://www.linkedin.com/feed/update/urn:li:share:7520484550762942467/",
"commentary":"Company announcement",
"publishedAt":"2026-10-28T10:00:00.000Z",
"lastModifiedAt":"2026-10-28T10:00:00.000Z",
"visibility":"PUBLIC",
"feedDistribution":"MAIN_FEED",
"isReshareDisabledByAuthor":false,
"reshareParentUrn":null,
"sourceSnapshot":{
"postedId":"urn:li:share:7520484550762942467",
"commentary":"Company announcement",
"authorName":"Company Page",
"publishedAt":"2026-10-28T10:00:00.000Z",
"capturedAt":"2026-11-03T12:00:00.000Z"
}
}],
"paging":{"start":0,"count":10,"nextStart":10}
}
}
```
- `postedId` is always the listed post's own canonical `urn:li:share:…` or
`urn:li:ugcPost:…` ID. Use it as the repost parent. `reshareParentUrn` is only
metadata about a post that is itself a reshare; do not use it instead.
- Follow `paging.nextStart` with the same connection, `count` and `sortBy` until it
is `null`. A short or even empty page can still have a next page. Pagination is
LinkedIn's live offset, so deduplicate by `postedId` while posts change.
- Only published posts with canonical IDs are returned. Activity IDs are omitted
and arbitrary LinkedIn URLs are not resolved.
- `commentary` is a preview of at most 30,000 characters. Timestamps, visibility,
feed distribution, the reshare-disabled flag and the parent are `null` when
LinkedIn does not provide them. The list can include sponsored posts. Check
visibility, distribution and `isReshareDisabledByAuthor` before choosing a
source; a missing flag does not guarantee that LinkedIn accepts the reshare.
- The original can change or disappear after this read. Publication still runs the
normal LinkedIn checks.
- To re-read known posts by ID or list a post's comments and reactions, see
[Agency LinkedIn Page reads](agency-linkedin-page-reads.md).
Reading requires internal content view access in the Workspace and a Company Page
connection with a usable token. Organization posts require the Page's existing
`r_organization_social` permission.
| Status/code | Meaning | Recovery |
| --- | --- | --- |
| 400 `LINKEDIN_INVALID_REQUEST` | Unknown field or invalid `start`, `count` or `sortBy` | Correct the request. |
| 400 `LINKEDIN_COMPANY_PAGE_REQUIRED` | The connection is a personal profile, not a Company Page | Use the Page connection's ID. |
| 401 `LINKEDIN_TOKEN_EXPIRED` / `LINKEDIN_RECONNECT_REQUIRED` | The Page connection needs to be reconnected | Reconnect the Page, then retry. |
| 403 `AGENCY_CORE_ACCESS_DENIED` | No current access to this Workspace's content | Refresh context and use an accessible Workspace. |
| 404 `AGENCY_CORE_CONNECTION_NOT_FOUND` | No such LinkedIn connection in the selected Workspace | Refresh the Workspace's connections. |
| 429 `LINKEDIN_RATE_LIMITED` | LinkedIn quota or cooldown | Honor `Retry-After`. |
| 502 `LINKEDIN_INVALID_RESPONSE` | LinkedIn returned an unusable page or continuation | Retry later from the same `start`. |
| 503 `COMPANY_LINKEDIN_UNAVAILABLE` | Temporarily unavailable | Retry later. |
## Create one draft per employee
Create a separate draft for each employee with exactly one target: that employee's
personal LinkedIn channel key (`linkedin-` from the Workspace's
connections). Keep the source Page out of the targets. Commentary is optional and
media is forbidden on a repost. See
[Agency platform settings](agency-platform-settings.md) for the repost fields.
```json
{
"platforms":["linkedin-EMPLOYEE_PLATFORM_ID"],
"content":"",
"platformSettings":{
"linkedin":{
"repostEnabled":true,
"repostParentUrn":"urn:li:share:7520484550762942467",
"repostVisibility":"PUBLIC"
}
},
"repostSourceSnapshot":{
"postedId":"urn:li:share:7520484550762942467",
"commentary":"Company announcement",
"authorName":"Company Page",
"publishedAt":"2026-10-28T10:00:00.000Z",
"capturedAt":"2026-11-03T12:00:00.000Z"
}
}
```
Send it with `POST /post-groups` or update an existing draft with
`PATCH /post-groups/:postGroupId`. MCP clients put the same fields inside `draft`
of `company_create_post` / `company_update_post`.
Optional top-level `repostSourceSnapshot` shows the original post's text, author
and capture time inside the client review. Copy the finder item's `sourceSnapshot`
verbatim:
| Field | Type | Rules |
| --- | --- | --- |
| `postedId` | string | Required. Must equal `platformSettings.linkedin.repostParentUrn` |
| `commentary` | string | Required, at most 30,000 characters (may be empty) |
| `authorName` | string or null | Optional, at most 300 characters |
| `publishedAt` | string or null | Optional exact UTC ISO timestamp from the finder |
| `capturedAt` | string | Required exact UTC ISO timestamp from the finder |
Unknown fields and avatar URLs are rejected. `null` clears the snapshot. It is a
descriptive preview supplied by the draft author, not live LinkedIn data or a
publishing permission, and it does not change what is published. Changing or
clearing it invalidates an existing client approval. Changing the repost parent
or removing the LinkedIn target clears an older snapshot automatically. Save the
snapshot in your stored request plan and resend it unchanged on retries instead
of calling the finder again. Without a snapshot, the review shows the link to the
original on LinkedIn.
`GET /post-groups/:postGroupId?includeRepostSource=true` (MCP: `company_get_post`
with `includeRepostSource: true`) adds `group.repostSourceSnapshot` when a matching
snapshot is saved. Without the parameter the response is unchanged.
## Request reviews
`POST /post-groups/:postGroupId/approval` starts a new review round for the saved
draft and returns its review link (`reviewUrl`). MCP:
`company_request_post_approval`. Finish edits and media uploads first.
```bash
curl -X POST "https://api.publora.com/api/v1/company/post-groups/$POST_GROUP_ID/approval" \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: $WORKSPACE_ID" \
-H "Idempotency-Key: $REVIEW_KEY" \
-H 'Content-Type: application/json' \
-d '{"managerComment":"Please review before Tuesday","scheduledTime":"2030-12-10T09:00:00.000Z"}'
```
| Field | Type | Description |
| --- | --- | --- |
| `managerComment` | string | Optional note for the client, at most 5,000 characters |
| `scheduledTime` | string or null | Optional future UTC instant. When set, approval schedules this exact version through the normal scheduler. Omit or `null` keeps manual publication |
- With a future `scheduledTime`, the client's approval and the scheduling commit
together, with the same checks as a manual schedule. If scheduling validation
fails, the approval is not saved (`409 COMPANY_APPROVAL_SCHEDULING_FAILED`, or
`503 COMPANY_APPROVAL_SCHEDULING_UNAVAILABLE` for a temporary failure); fix the
post or channel, then the client approves again.
- If the time passes before the client approves, the approval is saved and the post
stays a draft. It is never published immediately instead. Schedule it explicitly
or request a new round with a new time.
- To change the time of a pending review, request a new round. After approval,
use the normal reschedule and unschedule operations.
- Clients can approve, decline with an optional comment, or request changes with a
required comment. Declines and change requests never schedule. Editing text,
channels, media, publishing settings or the source snapshot makes the round
outdated; request a new one.
Treat each `reviewUrl` as a bearer credential: deliver it only to its employee and
keep it out of logs and public exports. Store the mapping of employee, channel,
draft and review ID in your application.
## Track decisions and results
Approval and publication are separate states. An `approval.decided` event reports
`approved`, `declined` or `changes_requested` for one review round and carries a
stable `id` for deduplication; for a timed round it includes the publication state
at decision time. `post.published` and `post.failed` report the actual per-channel
outcome later. Deduplicate decisions by envelope `id` and publication events by
`event` + `postId`. A late event for an older round must not replace the current
round. See [Agency webhooks](agency-webhooks.md#approval-decisions).
To recover state after a missed delivery, read:
- `GET /post-groups/:postGroupId/approval` for the current round, decision and
feedback (MCP: `company_get_post_approval`).
- `GET /post-groups/:postGroupId` for scheduling and per-channel publication
results (MCP: `company_get_post`).
Clients that understand declined reviews send
`Accept: application/vnd.publora.company-approval.v2+json, application/json` on
approval reads and on list, calendar and detail reads with `includeApproval=true`.
Without it, list and detail responses omit the approval details of a declined
post, and a dedicated approval read of a declined or timed round returns
`409 COMPANY_APPROVAL_CLIENT_UPDATE_REQUIRED`. The MCP tools send the v2 header.
See also [Company MCP tools](../mcp/tools-reference.md#company-tools-52) and
[LinkedIn reshare](../endpoints/linkedin-reshare.md) for personal accounts.
---
> Source: https://docs.publora.com/guides/agency-linkedin-page-reads
# Agency LinkedIn Page reads
Read known posts, comments and reactions of a LinkedIn Company Page connected to
an Agency Workspace. All three operations are read-only: they create no draft,
review, comment or reaction, and need no `Idempotency-Key`.
| Operation | REST | MCP |
| --- | --- | --- |
| Read up to 50 posts by ID, optionally with engagement summaries | `POST /linkedin-page-posts/batch` | `company_get_linkedin_page_posts_batch` |
| List top-level comments on one post | `POST /linkedin-page-posts/comments` | `company_list_linkedin_page_post_comments` |
| List reactions on one post | `POST /linkedin-page-posts/reactions` | `company_list_linkedin_page_post_reactions` |
Company API paths are relative to `https://api.publora.com/api/v1/company`. Send
your own `x-publora-key` and the selected `X-Publora-Workspace-Id` on every
request. MCP clients pass the same fields as top-level arguments together with
`workspaceId`.
`connectionId` is the Company Page connection's database ID from Company
`/connections` (`id` in `company_list_channels`), not a channel key, provider ID or
personal connection. Post IDs are canonical `urn:li:share:…` or
`urn:li:ugcPost:…` URNs, for example the `postedId` values returned by
[`POST /linkedin-page-posts`](agency-linkedin-reshares.md#find-a-company-page-post).
Activity IDs and LinkedIn URLs are not accepted. Unknown body fields are rejected.
## Permissions
| Read | Workspace access | LinkedIn permissions of the Page connection |
| --- | --- | --- |
| Posts (batch without engagement) | Internal content view (Manager, Publisher, Contributor or Viewer) | `r_organization_social` |
| Engagement (batch with `includeEngagement`, comments, reactions) | Internal content view and analytics view (Manager, Publisher or Contributor) | `r_organization_social` and `r_organization_social_feed` |
The author is always the Page behind `connectionId`: you cannot read another
organization's posts or select an author.
If the Page connection lacks a required LinkedIn permission, the request returns
`403 LINKEDIN_INSUFFICIENT_SCOPE`. Batch reads also need a Page connection
authorized through Publora's current LinkedIn app; an older connection returns
`403 LINKEDIN_BATCH_UNAVAILABLE` before any LinkedIn call. In both cases the error
`message` contains the recovery steps. Usually it asks you to reconnect the Page:
open **Channels** in the Workspace, choose **Copy reconnect link** on the Page's
card (or ask a Workspace manager for the link), have a LinkedIn Page admin
authorize the same Page, then retry. If the message asks the Workspace manager to
contact Publora support instead, reconnecting will not help. MCP clients receive
the same message; show it to the user and wait for the reconnect before retrying.
## Read posts by ID
```bash
curl -X POST 'https://api.publora.com/api/v1/company/linkedin-page-posts/batch' \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
-d '{"connectionId":"64b000000000000000000301","postedIds":["urn:li:share:7520484550762942467","urn:li:ugcPost:7520484551723372544"],"includeEngagement":true}'
```
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionId` | string | Yes | The Company Page connection's database ID |
| `postedIds` | string[] | Yes | 1–50 share or ugcPost URNs. Duplicates are read once |
| `includeEngagement` | boolean | No | Default `false`. `true` adds comment and reaction summaries and needs analytics view access |
```json
{
"success":true,
"data":{
"connectionId":"64b000000000000000000301",
"authorUrn":"urn:li:organization:2414183",
"items":[{
"postedId":"urn:li:share:7520484550762942467",
"permalink":"https://www.linkedin.com/feed/update/urn:li:share:7520484550762942467/",
"commentary":"Company announcement",
"publishedAt":"2026-10-28T10:00:00.000Z",
"lastModifiedAt":"2026-10-28T10:00:00.000Z",
"visibility":"PUBLIC",
"feedDistribution":"MAIN_FEED",
"isReshareDisabledByAuthor":false,
"reshareParentUrn":null,
"sourceSnapshot":{
"postedId":"urn:li:share:7520484550762942467",
"commentary":"Company announcement",
"authorName":"Company Page",
"publishedAt":"2026-10-28T10:00:00.000Z",
"capturedAt":"2026-11-05T12:00:00.000Z"
},
"engagement":{
"commentsState":"OPEN",
"commentCount":12,
"topLevelCommentCount":9,
"reactions":{"LIKE":40,"PRAISE":3}
}
}],
"errors":[{
"postedId":"urn:li:ugcPost:7520484551723372544",
"source":"post",
"status":404,
"code":"LINKEDIN_NOT_FOUND"
}]
}
}
```
- Successful posts appear in `items` in request order, with the same fields and
`sourceSnapshot` as the [Page post list](agency-linkedin-reshares.md#find-a-company-page-post).
- With `includeEngagement`, each returned post also has `engagement`, or `null`
when its summary is unavailable. `commentsState` (`OPEN`, `CLOSED`,
`PROCESSING` or `DELETED`), `commentCount` and `topLevelCommentCount` are
`null` when LinkedIn does not provide them. `reactions` maps each LinkedIn
reaction type to its count.
- Each failed post is listed once per source in `errors` with `postedId`,
`source` (`post` or `engagement`), the numeric `status` and a `code`:
`LINKEDIN_TOKEN_EXPIRED` (401), `LINKEDIN_ACCESS_DENIED` (403),
`LINKEDIN_NOT_FOUND` (404), `LINKEDIN_RATE_LIMITED` (429) or
`LINKEDIN_ITEM_UNAVAILABLE`. A missing, unpublished or other author's post is
omitted from `items`. A verified post whose engagement failed stays in `items`.
- The request uses one LinkedIn Posts batch read, plus one Social Metadata batch
read for the verified posts when `includeEngagement` is `true`.
- If LinkedIn throttles some posts, the response stays HTTP 200 with the other
results, `data.retryAfter` and a `Retry-After` header in seconds. If LinkedIn
throttles every post in either batch read, the request returns
`429 LINKEDIN_RATE_LIMITED`.
## List comments or reactions
Send the same body to `/linkedin-page-posts/comments` or
`/linkedin-page-posts/reactions`.
```bash
curl -X POST 'https://api.publora.com/api/v1/company/linkedin-page-posts/comments' \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
-d '{"connectionId":"64b000000000000000000301","postedId":"urn:li:share:7520484550762942467","start":0,"count":10}'
```
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionId` | string | Yes | The Company Page connection's database ID |
| `postedId` | string | Yes | One share or ugcPost URN authored by this Page |
| `start` | integer | No | Offset from 0 to 2147483647, default 0. Pass the previous `paging.nextStart` |
| `count` | integer | No | Page size from 1 to 100, default 10 |
Publora first verifies with the Page's token that the exact post exists, is
published and is authored by the Page, then reads one page of its top-level
comments or reactions. A normal page uses these two LinkedIn calls within one
request deadline. A missing, unpublished or other author's post returns
`404 LINKEDIN_NOT_FOUND`.
```json
{
"success":true,
"data":{
"connectionId":"64b000000000000000000301",
"authorUrn":"urn:li:organization:2414183",
"postedId":"urn:li:share:7520484550762942467",
"items":[{
"commentUrn":"urn:li:comment:(urn:li:activity:7520484551000000000,7520490000000000000)",
"parentCommentUrn":null,
"actorUrn":"urn:li:person:AbC123xyz",
"message":"Congratulations to the team!",
"createdAt":"2026-10-28T11:02:00.000Z",
"lastModifiedAt":"2026-10-28T11:02:00.000Z"
}],
"paging":{"start":0,"count":10,"nextStart":null}
}
}
```
- A comment item has `commentUrn` (LinkedIn's canonical comment URN, returned
verbatim), `parentCommentUrn`, `actorUrn`, `message` (at most 30,000
characters), `createdAt` and `lastModifiedAt`.
- A reaction item has `actorUrn`, `reactionType`, `createdAt` and
`lastModifiedAt`. Reactions are ordered newest first. Current types are `LIKE`,
`PRAISE`, `EMPATHY`, `INTEREST`, `APPRECIATION` and `ENTERTAINMENT`; older
reactions can be `MAYBE`.
- Timestamps are UTC ISO strings. Missing text, actor, parent or time values are
`null`. `actorUrn` is a LinkedIn person or organization URN; person URNs are
specific to the LinkedIn app that issued them, so do not match them against IDs
from another app.
- Follow `paging.nextStart` as the next `start` with the same `count`,
connection and post until it is `null`. A full final page can be followed by an
empty one. The list can change between pages: deduplicate comments by
`commentUrn` and reactions by a non-null `actorUrn`.
- A comments read past the last comment returns an empty page after Publora
confirms the comment count with LinkedIn; if LinkedIn cannot confirm it, the
request returns `404 LINKEDIN_NOT_FOUND`.
## Errors
Errors use the Company envelope `{ "success": false, "code": "...", "message": "..." }`.
| Status/code | Meaning | Recovery |
| --- | --- | --- |
| 400 `LINKEDIN_INVALID_REQUEST` | Unknown field, invalid post IDs, `includeEngagement`, `start` or `count` | Correct the request. |
| 400 `LINKEDIN_COMPANY_PAGE_REQUIRED` | The connection is a personal profile, not a Company Page | Use the Page connection's ID. |
| 401 `LINKEDIN_TOKEN_EXPIRED` / `LINKEDIN_RECONNECT_REQUIRED` | The Page connection needs to be reconnected | Reconnect the Page, then retry. |
| 403 `AGENCY_CORE_ACCESS_DENIED` | No current access to this Workspace's content, or engagement requested without analytics view access | Refresh context; use an accessible Workspace and role. |
| 403 `LINKEDIN_BATCH_UNAVAILABLE` | Batch only: the Page connection was authorized through an older LinkedIn app | Follow the steps in `message`. |
| 403 `LINKEDIN_INSUFFICIENT_SCOPE` | The Page connection lacks a required LinkedIn read permission | Follow the steps in `message`. |
| 403 `LINKEDIN_ACCESS_DENIED` | LinkedIn refused access to the resource | Check the Page admin's access, then retry. |
| 404 `AGENCY_CORE_CONNECTION_NOT_FOUND` | No such LinkedIn connection in the selected Workspace | Refresh the Workspace's connections. |
| 404 `LINKEDIN_NOT_FOUND` | Comments/reactions: the post is missing, unpublished or not authored by this Page | Use a `postedId` from the Page's post list. |
| 429 `LINKEDIN_RATE_LIMITED` | LinkedIn quota or cooldown | Honor `Retry-After`; do not switch Workspace to bypass it. |
| 502 `LINKEDIN_INVALID_RESPONSE` | LinkedIn returned a response Publora could not verify | Retry later with the same request. |
| 5xx `LINKEDIN_TEMPORARILY_UNAVAILABLE` | The LinkedIn read failed | Retry later. |
| 503 `COMPANY_LINKEDIN_UNAVAILABLE` | Temporarily unavailable | Retry later. |
| 504 `LINKEDIN_REQUEST_TIMEOUT` | The LinkedIn read deadline elapsed | Retry with backoff. |
See also [Agency LinkedIn Page reshares](agency-linkedin-reshares.md) and
[Company MCP tools](../mcp/tools-reference.md#company-tools-52).
---
> Source: https://docs.publora.com/guides/agency-webhooks
# Agency Workspace webhooks
Use the Company surface, not the personal `/webhooks` endpoints.
A subscription belongs to one Agency Workspace. Its managers can create,
list, edit, disable, delete and rotate its signing secret. Authority is the
existing Workspace settings permission; Account membership alone is not enough.
The subscription survives removal of the teammate who created it.
## Manage subscriptions
Use your own `x-publora-key` and the selected `X-Publora-Workspace-Id` on every
request. Company API paths are relative to `https://api.publora.com/api/v1`.
All mutations require a unique `Idempotency-Key` for each intended operation.
After an uncertain response retry the identical Workspace, path, body and key.
Do not generate a new key for a retry. Permission is checked again on replay.
| Method | Path | Body |
| --- | --- | --- |
| GET | `/company/webhooks` | None |
| POST | `/company/webhooks` | `{name,url,events,isActive?}` |
| PATCH | `/company/webhooks/:webhookId` | Any nonempty subset of `{name,url,events,isActive}` |
| DELETE | `/company/webhooks/:webhookId` | `{}` |
| POST | `/company/webhooks/:webhookId/regenerate-secret` | `{}` |
Names are trimmed, nonempty and at most 100 characters. URLs are trimmed and at
most 2048 characters, using public HTTP(S). Private/local destinations are refused
and DNS is checked again at delivery. Redirects are not followed. HTTPS is
recommended. Subscribe to one to three of `post.published`, `post.failed` and
`approval.decided`; other events and duplicate event names are rejected. Existing
subscriptions are not expanded automatically. `isActive` defaults to true.
The limit is ten subscriptions per Workspace, including disabled subscriptions.
Clients that manage `approval.decided` send
`Accept: application/vnd.publora.company-webhooks.v2+json` on every Company
webhook read and mutation. Without it, the publication-only JSON shape is kept,
but a request that would create, return or replay a subscription with
`approval.decided` fails with `409 COMPANY_WEBHOOK_CLIENT_UPDATE_REQUIRED`. Once
such a subscription exists in the Workspace, this includes the list. Nothing is
dropped or relabelled. The app and the MCP tools send the v2 header.
Set this key once for this new subscription; reuse it only for identical retries:
```bash
HOOK_CREATE_KEY="$(uuidgen)"
curl -X POST 'https://api.publora.com/api/v1/company/webhooks' \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: $WORKSPACE_ID" \
-H "Idempotency-Key: $HOOK_CREATE_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Client publishing","url":"https://receiver.example.com/publora","events":["post.published","post.failed"]}'
```
To also receive client review decisions, add the event and the v2 header:
```bash
HOOK_CREATE_KEY="$(uuidgen)"
curl -X POST 'https://api.publora.com/api/v1/company/webhooks' \
-H "x-publora-key: $PUBLORA_API_KEY" \
-H "X-Publora-Workspace-Id: $WORKSPACE_ID" \
-H "Idempotency-Key: $HOOK_CREATE_KEY" \
-H 'Accept: application/vnd.publora.company-webhooks.v2+json' \
-H 'Content-Type: application/json' \
-d '{"name":"Advocacy results","url":"https://receiver.example.com/publora","events":["approval.decided","post.published","post.failed"]}'
```
List returns `{success:true,data:{accountId,workspaceId,items:[...]}}`.
Create, update and rotation return
`{success:true,data:{accountId,workspaceId,webhook:{...}}}`. Create and rotation
also return sibling `data.secret`, including retries of that exact operation.
Store it securely; normal list/update responses never expose it. Rotating a
secret invalidates the previous secret for subsequent deliveries. Each webhook
DTO has `id`, `name`, `url`, `events`, `isActive`, `failureCount`,
`lastTriggeredAt` (nullable), `createdAt` and `updatedAt`.
Delete returns `{success:true,data:{accountId,workspaceId,webhookId,deleted:true}}`.
In the app, open Workspace settings and use Webhooks. MCP exposes
`company_list_webhooks`, `company_create_webhook`, `company_update_webhook`,
`company_delete_webhook` and `company_regenerate_webhook_secret`. Pass top-level
`workspaceId`, a stable `idempotencyKey` for mutations and `webhookId` for an
existing subscription. Create fields (`name`, `url`, `events`, optional
`isActive`) are top-level; update fields are nested in `changes`. A creation or rotation
secret is displayed only for the completed operation; it is not a list field.
## Events and signature verification
Publication events describe an individual platform post, not completion of the entire
multi-platform group. The destination is selected by the exact Company and
Workspace pair. Company events are never delivered to personal subscriptions,
and personal/token/billing events are never delivered to Company subscriptions.
Inactive Companies and archived Workspaces do not start new deliveries.
```json
{
"version":"1",
"event":"post.published",
"timestamp":"2026-10-22T12:00:00.000Z",
"data":{
"accountId":"64b000000000000000000101",
"workspaceId":"64b000000000000000000201",
"postId":"64b000000000000000000401",
"postGroupId":"64b000000000000000000301",
"platform":"instagram",
"platformId":"INSTAGRAM_CHANNEL_ID",
"postedId":"PROVIDER_POST_ID",
"permalink":"https://www.instagram.com/p/EXAMPLE/",
"publishedAt":"2026-10-22T12:00:00.000Z"
}
}
```
`post.failed` has the same Company/Workspace/post/group/platform/channel identity,
plus `error` and `failedAt`, instead of publication result fields. Error data
contains the publishing failure code/message and may identify an affected media
file. A provider may not supply a permalink or external post ID.
Every request carries `X-Publora-Event` and `X-Publora-Signature`. The signature
is the hex HMAC-SHA256 of the **exact raw request body bytes**, using the webhook
secret. Verify it before trusting or processing the body, with a constant-time
comparison. Do not parse and re-stringify JSON before checking the signature.
Publication events reuse the existing best-effort transport: one HTTP attempt per dispatch,
a ten-second timeout, 2xx success only and no automatic HTTP retry queue. Duplicate
dispatches are possible; process receivers idempotently using `event + postId`
(and your stored processing state), not `postGroupId` alone. There is no durable
outbox or exactly-once guarantee. After five consecutive failures, a subscription
is disabled. Re-enable it after correcting its URL/receiver; enabling resets the
failure count. A delivery already started may finish after disable, deletion or
secret rotation.
## Approval decisions
`approval.decided` reports a client's decision on one review round: `approved`,
`declined` or `changes_requested`. Requesting, expiring, cancelling or
invalidating a review emits no decision event, and an exact retry of a saved
decision emits no new event. Each review round has its own `reviewId`.
```json
{
"version":"1",
"id":"approval.4b062bc2-b366-467d-a839-8f01f7426e82",
"event":"approval.decided",
"timestamp":"2026-11-02T12:00:00.000Z",
"data":{
"accountId":"64b000000000000000000101",
"workspaceId":"64b000000000000000000201",
"postGroupId":"64b000000000000000000301",
"reviewId":"4b062bc2-b366-467d-a839-8f01f7426e82",
"decision":"approved",
"decidedAt":"2026-11-02T12:00:00.000Z",
"targets":[{"connectionId":"64b000000000000000000401","channelKey":"linkedin-employee","platform":"linkedin","platformId":"employee"}],
"publication":{"scheduledTime":"2026-11-02T12:10:00.000Z","status":"scheduled"}
}
}
```
`publication` appears only for a review requested with a `scheduledTime` and
describes the state when the decision was saved, not the current queue. An
approval is not a publication receipt: `post.published` / `post.failed` report the
outcome separately and may arrive in any order relative to the decision. The
payload contains no review link, response token, email, feedback or post content;
read the approval for feedback.
Decision delivery is durable but bounded. The decision and one delivery per
matching active subscription are saved together. The envelope, including `id` and
`timestamp`, never changes across retries. Each delivery gets up to five attempts
with delays of 1 minute, 5 minutes, 30 minutes and 2 hours, a ten-second timeout
and 2xx success; network errors and timeouts retry with the same `id`. Pending
deliveries expire after seven days. Five consecutive failures still disable the
subscription. Rotating the secret signs the next attempt with the new secret.
Changing the URL, disabling or deleting the subscription, or removing
`approval.decided` cancels its pending decision deliveries; re-enabling does not
replay them.
Verify the signature as above, then save the decision and its `id` in one
transaction before returning 2xx. A lost acknowledgement delivers the same event
again. Deduplicate decisions by envelope `id`, and keep those records longer than
the seven-day delivery window; keep publication deduplication by `event + postId`.
A late event for an older round must not replace the current round. Subscribe
before requesting reviews, and after a missed or expired delivery recover through
`GET /company/post-groups/:postGroupId/approval` (with
`Accept: application/vnd.publora.company-approval.v2+json, application/json`) and
`GET /company/post-groups/:postGroupId`. See
[Agency LinkedIn Page reshares](agency-linkedin-reshares.md) for a complete flow.
| Status/code | Meaning | Recovery |
| --- | --- | --- |
| 400 `COMPANY_WEBHOOK_INPUT_INVALID` | Invalid fields, URL, events or key | Correct the request. |
| 403 `AGENCY_CORE_ACCESS_DENIED` | Missing current Workspace settings authority | Refresh context and use an accessible Workspace. |
| 404 `COMPANY_WEBHOOK_NOT_FOUND` | No such subscription in the selected Workspace | Refresh its list. |
| 409 `COMPANY_WEBHOOK_LIMIT` | Ten subscriptions already exist | Delete an unused subscription. |
| 409 `COMPANY_WEBHOOK_IDEMPOTENCY_CONFLICT` | Key reused for a different operation | Keep the original key for its original retry; use a fresh key for a new operation. |
| 409 `COMPANY_WEBHOOK_IDEMPOTENCY_IN_FLIGHT` | Original request is still running | Respect Retry-After and retry the identical request/key. |
| 409 `COMPANY_WEBHOOK_CONFLICT` | Workspace state changed | Refresh before a new intended operation. |
| 409 `COMPANY_WEBHOOK_CLIENT_UPDATE_REQUIRED` | The request involves `approval.decided` without the v2 `Accept` header | Send `Accept: application/vnd.publora.company-webhooks.v2+json`. |
| 503 `COMPANY_WEBHOOK_UNAVAILABLE` | Dependency or transaction unavailable | Retry the identical request/key later. |
See [Agency platform settings](agency-platform-settings.md) and
[Company MCP tools](../mcp/tools-reference.md#company-tools-52).
---
> Source: https://docs.publora.com/platforms/linkedin
# LinkedIn API - Post to LinkedIn via REST API
> **Agency client posts:** use the separate [Company platform settings](../guides/agency-platform-settings.md) contract. The personal API examples below keep their existing shapes and upload workflows.
Post to LinkedIn programmatically using the Publora REST API. A simpler alternative to the LinkedIn Marketing API, LinkedIn Share API, or LinkedIn Community Management API.
## LinkedIn API Overview
Publora provides a unified REST API for professional content publishing to LinkedIn, including text posts, media attachments (images and videos), analytics retrieval (impressions, reactions, comments), reaction management, comments, and reshares (reposts). No need to manage LinkedIn OAuth flows, handle the LinkedIn API partner program requirements, or implement complex share creation endpoints.
### Why Use Publora Instead of LinkedIn Marketing API?
| Feature | Publora API | LinkedIn Marketing API |
|---------|-------------|------------------------|
| Authentication | Single API key | Complex OAuth 2.0 flow |
| API access | Instant | LinkedIn partner approval |
| Analytics | Built-in | Separate API calls |
| Multi-platform | Post to 10 platforms | LinkedIn only |
| Setup time | 5 minutes | Weeks (partner approval) |
| Reactions | Full support | Full support |
### Keywords: LinkedIn API, LinkedIn posting API, LinkedIn Share API, LinkedIn Marketing API, post to LinkedIn programmatically, LinkedIn REST API, LinkedIn developer API, LinkedIn automation API, LinkedIn content API, LinkedIn bot API, LinkedIn analytics API, LinkedIn UGC API
## Platform ID Format
```
linkedin-{profileId}
```
Where `{profileId}` is your LinkedIn profile identifier assigned during account connection via OAuth.
## Requirements
- A LinkedIn account connected via OAuth through the Publora dashboard
- API key from Publora
> **Note:** The free Starter plan includes API access (`apiAccess: true`) — API key authentication works on all standard plans.
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text | Yes | 3,000 characters |
| Images | Yes | JPEG, PNG (WebP auto-converted to JPEG), multiple supported |
| Videos | Yes | MP4 format |
| Analytics | Yes | IMPRESSION, MEMBERS_REACHED, RESHARE, REACTION, COMMENT |
| Reactions | Yes | LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT |
| Comments | Yes | Create, delete, reply (raw input up to 10,000 characters; 1,250 after mention processing) |
| Reshares (Reposts) | Yes | Immediate or scheduled, with optional commentary (3,000 characters max) |
| Mentions | Yes | @mention people and organizations |
## API Limits
### Character Limit
- **3,000 characters** maximum per post
- First 210 characters visible before "see more" is shown
### Image Limits (API)
| Property | Limit |
|----------|-------|
| Primary gate | 36,152,320 pixels (about 6048×6048); 50 MB permissive byte ceiling |
| Max count | 10 (multi-image posts) |
| Formats | JPEG, PNG, GIF, WebP (WebP images are auto-converted to JPEG before upload to LinkedIn) |
> **Note:** GIF images are passed through without conversion — if the LinkedIn API rejects a GIF, consider converting to JPEG/PNG before uploading.
> **Important:** Organic carousels (swipeable multi-image posts) are NOT supported via the API. The API only supports multi-image grid layouts. Swipeable carousels are only available for sponsored content.
### Video Limits (API)
| Property | Limit |
|----------|-------|
| Duration | 30 minutes (more than native's 15 min desktop / 10 min mobile) |
| Max size | **500 MB** (native allows 5 GB) |
| Formats | MP4 only |
### Important API Restrictions
- **Cannot mix media types**: Images cannot be combined with videos or documents in the same post
- **No organic carousels**: Swipeable multi-image posts are not available via API — only multi-image grid layout
- **Rate limit**: 200+ API calls per hour, based on user count
### Common Error Messages
| Error | Cause |
|-------|-------|
| `MEDIA_ASSET_PROCESSING_FAILED` | File too large or unsupported format |
| `Error 429` | Rate limit exceeded |
## Mentioning People and Organizations
Publora supports @mentioning LinkedIn members and organizations in your posts. When the post is published, the mention becomes a clickable link and the mentioned person/organization receives a notification.
### Mention Syntax
Use the following format in your post content:
```
@{urn:li:person:MEMBER_ID|Display Name} # Mention a person
@{urn:li:organization:ORG_ID|Company Name} # Mention an organization
```
### Examples
**Mentioning a person:**
```
Great insights from @{urn:li:person:ACoAABcD1234EfG|Serge Bulaev} on building APIs!
```
Result: `Great insights from @Serge Bulaev on building APIs!`
**Mentioning a company:**
```
Excited to work with @{urn:li:organization:107107343|Creative Content Crafts Inc}!
```
Result: `Excited to work with @Creative Content Crafts Inc!`
Both mentions will be rendered as clickable links on LinkedIn.
### How to Find LinkedIn URNs
- **Person URN**: The member ID from LinkedIn's API. The format is `urn:li:person:{member_id}`. Member IDs are typically long alphanumeric strings (e.g. `ACoAABcD1234EfG`). You can find them via LinkedIn's API (`/me` endpoint) or browser developer tools.
- **Organization URN**: Found in the company page URL or via LinkedIn's API. Format: `urn:li:organization:{numeric_id}`. Organization IDs are typically 8-digit numbers.
> **Important:** You must use a valid LinkedIn URN ID. Invalid or made-up IDs will cause a `400` error: `"Person URN ID in commentary field is invalid."` Always verify the URN before posting. See the [LinkedIn Mentions Guide](../guides/linkedin-mentions.md) for details.
### Important: Name Matching Requirements
**The display name must exactly match the name on LinkedIn** (case-sensitive):
- For **people**: Use their exact name as shown on their LinkedIn profile
- For **organizations**: Use the **exact registered company name** including suffixes like "Inc", "LLC", etc.
| Correct | Incorrect |
|---------|-----------|
| `@{urn:li:organization:98765432\|Acme Corp Inc}` | `@{urn:li:organization:98765432\|Acme Corp}` |
| `@{urn:li:person:ACoAADeFgHi5678\|John Smith}` | `@{urn:li:person:ACoAADeFgHi5678\|john smith}` |
If the name doesn't match exactly, the mention will appear as plain text instead of a clickable link.
### Code Example
**JavaScript**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Excited to collaborate with @{urn:li:person:ACoAABcD1234EfG|Serge Bulaev} on this project!',
platforms: ['linkedin-987654321']
})
});
```
**Python**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Excited to collaborate with @{urn:li:person:ACoAABcD1234EfG|Serge Bulaev} on this project!',
'platforms': ['linkedin-987654321']
}
)
```
## First Comment
Publora can post a text comment under your own post right after it publishes — pass `firstComment` to [`create-post`](../endpoints/create-post.md#first-comment) and read the outcome in [`get-post` → `posts[].firstCommentResult`](../endpoints/get-post.md#first-comment-result-postsfirstcommentresult).
- **Profiles and company Pages.** A member profile comments as the person; a Page comments as the organization (`urn:li:organization:`), which needs the Page admin permission the connection was granted at connect time — a refusal shows up as `FIRST_COMMENT_PERMISSION_REQUIRED` (reconnect the Page).
- Up to **1,250 characters**, plain text (no mentions or images — use [`POST /linkedin-comments`](../endpoints/linkedin-comments.md) once the post is live for those).
- `firstCommentResult.commentId` is the comment's `urn:li:comment:…` URN, usable with [`DELETE /linkedin-comments`](../endpoints/linkedin-comments.md).
```json
{
"content": "Three lessons from our launch week.",
"platforms": ["linkedin-Tz9W5i6ZYG"],
"scheduledTime": "2027-03-01T14:00:00.000Z",
"firstComment": { "text": "Full write-up: https://example.com/launch-week" }
}
```
## Analytics
Publora can retrieve analytics for your LinkedIn posts. Available metrics:
| Metric | Description |
|--------|-------------|
| `IMPRESSION` | Number of times the post was displayed |
| `MEMBERS_REACHED` | Unique LinkedIn members who saw the post |
| `RESHARE` | Number of times the post was shared |
| `REACTION` | Total reactions on the post |
| `COMMENT` | Number of comments on the post |
## Reactions
LinkedIn supports a richer set of reactions than a simple "like":
| Reaction | Description |
|----------|-------------|
| `LIKE` | Standard like (thumbs up) |
| `PRAISE` | Clapping hands / applause |
| `EMPATHY` | Heart / love |
| `INTEREST` | Lightbulb / insightful |
| `APPRECIATION` | Supportive |
| `ENTERTAINMENT` | Funny / laughing |
### Create a Reaction
**Endpoint:** `POST /api/v1/linkedin-reactions`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN (e.g., `urn:li:share:123` or `urn:li:ugcPost:123`) |
| `reactionType` | string | Yes | One of: `LIKE`, `PRAISE`, `EMPATHY`, `INTEREST`, `APPRECIATION`, `ENTERTAINMENT` |
| `platformId` | string | Yes | Your LinkedIn platform ID (e.g., `linkedin-ABC123`) |
**JavaScript**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-reactions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:ugcPost:7429953213384187904',
reactionType: 'INTEREST',
platformId: 'linkedin-987654321'
})
});
const data = await response.json();
// HTTP 201 Created
console.log(data);
// {
// success: true,
// reaction: {
// id: "urn:li:reaction:(urn:li:person:xxx,urn:li:ugcPost:xxx)",
// reactionType: "INTEREST",
// ...
// },
// urnTranslated: { from: "original-urn", to: "translated-urn" } // present when URN translation was needed
// }
```
> **Note:** The create reaction endpoint returns HTTP **201** (not 200). The response may include an `urnTranslated` field when the provided URN needed to be translated to a different format for the LinkedIn API.
> **Note:** POSTing a reaction that already exists returns **409** `REACTION_ALREADY_EXISTS`. Reactions are keyed by `(account, post)`, so delete the existing reaction before applying a different type.
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-reactions \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:ugcPost:7429953213384187904",
"reactionType": "INTEREST",
"platformId": "linkedin-987654321"
}'
```
### Delete a Reaction
**Endpoint:** `DELETE /api/v1/linkedin-reactions`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN |
| `platformId` | string | Yes | Your LinkedIn platform ID |
**cURL**
```bash
curl -X DELETE https://api.publora.com/api/v1/linkedin-reactions \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:ugcPost:7429953213384187904",
"platformId": "linkedin-987654321"
}'
```
> **Note:** The delete reaction response includes the `reaction` field set to `null` (not the deleted reaction type). It may also include an `urnTranslated` field (`{ from: "original-urn", to: "translated-urn" }`) when URN translation was needed.
**Response example:**
```json
{
"success": true,
"reaction": null,
"urnTranslated": { "from": "original-urn", "to": "translated-urn" }
}
```
## Comments
Publora supports creating and deleting comments on LinkedIn posts programmatically.
### Create a Comment
**Endpoint:** `POST /api/v1/linkedin-comments`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN (e.g., `urn:li:share:123` or `urn:li:ugcPost:123`) |
| `message` | string | Yes | Raw input up to 10,000 characters; after mention processing, the text sent to LinkedIn must be at most 1,250 characters |
| `platformId` | string | Yes | Your LinkedIn platform ID (e.g., `linkedin-ABC123`) |
| `parentComment` | string | No | Comment URN for nested replies |
**JavaScript**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7434685316856377344',
message: 'Great post! Thanks for sharing.',
platformId: 'linkedin-987654321'
})
});
const data = await response.json();
// HTTP 201 Created
console.log(data);
// {
// success: true,
// comment: {
// id: "7434695495614312448",
// commentUrn: "urn:li:comment:(urn:li:activity:xxx,7434695495614312448)",
// message: "Great post! Thanks for sharing.",
// ...
// }
// }
```
> **Note:** The create comment endpoint returns HTTP **201** (not 200).
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-comments \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:share:7434685316856377344",
"message": "Great post! Thanks for sharing.",
"platformId": "linkedin-987654321"
}'
```
### Delete a Comment
**Endpoint:** `DELETE /api/v1/linkedin-comments`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN the comment belongs to |
| `commentId` | string | Yes | Comment URN to delete (also accepts plain numeric IDs, e.g., `7434695495614312448`) |
| `platformId` | string | Yes | Your LinkedIn platform ID |
**JavaScript**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7434685316856377344',
commentId: 'urn:li:comment:(urn:li:activity:xxx,7434695495614312448)',
platformId: 'linkedin-987654321'
})
});
const data = await response.json();
console.log(data);
// { success: true, deleted: "urn:li:comment:(...)" }
```
**cURL**
```bash
curl -X DELETE https://api.publora.com/api/v1/linkedin-comments \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:share:7434685316856377344",
"commentId": "urn:li:comment:(urn:li:activity:xxx,7434695495614312448)",
"platformId": "linkedin-987654321"
}'
```
### Replying to a Comment
To reply to an existing comment (nested comment), include the `parentComment` parameter:
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7434685316856377344',
message: 'I agree with this point!',
platformId: 'linkedin-987654321',
parentComment: 'urn:li:comment:(urn:li:activity:xxx,7434695495614312448)'
})
});
```
## Reshare
Reshare (repost) an existing LinkedIn post to your own feed, with optional commentary. Works for both personal profile and company-page connections — the reshare is authored as the member or the organization automatically.
### Reshare a Post
**Endpoint:** `POST /api/v1/linkedin-reshare`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platformId` | string | Yes | Your LinkedIn platform ID (e.g., `linkedin-ABC123`) |
| `parent` | string | Yes | URN of the post to reshare (`urn:li:share:` or `urn:li:ugcPost:`) |
| `commentary` | string | No | Text added above the reshare (max 3,000 characters) |
| `visibility` | string | No | `PUBLIC` or `CONNECTIONS` (case-insensitive). Defaults to `PUBLIC`. `CONNECTIONS` is personal-profile-only. |
For a company-page connection, `CONNECTIONS` returns `400`: `"LinkedIn organization reposts cannot use CONNECTIONS visibility; choose PUBLIC"`.
**JavaScript**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-reshare', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-987654321',
parent: 'urn:li:share:7434685316856377344',
commentary: 'Great post! Sharing with my network.',
visibility: 'PUBLIC'
})
});
const data = await response.json();
// HTTP 201 Created
console.log(data.reshare.id); // urn:li:share:...
```
> **Note:** The reshare endpoint returns HTTP **201** (not 200). The new reshare URN is in `reshare.id`.
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-reshare \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"platformId": "linkedin-987654321",
"parent": "urn:li:share:7434685316856377344",
"commentary": "Great post! Sharing with my network."
}'
```
See the [LinkedIn Reshare endpoint reference](../endpoints/linkedin-reshare.md) for the full parameter and error details.
### Schedule a Reshare
Use [create-post](../endpoints/create-post.md#linkedin-repost-settings) with `platformSettings.linkedin.repostParentUrn` to schedule a repost for a future time. The post content becomes the reshare commentary, and media is not allowed on repost groups.
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'My commentary on this great post.',
platforms: ['linkedin-987654321'],
scheduledTime: '2026-08-01T14:00:00.000Z',
platformSettings: {
linkedin: {
repostParentUrn: 'urn:li:share:7434685316856377344',
repostVisibility: 'PUBLIC'
}
}
})
});
```
> **Note:** If the parent post was deleted, made private, or has resharing disabled, the scheduled post fails at publish time with *"LinkedIn rejected the repost — the original post may have been deleted, made private, or is not reshareable."*
## Examples
### Post a Text Update
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Excited to announce our Series A funding! We are building the future of social media management for developer teams. More details coming soon.',
platforms: ['linkedin-987654321']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Excited to announce our Series A funding! We are building the future of social media management for developer teams. More details coming soon.',
'platforms': ['linkedin-987654321']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Excited to announce our Series A funding! We are building the future of social media management for developer teams. More details coming soon.",
"platforms": ["linkedin-987654321"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Excited to announce our Series A funding! We are building the future of social media management for developer teams. More details coming soon.',
platforms: ['linkedin-987654321']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with an Image
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Our team just wrapped up an incredible hackathon weekend. Here are some highlights from the event!',
platforms: ['linkedin-987654321']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Our team just wrapped up an incredible hackathon weekend. Here are some highlights from the event!',
'platforms': ['linkedin-987654321']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Our team just wrapped up an incredible hackathon weekend. Here are some highlights from the event!",
"platforms": ["linkedin-987654321"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Our team just wrapped up an incredible hackathon weekend. Here are some highlights from the event!',
platforms: ['linkedin-987654321']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** To attach media to a LinkedIn post, first create the post, then upload media using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
### Check Post Analytics
**Endpoint:** `POST /api/v1/linkedin-post-statistics`
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN (e.g., `urn:li:share:123` or `urn:li:ugcPost:123`) |
| `platformId` | string | Yes | Your LinkedIn platform ID (e.g., `linkedin-ABC123`) |
| `queryType` | string | No | Single metric to retrieve. Valid values: `IMPRESSION`, `MEMBERS_REACHED`, `RESHARE`, `REACTION`, `COMMENT`. `ALL` is only valid when used with the `queryTypes` array parameter, not with the singular `queryType` parameter. At least one of `queryType` or `queryTypes` is required. Without this parameter (and without `queryTypes`), the API returns 400: `queryType or queryTypes is required`. |
| `queryTypes` | array of strings | No | Multiple metrics to retrieve in one request. Same valid values as `queryType`. At least one of `queryType` or `queryTypes` is required. |
> **Response format differs by request type:**
> - **Single metric** (using `queryType`): Returns `{ success: true, count: 123, cached: true/false }`
> - **Multiple metrics** (using `queryTypes`): Returns `{ success: true/false, metrics: { IMPRESSION: 4521, ... }, cached: true/false, cachedMetrics: [...], errors: [...] }`
>
> **Multi-metric response fields:**
> - `cached` (boolean): Whether any metrics were served from cache.
> - `cachedMetrics` (array): Only present when non-empty. Lists which metrics came from cache.
> - `errors` (array): Present when some metrics failed to fetch.
> - `success` is `false` when one or more metrics failed to fetch (i.e., `errors` array is non-empty). The `metrics` object is still populated with `null` for failed metrics.
**JavaScript (fetch) — multiple metrics**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7434685316856377344',
platformId: 'linkedin-987654321',
queryTypes: ['IMPRESSION', 'MEMBERS_REACHED', 'RESHARE', 'REACTION', 'COMMENT']
})
});
const analytics = await response.json();
console.log(analytics);
// {
// success: true,
// metrics: {
// IMPRESSION: 4521,
// MEMBERS_REACHED: 3200,
// RESHARE: 12,
// REACTION: 89,
// COMMENT: 15
// }
// }
```
**JavaScript (fetch) — single metric**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7434685316856377344',
platformId: 'linkedin-987654321',
queryType: 'IMPRESSION'
})
});
const analytics = await response.json();
console.log(analytics);
// { success: true, count: 4521, cached: false }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-post-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7434685316856377344',
'platformId': 'linkedin-987654321',
'queryTypes': ['IMPRESSION', 'MEMBERS_REACHED', 'RESHARE', 'REACTION', 'COMMENT']
}
)
analytics = response.json()
print(analytics)
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-post-statistics \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:share:7434685316856377344",
"platformId": "linkedin-987654321",
"queryTypes": ["IMPRESSION", "MEMBERS_REACHED", "RESHARE", "REACTION", "COMMENT"]
}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/linkedin-post-statistics', {
postedId: 'urn:li:share:7434685316856377344',
platformId: 'linkedin-987654321',
queryTypes: ['IMPRESSION', 'MEMBERS_REACHED', 'RESHARE', 'REACTION', 'COMMENT']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
```
## Additional Analytics Endpoints
Beyond post-level statistics, Publora provides additional LinkedIn analytics endpoints:
- **Followers Statistics** (`POST /api/v1/linkedin-followers`) — Retrieve follower demographics and growth data for your LinkedIn account. See the [LinkedIn Followers](../endpoints/linkedin-followers.md) endpoint docs.
- **Account Statistics** (`POST /api/v1/linkedin-account-statistics`) — Get aggregate account-level statistics including total impressions, engagement, and reach. See the [LinkedIn Statistics](../endpoints/linkedin-statistics.md) endpoint docs.
- **Profile Summary** (`POST /api/v1/linkedin-profile-summary`) — Retrieve your LinkedIn profile summary information. See the [LinkedIn Profile Summary](../endpoints/linkedin-profile-summary.md) endpoint docs.
## Platform Quirks
- **URN formats differ**: LinkedIn URLs use `urn:li:activity:xxx` but the API requires `urn:li:share:xxx` or `urn:li:ugcPost:xxx`. For posts created via Publora, use the `postedId` from the `get-post` endpoint. For external posts, you may need to look up the correct URN format.
- **WebP auto-conversion**: If you provide a WebP image URL, Publora automatically converts it to JPEG before uploading to LinkedIn. No action needed on your part.
- **3,000-character limit**: LinkedIn enforces a strict 3,000-character limit for post text. Publora will return an error if your content exceeds this.
- **Multiple images**: LinkedIn supports posting multiple images at once. They will appear as a multi-image grid layout (not a swipeable carousel — organic carousels are not supported via the API).
- **Rich text not supported via API**: LinkedIn's API does not support bold, italic, or other rich text formatting. Use plain text or Unicode characters for emphasis.
- **Analytics delay**: LinkedIn analytics may take up to 24 hours to fully populate. Querying immediately after posting will return partial data.
- **Hashtags**: LinkedIn hashtags are supported in the content body. They are treated as plain text but become clickable on the platform.
- **Reactions on external posts**: You can only react to posts visible in your LinkedIn network. Ensure your account is connected to the post author.
## Character Limits
| Element | Limit |
|---------|-------|
| Post body | 3,000 characters |
| Comment | 1,250 characters after mention processing (raw input cap 10,000; see the exact errors in [LinkedIn Comments](../endpoints/linkedin-comments.md)) |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/x-twitter
# Twitter API / X API - Post Tweets via REST API
Post to Twitter (X) programmatically using the Publora REST API. A simpler alternative to the official Twitter API v2, Tweepy, node-twitter-api-v2, or Twitter Java SDK.
## Twitter API Overview
Publora provides a unified REST API for posting tweets to X (formerly Twitter), including text posts, media attachments, images, videos, and automatic thread splitting for long-form content. No need to manage OAuth tokens, API rate limits, or complex Twitter API authentication flows.
### Why Use Publora Instead of Twitter API v2 / Tweepy / node-twitter-api-v2?
| Feature | Publora API | Twitter API v2 / Tweepy |
|---------|-------------|-------------------------|
| Authentication | Single API key | Complex OAuth 2.0 flow |
| Rate limit handling | Automatic | Manual implementation |
| Thread creation | Automatic splitting | Manual tweet chaining |
| Multi-platform | Post to 10 platforms | Twitter only |
| Setup time | 5 minutes | Hours to days |
| Pricing | API access is included on the free Starter plan; publishing to X needs Pro for new accounts | Free tier + paid tiers |
### Keywords: Twitter API, X API, post tweet API, Twitter posting API, tweet programmatically, Twitter bot API, Twitter automation API, send tweet API, Twitter REST API, Twitter developer API
## Platform ID Format
```
twitter-{userId}
```
Where `{userId}` is your X/Twitter numeric user ID assigned during account connection.
## Requirements
- An X/Twitter account connected via OAuth through the Publora dashboard
- API key from Publora
- Publora API access on any standard plan, including the free Starter plan
- A plan that allows X: Pro. New Starter accounts cannot publish to X (`403 PLATFORM_NOT_AVAILABLE`); Starter accounts that already used X before the change keep it. `allowedPlatforms` in [`GET /account-context`](../endpoints/account-context.md) shows whether your plan includes `twitter`.
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text | Yes | 280 characters (standard) / 25,000 characters (Premium and PremiumPlus) |
| Images | Yes | Up to 4 per post, auto-converted to PNG (max 1000px width) |
| Videos | Yes | MP4, MOV format |
| Threads | Yes | Auto-split with `(1/N)` markers |
## Character Counting
X has specific rules for character counting that Publora handles automatically:
- Standard characters count as 1
- Emojis count as **2 characters**
- URLs are counted by their literal length (Publora does NOT apply Twitter's 23-character URL shortening rule)
- Publora calculates the character count before posting
## Replies and Quote Posts
Set X-specific targets in `platformSettings.twitter` when creating or updating a post:
```json
{
"content": "Thanks for the mention — here is the answer.",
"platforms": ["twitter-12345678"],
"scheduledTime": "2026-08-25T14:00:00.000Z",
"platformSettings": {
"twitter": {
"replyTo": "https://x.com/customer/status/1234567890123456789",
"quoteTweet": "987654321098765432"
}
}
}
```
- `replyTo` publishes under the target post. If the content becomes a thread, the first post replies to the target and subsequent parts chain normally.
- `quoteTweet` quotes the target from the single post or the first post of a thread.
- Both fields accept a full `x.com`/`twitter.com` status URL or a bare 1–19 digit post ID. Send an empty string to clear a setting.
- `replyTo` and `quoteTweet` can be used together. Quote posts can include media.
> **Important X restriction:** self-serve X API tiers allow a programmatic reply or quote only when the target post's author **mentioned the connected account in that same post**, **quoted one of the account's posts**, or the connected account **authored the target itself**. Enterprise apps are exempt. This makes the feature suitable for inbound engagement and resurfacing your own posts, not arbitrary outreach.
Publora cannot determine this relationship during create/update validation. An accepted scheduled post can later fail permanently with `X_REPLY_NOT_AUTHORIZED` when X rejects its target; repeating it unchanged will not succeed. An inaccessible, deleted, or protected target may instead fail with `X_TARGET_REJECTED`.
## AI-Generated Media Disclosure
Set `platformSettings.twitter.aiGenerated: true` to mark the post's media as AI-generated. X shows its "Made with AI" label (`made_with_ai`):
```json
{
"content": "Concept render of the new store front.",
"platforms": ["twitter-12345678"],
"scheduledTime": "2026-11-10T14:00:00.000Z",
"mediaUrls": ["https://cdn.example.com/renders/store-front.png"],
"platformSettings": {
"twitter": { "aiGenerated": true }
}
}
```
- The flag defaults to `false` and is sent only when the post attaches media — X defines it as a media disclosure, so a text-only post is published without it.
- On a thread it rides on the head tweet, the only part that carries media.
- Disclosure is voluntary on X in general; X requires it for AI-generated videos of armed conflicts by creators in revenue sharing. Publora forwards the flag and does not detect AI content.
- REST also accepts the string encodings `"true"` / `"false"` / `"1"` / `"0"` / `"yes"` / `"no"` / `"on"` / `"off"`; MCP `create_post`/`update_post` accept JSON booleans only. On `update-post` an omitted field keeps its stored value.
- `aiGenerated` is the only `twitter` setting the Agency Company API accepts (inside `draft.platformSettings.twitter`); `replyTo` and `quoteTweet` remain personal-API only.
- The same field exists on Instagram, TikTok and YouTube — see [AI-Generated Content Disclosure](../endpoints/create-post.md#ai-generated-content-disclosure).
## Threading
When your content exceeds the character limit, Publora automatically splits it into a thread (multiple connected tweets):
### How It Works
Publora uses the official X API v2 `reply.in_reply_to_tweet_id` parameter to chain tweets together. Each subsequent tweet is posted as a reply to the previous one, creating a connected thread.
**Technical flow:**
1. First tweet is published normally via `POST /2/tweets`
2. Each subsequent tweet is published with `reply.in_reply_to_tweet_id` set to the previous tweet's ID
3. All tweets share the same `conversation_id` (equals the first tweet's ID)
### Automatic Splitting
When content exceeds the applicable account limit, Publora automatically:
- Splits at paragraph breaks (`\n\n`) when possible
- Falls back to sentence boundaries (`. `, `! `, `? `)
- Falls back to word boundaries if needed
- Adds `(1/N)` markers at the end of each tweet (e.g., `(1/3)`, `(2/3)`, `(3/3)`)
- Reserves 10 characters per tweet for the marker
> **Note:** Publora auto-converts all images to PNG and resizes them to a maximum of 1000px width using sharp before uploading.
### Manual Thread Parts
You can manually define where thread breaks should occur using either method:
**Method 1: Triple dash separator**
```
This is my first tweet in the thread.
---
This is my second tweet in the thread.
---
And this is my third tweet!
```
**Method 2: Explicit markers**
```
First part of the thread [1/3]
Second part of the thread [2/3]
Third and final part [3/3]
```
When explicit markers are detected, Publora preserves them exactly as written and splits at those points. Use square brackets `[n/m]`, which is distinct from the auto-added numbering format `(1/N)` that uses parentheses.
### Media in Threads
- **Images:** Up to 4 images attached to the first tweet only
- **Video:** Single video attached to the first tweet only
- Subsequent tweets in the thread are text-only
- Images and video cannot be combined in the same tweet
- `platformSettings.twitter.aiGenerated: true` marks that head-tweet media as AI-generated (`made_with_ai`); see [AI-Generated Media Disclosure](#ai-generated-media-disclosure)
## First Comment
Pass `firstComment` to [`create-post`](../endpoints/create-post.md#first-comment) and Publora replies to your own post right after it publishes (on a thread, under the last part). Counted like a tweet: **280 weighted characters**, 25,000 only when every targeted X connection is Premium; links count as 23. The reply's tweet ID is returned in [`get-post` → `posts[].firstCommentResult.commentId`](../endpoints/get-post.md#first-comment-result-postsfirstcommentresult). Self-serve X API tiers can refuse the reply (`X_REPLY_NOT_AUTHORIZED`); the post itself is unaffected.
## Examples
### Post a Text Update
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Hello from Publora! Posting to X has never been easier.',
platforms: ['twitter-12345678']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Hello from Publora! Posting to X has never been easier.',
'platforms': ['twitter-12345678']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Hello from Publora! Posting to X has never been easier.",
"platforms": ["twitter-12345678"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Hello from Publora! Posting to X has never been easier.',
platforms: ['twitter-12345678']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with an Image
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Check out this screenshot of our new dashboard!',
platforms: ['twitter-12345678']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Check out this screenshot of our new dashboard!',
'platforms': ['twitter-12345678']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Check out this screenshot of our new dashboard!",
"platforms": ["twitter-12345678"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Check out this screenshot of our new dashboard!',
platforms: ['twitter-12345678']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** To attach media to a post, first create the post, then use the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
### Post a Thread
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `Here is a deep dive into our new feature release and what it means for developers building on our platform.
We have completely redesigned the API layer to support batch operations, real-time webhooks, and granular rate limiting. This means you can now process up to 1000 requests per minute with predictable throughput.
The new SDK is available for JavaScript, Python, and Go. Each SDK includes full TypeScript definitions, async support, and built-in retry logic. Check our docs for migration guides.`,
platforms: ['twitter-12345678']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
content = """Here is a deep dive into our new feature release and what it means for developers building on our platform.
We have completely redesigned the API layer to support batch operations, real-time webhooks, and granular rate limiting. This means you can now process up to 1000 requests per minute with predictable throughput.
The new SDK is available for JavaScript, Python, and Go. Each SDK includes full TypeScript definitions, async support, and built-in retry logic. Check our docs for migration guides."""
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': content,
'platforms': ['twitter-12345678']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Here is a deep dive into our new feature release and what it means for developers building on our platform.\n\nWe have completely redesigned the API layer to support batch operations, real-time webhooks, and granular rate limiting. This means you can now process up to 1000 requests per minute with predictable throughput.\n\nThe new SDK is available for JavaScript, Python, and Go. Each SDK includes full TypeScript definitions, async support, and built-in retry logic. Check our docs for migration guides.",
"platforms": ["twitter-12345678"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const content = `Here is a deep dive into our new feature release and what it means for developers building on our platform.
We have completely redesigned the API layer to support batch operations, real-time webhooks, and granular rate limiting. This means you can now process up to 1000 requests per minute with predictable throughput.
The new SDK is available for JavaScript, Python, and Go. Each SDK includes full TypeScript definitions, async support, and built-in retry logic. Check our docs for migration guides.`;
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content,
platforms: ['twitter-12345678']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
Publora will automatically split this into a numbered thread (e.g., `(1/3)`, `(2/3)`, `(3/3)`) at sentence boundaries.
## Platform Quirks
- **Emoji character counting**: Each emoji counts as 2 characters toward the applicable account limit. Publora accounts for this automatically.
- **PNG preferred for images**: While JPEG works, PNG images tend to render with higher quality on X due to their compression algorithm.
- **Thread numbering**: Publora adds `(1/N)` markers at the end of each tweet in a thread. This is appended after the content, so it reduces available character space by 10 characters per tweet.
- **Image auto-conversion**: Publora automatically converts all images to PNG format and resizes them to a maximum width of 1000px before uploading.
- **Rate limits**: X enforces its own rate limits. If you hit them, Publora will return the appropriate error from the X API.
- **Up to 4 images**: You can attach a maximum of 4 images to a single tweet. Attempting to attach more will result in an error.
- **Video and images are mutually exclusive**: A single tweet can contain either images or a video, but not both.
## API Limits
### Character Limit
- **Standard accounts:** 280 characters
- **Premium and PremiumPlus accounts:** 25,000 characters
- **Detection:** Publora selects the limit automatically from the connected X account's subscription type
- **Threading:** Supported when content exceeds the applicable account limit
### Image Limits
| Property | Limit |
|----------|-------|
| Max size | 5 MB |
| Max count | 4 per tweet |
| Formats | JPEG, PNG, GIF, WebP |
> **Note:** All images are automatically converted to PNG (max 1000px width) via sharp before upload, regardless of the original format. This means animated GIFs will lose their animation.
### Video Limits (API)
| Property | Limit |
|----------|-------|
| **Max duration** | **2 minutes 20 seconds (140 seconds)** |
| Max size | 512 MB |
| Formats | MP4, MOV |
> **Important:** Publora validates X videos at **140 seconds (2:20)** through the API.
**Premium users via native app:** Up to 4 hours (not available via API)
## Character Limits
| Account Type | Limit |
|-------------|-------|
| Standard | 280 characters |
| Premium and PremiumPlus | 25,000 characters |
| Thread tweet (each part) | Applicable account limit, minus `(X/N)` marker space (10 chars) |
## Rate Limits
X-side pricing and posting quotas change independently of Publora and are not a Publora contract. Consult X's current developer documentation; Publora surfaces platform rate-limit errors when X rejects a request.
## What you can't do
- **Preserve animated GIFs:** The X publish path sends every non-video media item through `sharp(...).png()` before upload. A GIF is accepted as input, but animation is lost and X receives a static PNG.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/facebook
# Facebook API - Post to Facebook Page via REST API
Post to Facebook Pages programmatically using the Publora REST API. A simpler alternative to the Facebook Graph API or Meta Marketing API.
## Facebook API Overview
Publora provides a unified REST API for publishing text posts, images (including carousels and albums), and video content to Facebook Pages. Multiple pages per account are supported. No need to manage Facebook OAuth flows, handle Graph API versioning, or set up a Meta Developer app.
### Why Use Publora Instead of Facebook Graph API?
| Feature | Publora API | Facebook Graph API |
|---------|-------------|-------------------|
| Authentication | Single API key | OAuth 2.0 flow |
| API versioning | Handled | Manual updates required |
| Multi-page support | Built-in | Manual implementation |
| Multi-platform | Post to 10 platforms | Facebook only |
| Setup time | 5 minutes | Hours (app setup) |
| Media handling | Automatic | Manual upload |
### Keywords: Facebook API, Facebook Graph API, Facebook posting API, Facebook Page API, post to Facebook programmatically, Facebook REST API, Facebook developer API, Facebook automation API, Facebook content API, Facebook bot API, Meta Graph API
## Platform ID Format
```
facebook-{pageId}
```
Where `{pageId}` is your Facebook Page ID assigned during account connection via Facebook OAuth. If you manage multiple pages, each page gets its own platform ID.
## Requirements
- A Facebook Page (not a personal profile) connected via OAuth through the Publora dashboard
- Page admin permissions granted during OAuth (OAuth scopes requested: `public_profile`, `pages_manage_posts`, `pages_show_list`, `pages_read_engagement`, `business_management`)
- API key from Publora
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text | Yes | 2,200 characters (Publora frontend limit; see note below) |
| Images | Yes | Multiple supported (carousel/album), WebP auto-converted to JPEG |
| Videos | Yes | MP4 and MOV formats |
| Multiple Pages | Yes | Each page has its own platform ID |
## Token Management
Facebook page tokens have a **59-day lifespan**. Publora automatically handles token refresh so you do not need to manually reconnect your account. However, if the refresh fails (e.g., due to permission changes on Facebook), you will need to reconnect the page through the Publora dashboard.
> **Note:** The auto-refresh mechanism is handled by a separate internal service and runs independently of the API.
## Examples
### Post a Text Update
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'We are thrilled to announce our new product launch! After months of development, we are finally ready to share what we have been building. Visit our website to learn more and sign up for early access.',
platforms: ['facebook-112233445566']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'We are thrilled to announce our new product launch! After months of development, we are finally ready to share what we have been building. Visit our website to learn more and sign up for early access.',
'platforms': ['facebook-112233445566']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "We are thrilled to announce our new product launch! After months of development, we are finally ready to share what we have been building. Visit our website to learn more and sign up for early access.",
"platforms": ["facebook-112233445566"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'We are thrilled to announce our new product launch! After months of development, we are finally ready to share what we have been building. Visit our website to learn more and sign up for early access.',
platforms: ['facebook-112233445566']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with Multiple Images
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Highlights from our company retreat last weekend! Great team, great memories.',
platforms: ['facebook-112233445566']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Highlights from our company retreat last weekend! Great team, great memories.',
'platforms': ['facebook-112233445566']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Highlights from our company retreat last weekend! Great team, great memories.",
"platforms": ["facebook-112233445566"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Highlights from our company retreat last weekend! Great team, great memories.',
platforms: ['facebook-112233445566']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** To attach media to a Facebook post, first create the post, then upload media using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
### Post to Multiple Facebook Pages
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Important announcement: Our offices will be closed on Monday for the holiday. We will resume normal business hours on Tuesday.',
platforms: [
'facebook-112233445566',
'facebook-778899001122'
]
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Important announcement: Our offices will be closed on Monday for the holiday. We will resume normal business hours on Tuesday.',
'platforms': [
'facebook-112233445566',
'facebook-778899001122'
]
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Important announcement: Our offices will be closed on Monday for the holiday. We will resume normal business hours on Tuesday.",
"platforms": [
"facebook-112233445566",
"facebook-778899001122"
]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Important announcement: Our offices will be closed on Monday for the holiday. We will resume normal business hours on Tuesday.',
platforms: [
'facebook-112233445566',
'facebook-778899001122'
]
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
## Platform Quirks
- **Pages only, not profiles**: Publora posts to Facebook Pages, not personal profiles. The Facebook API does not allow posting to personal profiles via third-party apps.
- **Multiple pages**: If you manage multiple Facebook Pages, each page is connected separately and gets its own `facebook-{pageId}` platform ID. You can post to multiple pages in a single API call.
- **WebP auto-conversion**: WebP images are automatically converted to JPEG before uploading to Facebook. No action needed on your part.
- **59-day token lifespan**: Facebook page access tokens expire after 59 days. Publora auto-refreshes these tokens, but if the refresh fails silently (e.g., due to permission changes on Facebook's side), posts will start failing without a specific token-related error. If you experience unexplained posting failures, try reconnecting the page through the Publora dashboard.
- **Album behavior**: When posting multiple images, Facebook may display them as a carousel or an album depending on the count and the viewer's device.
- **Video and images are separate**: A single post can contain either images or a video, but not both simultaneously. This is a Facebook platform limitation. Note that Publora's backend validation does **not** enforce this mixed media restriction for Facebook (it only does so for Instagram). If Facebook rejects mixed media, the error comes from the Facebook API itself, not from Publora's validation layer.
- **Multi-media code path supports images only**: The multi-media code path currently only supports multiple images (photo albums). Multiple videos in a single post are not properly supported — if you attach multiple videos, they will be processed through the photo upload path incorrectly. Use one video per post for reliable behavior.
- **Link previews**: If your text content includes a URL, Facebook will automatically generate a link preview. This is Facebook's behavior and is not controlled by Publora.
## Character Limits
| Element | Limit |
|---------|-------|
| Post body | 2,200 characters (Publora frontend limit; see note below) |
| Comment | 8,000 characters |
> **Note:** The 2,200-character limit is enforced by the Publora frontend/editor only. The API does not enforce this limit — content up to Facebook's native 63,206-character limit will be accepted.
## API Limits
These limits apply when posting via the Facebook Graph API (and by extension, Publora).
### Character Limit
- **2,200 characters** maximum for post body via the Publora frontend/editor. The API does not enforce this limit; content up to Facebook's native 63,206-character limit will be accepted.
- Posts under 80 characters get 66% more engagement
### Image Limits (API)
| Property | Limit |
|----------|-------|
| Max size | 10 MB (PNG recommended max 1 MB to avoid pixelation) |
| Max count | Up to 10 images per post |
| Formats | JPEG, PNG, GIF, BMP, TIFF, WebP, AVIF, HEIF, HEIC |
### Video Limits (API)
| Property | API Limit | Native Limit |
|----------|-----------|--------------|
| Duration | 45 minutes max | 240 min (4 hours) |
| Max size | 2 GB through the presigned API upload flow | 4 GB |
| Formats | MP4, MOV | - |
**Reels via API:**
- Duration: 90 seconds max
- Pages only (not personal profiles)
### Important API Restrictions
- **Reels can only be posted to Pages** (not personal profiles)
- **Platform-side quotas:** Account-dependent and subject to change; not a Publora numeric contract.
### Common Error Messages
| Error Code | Description |
|------------|-------------|
| `Error 1363026` | Video exceeds 45 min duration |
| `Error 1363023` | File size exceeds Facebook's 2 GB API limit |
| `Error 1363128` | Reels duration outside 3-90 second range |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/instagram
# Instagram API - Post to Instagram via REST API
> **Agency client posts:** use the separate [Company platform settings](../guides/agency-platform-settings.md) contract for Stories, Reels cover URLs and feed sharing. Agency covers use a public JPEG URL; the personal cover-upload endpoint does not accept Company posts. The personal API examples below keep their existing shapes and upload workflows.
Post to Instagram programmatically using the Publora REST API. A simpler alternative to the Instagram Graph API, Instagram Basic Display API, or Instagrapi.
## Instagram API Overview
Publora connects Instagram accounts through Instagram Login for Business and requests `instagram_business_basic` plus `instagram_business_content_publish`; personal accounts are unsupported. Whether Meta accepts a particular Creator account is determined by Meta, not Publora's code.
### Why Use Publora Instead of Instagram Graph API / Instagrapi?
| Feature | Publora API | Instagram Graph API |
|---------|-------------|---------------------|
| Authentication | Single API key | Instagram Business Login (OAuth 2.0) |
| API access | Instant | Facebook app review |
| Reels & Stories | Supported | Supported |
| Multi-platform | Post to 10 platforms | Instagram only |
| Setup time | 5 minutes | Days to weeks |
| Carousel support | Yes | Yes |
### Keywords: Instagram API, Instagram posting API, Instagram Graph API, post to Instagram programmatically, Instagram REST API, Instagram developer API, Instagram automation API, Instagram Reels API, Instagram Stories API, Instagram content API, Instagrapi alternative, Instagram bot API
## Platform ID Format
```
instagram-{accountId}
```
Where `{accountId}` is your Instagram Business account ID assigned during connection via Instagram OAuth.
## Requirements
- A professional Instagram account accepted by Meta's Instagram Login for Business flow
- Connected via Instagram OAuth through the Publora dashboard
- API key from Publora
> Publora connects Instagram accounts through Instagram Login for Business and requests `instagram_business_basic` plus `instagram_business_content_publish`; personal accounts are unsupported. Whether Meta accepts a particular Creator account is determined by Meta, not Publora's code.
## API Limits
These are critical limits specific to the Instagram Graph API (different from native app limits):
### Character Limit
- **Caption:** 2,200 characters (first 125 characters visible before "more")
### Image Limits (API)
| Limit | Value |
|-------|-------|
| Max file size | 8 MB |
| Max count (carousel) | 10 images (native app allows 20) |
| **Formats** | JPEG, PNG, WebP (WebP is auto-converted to JPEG before publishing) |
> **Warning:** You cannot mix images and videos in the same carousel via the API.
### Video Limits (API)
| Limit | Reels | Carousel Videos |
|-------|-------|-----------------|
| Max duration | **15 minutes (900 seconds)** for Reels; feed video supports up to 60 minutes (3600 seconds). | 60 seconds |
| Min duration | 3 seconds | 3 seconds |
| Max file size | 300 MB | 300 MB |
| Formats | MP4, MOV | MP4, MOV |
### Rate Limits
Instagram-side posting quotas are account-dependent, may change without notice, and are not a Publora numeric contract.
### Important API Restrictions
The following features are **not available** via the Instagram Graph API:
- Personal accounts are unsupported; account eligibility is determined by Meta's Instagram Login for Business flow
- Shopping tags
- Branded content tags
- Filters and effects
- Music/audio additions
- Mixing images and videos in carousels
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text only | No | Instagram requires at least one image or video |
| Images | Yes | JPEG, PNG, WebP (WebP auto-converted to JPEG), max 8 MB, 10 per carousel |
| Videos (Reels) | Yes | MP4/MOV, max 15 minutes (900 seconds), max 300 MB |
| Videos (Stories) | Yes | MP4/MOV, requires `videoType: "STORIES"` setting |
| Carousels | Yes | 2-10 items (API limit; native app allows 20) |
## Platform-Specific Settings
Instagram supports a `platformSettings` object to control video behavior and AI-content disclosure:
```json
{
"platformSettings": {
"instagram": {
"videoType": "REELS",
"coverUrl": "https://cdn.example.com/covers/reel-cover.jpg"
}
}
}
```
| Setting | Values | Default | Description |
|---------|--------|---------|-------------|
| `videoType` | `"REELS"`, `"STORIES"` | `"REELS"` | Determines how videos are published |
| `coverUrl` | http(s) URL string | — | Custom cover image for Reels (alias: `cover_url`). Must resolve to a **JPEG image**. Two ways to set it: (1) [upload a file](../endpoints/upload-instagram-cover.md) (JPEG/PNG/WebP, up to 8 MB — Publora hosts it and converts to JPEG) and use the returned URL, or (2) pass your own **publicly accessible** JPEG URL, which Instagram fetches server-side when the Reel is created. When set, it takes precedence over frame-based cover selection (`videoTimestamp`). Send an empty string to clear. Non-JPEG or non-http(s) URLs are rejected with `400`. Settable on both `create-post` and `update-post`. Ignored for Stories and images. |
| `aiGenerated` | boolean | `false` | Self-disclose realistic AI-generated or AI-altered video, audio or images; Instagram shows its "AI info" label (`is_ai_generated`). Sent on the container that is published — a single image or video, a Reel, a Story, or the carousel parent (never carousel children). Instagram cannot add or remove the label after publishing, so `update-post` refuses a change with `409 POST_PUBLISH_IN_PROGRESS` once publishing has started. REST also accepts `"true"`/`"false"` strings; MCP accepts booleans only. Settable on both `create-post` and `update-post`. See [AI-Generated Content Disclosure](../endpoints/create-post.md#ai-generated-content-disclosure). |
| `videoTimestamp` | number (milliseconds) | — | Dashboard-only top-level field for frame selection; it is not accepted by the REST create/update contract. Sending `thumbOffset` under `platformSettings.instagram` returns `400 PLATFORM_SETTING_UNKNOWN`. API callers should use `coverUrl`. |
## Examples
### Post with an Image
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Sunset views from the office rooftop. #startup #views',
platforms: ['instagram-11223344']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Sunset views from the office rooftop. #startup #views',
'platforms': ['instagram-11223344']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Sunset views from the office rooftop. #startup #views",
"platforms": ["instagram-11223344"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Sunset views from the office rooftop. #startup #views',
platforms: ['instagram-11223344']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** Instagram requires media on every post. First create the post, then upload media using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`. For carousels, upload multiple files to the same `postGroupId`.
### Post a Carousel
Carousels require 2-10 images. The workflow is: create a draft post, upload images, then schedule.
**JavaScript (fetch)**
```javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
// Step 1: Create a draft post (no scheduledTime)
const postResponse = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
content: '10 tips for better code reviews. Swipe through! #coding #devtips',
platforms: ['instagram-11223344']
// No scheduledTime = draft
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Upload each image (2-10 images for Instagram carousels)
const images = ['tip1.jpg', 'tip2.jpg', 'tip3.jpg'];
for (const fileName of images) {
// Get upload URL
const uploadUrlResponse = await fetch(`${BASE_URL}/get-upload-url`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
fileName,
contentType: 'image/jpeg',
type: 'image',
postGroupId
})
});
const { uploadUrl } = await uploadUrlResponse.json();
// Upload to S3
const fileBuffer = await fs.promises.readFile(`./${fileName}`);
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: fileBuffer
});
}
// Step 3: Schedule the post
await fetch(`${BASE_URL}/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-15T14:00:00.000Z'
})
});
console.log('Carousel scheduled!');
```
**Python (requests)**
```python
import requests
API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
}
# Step 1: Create a draft post (no scheduledTime)
post_response = requests.post(
f'{BASE_URL}/create-post',
headers=HEADERS,
json={
'content': '10 tips for better code reviews. Swipe through! #coding #devtips',
'platforms': ['instagram-11223344']
# No scheduledTime = draft
}
)
post_group_id = post_response.json()['postGroupId']
# Step 2: Upload each image (2-10 images for Instagram carousels)
images = ['tip1.jpg', 'tip2.jpg', 'tip3.jpg']
for file_name in images:
# Get upload URL
upload_response = requests.post(
f'{BASE_URL}/get-upload-url',
headers=HEADERS,
json={
'fileName': file_name,
'contentType': 'image/jpeg',
'type': 'image',
'postGroupId': post_group_id
}
)
upload_url = upload_response.json()['uploadUrl']
# Upload to S3
with open(f'./{file_name}', 'rb') as f:
requests.put(upload_url, headers={'Content-Type': 'image/jpeg'}, data=f.read())
# Step 3: Schedule the post
requests.put(
f'{BASE_URL}/update-post/{post_group_id}',
headers=HEADERS,
json={
'status': 'scheduled',
'scheduledTime': '2026-03-15T14:00:00.000Z'
}
)
print('Carousel scheduled!')
```
**cURL**
```bash
API_KEY="YOUR_API_KEY"
# Step 1: Create a draft post (no scheduledTime)
POST_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"content": "10 tips for better code reviews. Swipe through! #coding #devtips",
"platforms": ["instagram-11223344"]
}')
POST_GROUP_ID=$(echo "$POST_RESPONSE" | jq -r '.postGroupId')
# Step 2: Upload each image (2-10 images for Instagram carousels)
for FILE in tip1.jpg tip2.jpg tip3.jpg; do
UPLOAD_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/get-upload-url \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d "{
\"fileName\": \"$FILE\",
\"contentType\": \"image/jpeg\",
\"type\": \"image\",
\"postGroupId\": \"$POST_GROUP_ID\"
}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
curl -s -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
--data-binary @"./$FILE"
done
# Step 3: Schedule the post
curl -X PUT "https://api.publora.com/api/v1/update-post/$POST_GROUP_ID" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"status": "scheduled",
"scheduledTime": "2026-03-15T14:00:00.000Z"
}'
```
> **Note:** For immediate publishing, set `scheduledTime` a few seconds in the future — a time already in the past is clamped to server time and flagged with a `SCHEDULED_TIME_COERCED` warning (see [past scheduled times](../guides/scheduling.md#past-scheduled-times)). For more details, see the [media upload workflow](../guides/media-uploads.md).
### Post a Reel
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Behind the scenes of building our product. #buildinpublic',
platforms: ['instagram-11223344'],
platformSettings: {
instagram: {
videoType: 'REELS'
}
}
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Behind the scenes of building our product. #buildinpublic',
'platforms': ['instagram-11223344'],
'platformSettings': {
'instagram': {
'videoType': 'REELS'
}
}
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Behind the scenes of building our product. #buildinpublic",
"platforms": ["instagram-11223344"],
"platformSettings": {
"instagram": {
"videoType": "REELS"
}
}
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Behind the scenes of building our product. #buildinpublic',
platforms: ['instagram-11223344'],
platformSettings: {
instagram: {
videoType: 'REELS'
}
}
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
## Platform Quirks
- **No text-only posts**: Instagram requires at least one image or video. Attempting to post text without media will return an error.
- Publora connects Instagram accounts through Instagram Login for Business and requests `instagram_business_basic` plus `instagram_business_content_publish`; personal accounts are unsupported. Whether Meta accepts a particular Creator account is determined by Meta, not Publora's code.
- **Direct Instagram connection**: Publora connects directly to Instagram via Instagram Business Login. No Facebook Page is required.
- **Carousel limits**: Carousels require between 2 and 10 media items. A single image is posted as a regular photo post, not a carousel.
- **Reel is the default**: When posting a video, Publora defaults to publishing it as a Reel. Set `videoType: "STORIES"` to post as a Story instead.
- **Custom Reels cover**: Set `platformSettings.instagram.coverUrl` to a publicly accessible JPEG URL to control the Reel's cover/thumbnail. Instagram downloads the image itself, so private or expiring URLs will fail at publish time. See [Platform-Specific Settings](#platform-specific-settings).
- **AI-generated content**: Set `platformSettings.instagram.aiGenerated: true` for realistic AI-generated or AI-altered media so Instagram adds its "AI info" label. The label is fixed when the post is published and cannot be changed afterwards. See [Platform-Specific Settings](#platform-specific-settings).
- **Stories disappear**: Stories are ephemeral and will disappear after 24 hours. This is standard Instagram behavior.
- **Image aspect ratios**: Instagram images must be between 4:5 and 1.91:1. Scheduling rejects files outside that range with `MEDIA_ASPECT_RATIO_INVALID`; Publora does not silently crop them.
- **Caption hashtags**: Hashtags are included in the caption text. There is no separate hashtags field.
## Character Limits
| Element | Limit |
|---------|-------|
| Caption | 2,200 characters |
| Hashtags | 30 per post |
| Carousel items | 2-10 media items |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/threads
# Threads API - Post to Threads via REST API
> **Agency client posts:** use the separate [Company platform settings](../guides/agency-platform-settings.md) contract. The personal API examples below keep their existing shapes and upload workflows.
Post to Threads (by Meta) programmatically using the Publora REST API. A simpler alternative to the official Threads API or Meta Graph API for Threads.
> **Permission requirement:** Threads chains need the `threads_manage_replies` permission on the connection. Publora checks the grant when you schedule (from a per-connection cache up to five minutes old) and re-checks it against Meta immediately before publishing; a connection whose token predates that permission is rejected with `THREADS_PERMISSION_REQUIRED` **before any part is published**. Reconnect that account in Publora **Channels** and approve all requested permissions. Single posts and carousels are unaffected.
## Threads API Overview
Publora provides a unified REST API for publishing single text posts, images, videos, carousels, and multi-part chains on Threads.
### Why Use Publora Instead of Threads API / Meta Graph API?
| Feature | Publora API | Threads API (Meta) |
|---------|-------------|-------------------|
| Authentication | Single API key | Meta OAuth 2.0 flow |
| API access | Instant | Requires Meta app review |
| Multi-part thread creation | Automatic from one `content` field | Manual implementation |
| Multi-platform | Post to 10 platforms | Threads only |
| Setup time | 5 minutes | Days to weeks |
| Carousel support | Yes | Yes |
### Keywords: Threads API, Threads posting API, Meta Threads API, post to Threads programmatically, Threads REST API, Threads developer API, Threads automation API, Threads bot API, Instagram Threads API, publish to Threads API
## Platform ID Format
```
threads-{accountId}
```
Where `{accountId}` is your Threads account ID assigned during connection via Meta OAuth.
## Requirements
- A Threads account connected via Meta OAuth through the Publora dashboard
- API key from Publora
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text | Yes | 500 characters |
| Images | Yes | Up to 20 per carousel, WebP auto-converted |
| Videos | Yes | MP4, MOV formats, 1 per post (see Platform Quirks for video inside a carousel) |
| Carousels | Yes | 2-20 items; a video item behaves differently per path (see Platform Quirks) |
| Multi-part threads | Yes | 500 characters per part; automatic splits are numbered, `---` breaks are not |
| Hashtags | Yes | Maximum 1 hashtag per post |
## Threading
Threads supports multi-part chains (`supportsThreading: true`). One `create-post` call with one `content` field produces the whole chain.
### How It Works
Publora uses the official Threads API `reply_to_id` parameter to chain posts together. Each subsequent post is posted as a reply to the previous one, creating a connected thread visible on Threads.
**Technical flow:**
1. First post is published normally
2. Each subsequent post is published with `reply_to_id` set to the previous post's ID
3. All posts appear as a connected thread on Threads
### Automatic Splitting
Content over 500 characters is split into a chain instead of failing validation. Splitting prefers paragraph breaks, then line breaks, then sentence endings, then word boundaries, and cuts mid-word only as a last resort. Automatically split parts carry a ` (1/3)`-style suffix, and 10 characters of each part's 500 are reserved for it — so roughly 490 characters of your own text land in each part. Emoji and other astral characters count as **2** toward that limit.
### Controlling the split
**Method 1: Triple dash separator**
```
This is my first post in the thread.
---
This is my second post in the thread.
---
And this is my third post!
```
**Method 2: Explicit markers**
```
First part of the thread [1/3]
Second part of the thread [2/3]
Third and final part [3/3]
```
Both separators work, and both split content that would otherwise fit in a single post:
- A `---` break must sit on its own line with a newline before and after it (`\n---\n` or `\n\n---\n\n`). `---` as the very first or very last characters of `content`, or `----`, does not register.
- `[n/m]` markers must form a complete set — `[1/3]`, `[2/3]`, `[3/3]`, all sharing the same total. An incomplete or inconsistent set is ignored and the text is treated as ordinary content.
Parts you separate yourself are published **exactly as written — no numbering is added**. Numbering appears only when Publora splits the text itself. A part you defined that exceeds 500 characters is re-split automatically when it came from `---`, but a `[n/m]` part is not — an oversized marker part is rejected at scheduling with `400` / `THREAD_PART_TOO_LONG`.
There is no public `parts` array and no numbering or threading switch in REST or MCP: `content` is the only input.
### Media in Threads
- **Carousel/Images:** Attached to the first post only
- **Video:** Attached to the first post only
- Subsequent posts in the thread are text-only
## Platform-Specific Settings
Threads supports a `replyControl` setting that controls who can reply to your posts:
```json
{
"platformSettings": {
"threads": {
"replyControl": ""
}
}
}
```
### Reply Control
| Value | Description |
|-------|-------------|
| `"everyone"` | Anyone can reply. This is a valid enum value in the schema but is distinct from the default `""`. When explicitly set, it is sent to the Threads API. |
| `""` (empty string) | **Default.** No `replyControl` value is sent to the Threads API — the platform's own default behavior applies (anyone can reply). This is NOT included in the API's default platform settings. |
| `"accounts_you_follow"` | Only accounts you follow can reply |
| `"mentioned_only"` | Only accounts mentioned in the post can reply |
## First Comment
Pass `firstComment` to [`create-post`](../endpoints/create-post.md#first-comment) and Publora replies to your own post right after it publishes (on a chain, under the last part). Up to **500 characters**; the connected account must grant `threads_manage_replies`, otherwise the result is `failed` with `FIRST_COMMENT_PERMISSION_REQUIRED` — reconnect the account in Publora Channels. The reply's media ID is returned in [`get-post` → `posts[].firstCommentResult.commentId`](../endpoints/get-post.md#first-comment-result-postsfirstcommentresult).
## Reply Management
Threads supports reply management through the Publora dashboard. The `getReplies` endpoint retrieves replies to a Threads post, and the `manageReply` endpoint allows you to hide or unhide individual replies. These endpoints are accessible via the dashboard API routes.
> **Note:** Reply management requires the `threads_manage_replies` OAuth scope. The current OAuth flow requests this scope automatically, but older connections established before this scope was added may lack it. If reply management returns permission errors, disconnect and reconnect your Threads account to obtain the updated scopes.
## Examples
### Post a Text Update
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Just shipped a major update to our API. Faster response times, better error messages, and new endpoints for batch operations.',
platforms: ['threads-55667788']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Just shipped a major update to our API. Faster response times, better error messages, and new endpoints for batch operations.',
'platforms': ['threads-55667788']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Just shipped a major update to our API. Faster response times, better error messages, and new endpoints for batch operations.",
"platforms": ["threads-55667788"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Just shipped a major update to our API. Faster response times, better error messages, and new endpoints for batch operations.',
platforms: ['threads-55667788']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with an Image Carousel
Carousels support 2-20 images. The workflow is: create a draft post, upload images, then schedule.
**JavaScript (fetch)**
```javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
// Step 1: Create a draft post (no scheduledTime)
const postResponse = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
content: 'Our product evolution over the past year. #buildinpublic',
platforms: ['threads-55667788']
// No scheduledTime = draft
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Upload each image (2-20 images supported)
const images = ['photo1.jpg', 'photo2.jpg', 'photo3.jpg'];
for (const fileName of images) {
// Get upload URL
const uploadUrlResponse = await fetch(`${BASE_URL}/get-upload-url`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
fileName,
contentType: 'image/jpeg',
type: 'image',
postGroupId
})
});
const { uploadUrl } = await uploadUrlResponse.json();
// Upload to S3
const fileBuffer = await fs.promises.readFile(`./${fileName}`);
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: fileBuffer
});
}
// Step 3: Schedule the post
await fetch(`${BASE_URL}/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-15T14:00:00.000Z'
})
});
console.log('Carousel scheduled!');
```
**Python (requests)**
```python
import requests
API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
}
# Step 1: Create a draft post (no scheduledTime)
post_response = requests.post(
f'{BASE_URL}/create-post',
headers=HEADERS,
json={
'content': 'Our product evolution over the past year. #buildinpublic',
'platforms': ['threads-55667788']
# No scheduledTime = draft
}
)
post_group_id = post_response.json()['postGroupId']
# Step 2: Upload each image (2-20 images supported)
images = ['photo1.jpg', 'photo2.jpg', 'photo3.jpg']
for file_name in images:
# Get upload URL
upload_response = requests.post(
f'{BASE_URL}/get-upload-url',
headers=HEADERS,
json={
'fileName': file_name,
'contentType': 'image/jpeg',
'type': 'image',
'postGroupId': post_group_id
}
)
upload_url = upload_response.json()['uploadUrl']
# Upload to S3
with open(f'./{file_name}', 'rb') as f:
requests.put(upload_url, headers={'Content-Type': 'image/jpeg'}, data=f.read())
# Step 3: Schedule the post
requests.put(
f'{BASE_URL}/update-post/{post_group_id}',
headers=HEADERS,
json={
'status': 'scheduled',
'scheduledTime': '2026-03-15T14:00:00.000Z'
}
)
print('Carousel scheduled!')
```
**cURL**
```bash
API_KEY="YOUR_API_KEY"
# Step 1: Create a draft post (no scheduledTime)
POST_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"content": "Our product evolution over the past year. #buildinpublic",
"platforms": ["threads-55667788"]
}')
POST_GROUP_ID=$(echo "$POST_RESPONSE" | jq -r '.postGroupId')
# Step 2: Upload each image (2-20 images supported)
for FILE in photo1.jpg photo2.jpg photo3.jpg; do
UPLOAD_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/get-upload-url \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d "{
\"fileName\": \"$FILE\",
\"contentType\": \"image/jpeg\",
\"type\": \"image\",
\"postGroupId\": \"$POST_GROUP_ID\"
}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
curl -s -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
--data-binary @"./$FILE"
done
# Step 3: Schedule the post
curl -X PUT "https://api.publora.com/api/v1/update-post/$POST_GROUP_ID" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"status": "scheduled",
"scheduledTime": "2026-03-15T14:00:00.000Z"
}'
```
> **Note:** For immediate publishing, set `scheduledTime` a few seconds in the future — a time already in the past is clamped to server time and flagged with a `SCHEDULED_TIME_COERCED` warning (see [past scheduled times](../guides/scheduling.md#past-scheduled-times)). For more details, see the [media upload workflow](../guides/media-uploads.md).
### Post a Thread (Long Content)
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `We just completed a major infrastructure migration and I want to share what we learned. Moving from a monolithic architecture to microservices is not as straightforward as the blog posts make it sound.
First, we had to map every single dependency between our services. This alone took two weeks. We discovered circular dependencies we never knew existed and had to refactor several core modules before we could even begin the migration.
The actual migration took three months. We ran both systems in parallel, comparing outputs in real-time. When we finally cut over, we had 99.97% uptime throughout the process. The key was incremental rollout and comprehensive monitoring at every step.`,
platforms: ['threads-55667788']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
content = """We just completed a major infrastructure migration and I want to share what we learned. Moving from a monolithic architecture to microservices is not as straightforward as the blog posts make it sound.
First, we had to map every single dependency between our services. This alone took two weeks. We discovered circular dependencies we never knew existed and had to refactor several core modules before we could even begin the migration.
The actual migration took three months. We ran both systems in parallel, comparing outputs in real-time. When we finally cut over, we had 99.97% uptime throughout the process. The key was incremental rollout and comprehensive monitoring at every step."""
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': content,
'platforms': ['threads-55667788']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "We just completed a major infrastructure migration and I want to share what we learned. Moving from a monolithic architecture to microservices is not as straightforward as the blog posts make it sound.\n\nFirst, we had to map every single dependency between our services. This alone took two weeks. We discovered circular dependencies we never knew existed and had to refactor several core modules before we could even begin the migration.\n\nThe actual migration took three months. We ran both systems in parallel, comparing outputs in real-time. When we finally cut over, we had 99.97% uptime throughout the process. The key was incremental rollout and comprehensive monitoring at every step.",
"platforms": ["threads-55667788"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const content = `We just completed a major infrastructure migration and I want to share what we learned. Moving from a monolithic architecture to microservices is not as straightforward as the blog posts make it sound.
First, we had to map every single dependency between our services. This alone took two weeks. We discovered circular dependencies we never knew existed and had to refactor several core modules before we could even begin the migration.
The actual migration took three months. We ran both systems in parallel, comparing outputs in real-time. When we finally cut over, we had 99.97% uptime throughout the process. The key was incremental rollout and comprehensive monitoring at every step.`;
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content,
platforms: ['threads-55667788']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
Long content like this is split into a numbered chain automatically. Inspect the result with `GET /api/v1/get-post/:postGroupId`, which reports `isThread` and one `threadParts[]` entry per part.
## Platform Quirks
- **Single hashtag limit**: Threads allows a maximum of 1 hashtag per post. If your content includes more than one hashtag, only the first will be recognized by the platform.
- **WebP auto-conversion**: If you provide WebP images, Publora automatically converts them to **JPEG** before uploading to Threads.
- **Chains need a permission**: `threads_manage_replies` must be granted on the connection. Publora rejects a chain before publishing anything if the grant is missing.
- **Numbering depends on who split the text**: parts Publora derives automatically are numbered; parts you separate with `---` are published verbatim.
- **No chain-wide ID**: `postedId` is the first part's ID. Per-part IDs are in `threadParts[].publishedId`.
- **No edit support**: Once posted, Threads posts cannot be edited via the API. You would need to delete and repost.
- **MP4 and MOV for videos**: MP4 and MOV video formats are supported. Other formats will be rejected.
- **Carousel video support depends on the path**: a single (non-chain) Threads post uploads every carousel item as an IMAGE, so a video inside one is not published as video. On a chain's first part Publora sends each item with its own type, so a video item is submitted as `VIDEO` — whether Threads accepts a mixed carousel is Meta's call, not Publora's. Standalone video posts work normally either way.
## Character Limits
| Element | Limit |
|---------|-------|
| Post body | 500 characters |
| Hashtags | 1 per post |
| Carousel items | 2-20 items (see Platform Quirks for video inside a carousel) |
## API Limits
### Text Limits
| Element | Limit |
|---------|-------|
| Post body | 500 characters |
| Links per post | 5 |
| Hashtags | 1 per post |
### Media Limits
| Media Type | Max Size | Max Count | Supported Formats |
|------------|----------|-----------|-------------------|
| Images | 8 MB | 20 per carousel | JPEG, PNG, WebP |
| Videos | 1 GB | 1 per post (see Platform Quirks for video inside a carousel) | MP4, MOV |
| Video Constraint | Limit |
|------------------|-------|
| Duration | 5 minutes |
### Rate Limits
Threads-side posting quotas are advisory, account-dependent, and may change without notice; they are not a Publora numeric contract.
### Additional Notes
- Multi-part chains are supported: 500 characters per part, media on the first part only.
- Platform-side rate-limit failures are surfaced; do not assume automatic retry or redistribution.
## What you can't do
- **Submit thread parts as a list:** there is no public `parts` array and no numbering or threading switch. The only public input is `content`, optionally with standalone `---` lines.
- **Address a chain by one ID:** no single platform ID represents the whole chain; read `threadParts[].publishedId` for the individual messages.
- **Attach media to a reply:** media go on the first part only; later parts are text-only.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/tiktok
# TikTok API - Upload Video via REST API
> **Agency client posts:** use the separate [Company platform settings](../guides/agency-platform-settings.md) contract. The personal API examples below keep their existing shapes and upload workflows.
Upload videos to TikTok programmatically using the Publora REST API. A simpler alternative to the official TikTok Developer API, TikTok Business SDK, or TikAPI.
## TikTok API Overview
Publora provides a unified REST API for uploading and publishing videos to TikTok with granular privacy and interaction controls. No need to manage complex TikTok OAuth flows, handle video processing, or navigate TikTok's developer portal requirements.
### Why Use Publora Instead of TikTok Developer API / TikTok Business SDK?
| Feature | Publora API | TikTok Developer API |
|---------|-------------|----------------------|
| Authentication | Single API key | Complex OAuth 2.0 flow |
| Video upload | Simple REST endpoint | Multi-step upload process |
| App approval | Not required | TikTok app review required |
| Multi-platform | Post to 10 platforms | TikTok only |
| Setup time | 5 minutes | Weeks (app review) |
| Privacy controls | Full support | Full support |
### Keywords: TikTok API, TikTok upload video API, TikTok posting API, TikTok video API, upload to TikTok programmatically, TikTok bot API, TikTok automation API, TikTok REST API, TikTok developer API, TikTok content API, post video to TikTok API
## Platform ID Format
```
tiktok-{openId}
```
Where `{openId}` is the TikTok `open_id` assigned during account connection via OAuth. This is an app-scoped identifier (not the user's public TikTok user ID).
## Requirements
- A TikTok account connected via OAuth through the Publora dashboard
- API key from Publora
- Media is **required** — either a video or a photo carousel of up to 35 images (TikTok has no text-only posts)
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text only | No | TikTok requires media (a video or photo) |
| Images | Yes | Photo carousel, up to 35 images (JPEG, PNG, WebP) |
| Videos | Yes | MP4, MOV, or WebM; minimum 23 FPS |
## Platform-Specific Settings
TikTok has extensive publishing settings that you can control through the `platformSettings` object:
```json
{
"platformSettings": {
"tiktok": {
"viewerSetting": "PUBLIC_TO_EVERYONE",
"allowComments": true,
"allowDuet": false,
"allowStitch": false,
"commercialContent": false,
"brandOrganic": false,
"brandedContent": false,
"aiGenerated": false
}
}
}
```
### Viewer Settings
> **Default: `PUBLIC_TO_EVERYONE`.** When you create a post via the REST API without specifying `viewerSetting`, Publora applies `PUBLIC_TO_EVERYONE`. A value is effectively required — an empty string is rejected with *"TikTok requires selecting who can view your post"* — so always set `viewerSetting` explicitly in your `platformSettings.tiktok` object.
>
> The viewer settings an account can actually use are determined by TikTok from that account's own configuration. Public accounts support all four levels below. If the connected account is private, TikTok limits it to `SELF_ONLY` and rejects other values for that account — switch the account to public in the TikTok app to unlock the full range.
| Value | Description |
|-------|-------------|
| `PUBLIC_TO_EVERYONE` | Anyone can view the video |
| `MUTUAL_FOLLOW_FRIENDS` | Only mutual followers can view |
| `FOLLOWER_OF_CREATOR` | Only your followers can view |
| `SELF_ONLY` | Only you can view (draft-like behavior) |
### Interaction Settings
> Each flag is direct: `true` allows the interaction, `false` blocks it.
>
> **Note:** Duet and Stitch apply to video posts only. TikTok also honors the account's own permissions — if a creator has disabled Duet, Stitch, or comments at the account level, that takes precedence over the request.
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `allowComments` | boolean | `true` | Allow viewers to comment |
| `allowDuet` | boolean | `false` | Allow viewers to create Duets |
| `allowStitch` | boolean | `false` | Allow viewers to Stitch your video |
### Automatic Music for Photo Posts
For a photo carousel, opt in with the optional boolean
`platformSettings.tiktok.autoAddMusic`:
```json
{
"platformSettings": {
"tiktok": {
"viewerSetting": "PUBLIC_TO_EVERYONE",
"autoAddMusic": true
}
}
}
```
TikTok will automatically choose the music. You cannot select or preview a
specific track in Publora. Choosing or uploading a song, searching a music
catalogue and editing video soundtracks are not supported by this setting.
| Value | Behavior |
| --- | --- |
| `true` | Ask TikTok to add recommended music to a photo Direct Post. |
| `false` | Disable music; send false for photos. Allowed when switching to video, which never sends the parameter. |
| Omitted | Preserve existing behavior; Publora does not silently enable music. |
Use this field on personal REST `create-post`/`update-post` and MCP
`create_post`/`update_post`. Agency drafts accept it through Company REST and
`company_create_post`/`company_update_post` inside `draft.platformSettings`;
see [Company settings](../guides/agency-platform-settings.md#tiktok-automatic-photo-music).
Draft saving, loading, editing, duplication and scheduling preserve the value.
Attaching known video/document media automatically clears a previously enabled
photo-music setting. For personal `update-post`/`update_post` media appends, this
cleanup applies when `autoAddMusic` is omitted; explicit `true` still fails
validation with non-photo media.
Enable this option only for **photo Direct Post**: `true` with known non-photo
media fails validation. Send `false` to disable music when switching a draft to
video. Incomplete drafts without media remain allowed. The field accepts JSON booleans only; strings such as `"true"`,
numbers and `null` are rejected. Publora maps an explicitly supplied value to
TikTok's `post_info.auto_add_music` on `/v2/post/publish/content/init/`, and never
sends it in video publishing requests. It uses the existing `video.publish`
permission, with no additional OAuth scope.
Changing this publishing setting invalidates an existing Agency client
approval. Request approval of the changed draft before scheduling/publishing
when client review is required.
Reference: [TikTok photo Direct Post API](https://developers.tiktok.com/docs/en/content-posting-api-reference-photo-post).
### Commercial Content Settings
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `commercialContent` | boolean | `false` | Whether this is commercial content |
| `brandOrganic` | boolean | `false` | Organic brand promotion (your own brand) |
| `brandedContent` | boolean | `false` | Paid partnership or sponsored content |
> **Note**: If `commercialContent` is `true`, then at least one of `brandOrganic` or `brandedContent` must also be `true`. Publora will return a validation error if `commercialContent` is enabled without specifying which type of commercial content applies.
### AI-Generated Content Disclosure
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `aiGenerated` | boolean | `false` | Self-disclose realistic AI-generated video or images; TikTok shows its "Creator labeled as AI-generated" label (`is_aigc`) |
TikTok requires the label for realistic AI-generated video or images; a missing disclosure risks removal or loss of For You eligibility. Publora sends the value as `is_aigc`: inside `post_info` for video Direct Post (always present, `false` by default) and at the top level of the photo `content/init` request (only when `true`). REST accepts the usual string encodings (`"true"`, `"1"`, `"yes"`, `"on"` and their negatives); MCP `create_post`/`update_post` and the Company API accept JSON booleans only. Agency drafts take it inside `draft.platformSettings.tiktok`, and changing it invalidates an existing client approval. The same field exists on Instagram, YouTube and X — see [AI-Generated Content Disclosure](../endpoints/create-post.md#ai-generated-content-disclosure).
## Examples
### Post a Video
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'How we built our startup in 60 seconds #startup #tech #coding',
platforms: ['tiktok-99887766'],
platformSettings: {
tiktok: {
viewerSetting: 'PUBLIC_TO_EVERYONE',
allowComments: true,
allowDuet: false,
allowStitch: false,
commercialContent: false,
brandOrganic: false,
brandedContent: false
}
}
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'How we built our startup in 60 seconds #startup #tech #coding',
'platforms': ['tiktok-99887766'],
'platformSettings': {
'tiktok': {
'viewerSetting': 'PUBLIC_TO_EVERYONE',
'allowComments': True,
'allowDuet': False,
'allowStitch': False,
'commercialContent': False,
'brandOrganic': False,
'brandedContent': False
}
}
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "How we built our startup in 60 seconds #startup #tech #coding",
"platforms": ["tiktok-99887766"],
"platformSettings": {
"tiktok": {
"viewerSetting": "PUBLIC_TO_EVERYONE",
"allowComments": true,
"allowDuet": false,
"allowStitch": false,
"commercialContent": false,
"brandOrganic": false,
"brandedContent": false
}
}
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'How we built our startup in 60 seconds #startup #tech #coding',
platforms: ['tiktok-99887766'],
platformSettings: {
tiktok: {
viewerSetting: 'PUBLIC_TO_EVERYONE',
allowComments: true,
allowDuet: false,
allowStitch: false,
commercialContent: false,
brandOrganic: false,
brandedContent: false
}
}
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** TikTok requires media — a video or a photo carousel. First create the post, then upload your media using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
### Post a Private Video with Restricted Interactions
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Preview of our upcoming feature for close friends only',
platforms: ['tiktok-99887766'],
platformSettings: {
tiktok: {
viewerSetting: 'MUTUAL_FOLLOW_FRIENDS',
allowComments: true,
allowDuet: false,
allowStitch: false,
commercialContent: false,
brandOrganic: false,
brandedContent: false
}
}
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Preview of our upcoming feature for close friends only',
'platforms': ['tiktok-99887766'],
'platformSettings': {
'tiktok': {
'viewerSetting': 'MUTUAL_FOLLOW_FRIENDS',
'allowComments': True,
'allowDuet': False,
'allowStitch': False,
'commercialContent': False,
'brandOrganic': False,
'brandedContent': False
}
}
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Preview of our upcoming feature for close friends only",
"platforms": ["tiktok-99887766"],
"platformSettings": {
"tiktok": {
"viewerSetting": "MUTUAL_FOLLOW_FRIENDS",
"allowComments": true,
"allowDuet": false,
"allowStitch": false,
"commercialContent": false,
"brandOrganic": false,
"brandedContent": false
}
}
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Preview of our upcoming feature for close friends only',
platforms: ['tiktok-99887766'],
platformSettings: {
tiktok: {
viewerSetting: 'MUTUAL_FOLLOW_FRIENDS',
allowComments: true,
allowDuet: false,
allowStitch: false,
commercialContent: false,
brandOrganic: false,
brandedContent: false
}
}
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
## Platform Quirks
- **Media required**: TikTok does not support text-only posts; attach either a photo carousel (up to 35 images) or one video.
- **Minimum 23 FPS**: Videos must have a frame rate of at least 23 frames per second. Videos below this threshold will be rejected by TikTok.
- **Supported formats**: Publora's scheduling validator accepts MP4, MOV, and WebM. A presigned URL can be issued for a broader `video/*` MIME type, but that upload-layer acceptance does not make AVI or MKV publishable.
- **Commercial content disclosure**: If your video promotes a brand or is part of a paid partnership, you must set the appropriate commercial content flags. Failing to do so may violate TikTok's community guidelines.
- **AI-generated content disclosure**: Set `aiGenerated: true` for realistic AI-generated video or images so TikTok applies its AI-generated label; undisclosed AI content risks removal or loss of For You eligibility. See [AI-Generated Content Disclosure](#ai-generated-content-disclosure).
- **Brand content dependencies**: Setting `commercialContent` to `true` requires at least one of `brandOrganic` or `brandedContent` to also be `true`. Publora will return a validation error if `commercialContent` is enabled without specifying which type applies.
- **Viewer setting restrictions**: Some viewer settings may limit the interaction options available. For example, `SELF_ONLY` posts cannot receive comments from others.
- **Processing time**: TikTok videos may take some time to process after upload. The post may not appear immediately on the profile.
## Creator Info
Before publishing, you can query the connected TikTok account's capabilities (max video duration, whether comments/duet/stitch are allowed by the creator's settings, etc.) using the creator info endpoint.
**Endpoint:** `POST /auth/tiktok/get-creator-info`
> **Important:** This is a **dashboard-only endpoint** that requires session authentication. It is **not** available as a public API endpoint and **cannot** be called with API key (`x-publora-key`) authentication. It is listed here for reference only.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platformId` | string | Yes | Your TikTok platform ID (e.g., `tiktok-abc123def`) |
**cURL (session auth required)**
```bash
curl -X POST https://api.publora.com/auth/tiktok/get-creator-info \
-H "Content-Type: application/json" \
--cookie "session=YOUR_SESSION_COOKIE" \
-d '{
"platformId": "tiktok-abc123def"
}'
```
The response includes the creator's available privacy levels, whether comments/duet/stitch can be toggled, and the maximum video duration allowed for the account.
## API Limits
These limits apply specifically to the TikTok Content Posting API and may differ from native TikTok app limits.
### Character Limit
| Element | API Limit | Native App Limit |
|---------|-----------|------------------|
| Video caption | 2,200 characters | 4,000 characters |
| Hashtags | Included in caption character count | Included in caption character count |
### Video Limits
| Specification | API Limit | Native App Limit |
|---------------|-----------|------------------|
| Maximum duration | **10 minutes (600 seconds)** -- actual limit is fetched dynamically from TikTok's creator info API and may vary per account | 60 minutes |
| Minimum duration | 3 seconds | 3 seconds |
| Maximum file size | 4 GB | 4 GB |
| Supported formats | MP4, MOV, WebM | MP4, MOV, WebM |
| Minimum frame rate | 23 FPS | 23 FPS |
### Rate Limits
TikTok-side posting quotas are account-dependent, may change without notice, and are not a Publora numeric contract.
### Publishing Notes
- **Video or photo**: TikTok accepts a single video (MP4, MOV, WebM), or a photo carousel of up to 35 images (JPEG, PNG, WebP). Other image formats fail scheduling validation with `400 MEDIA_TYPE_NOT_SUPPORTED`.
- **Privacy is account-dependent**: The viewer settings available to an account are set by TikTok from that account's configuration (see [Viewer Settings](#viewer-settings)). Public accounts can post at any level, including `PUBLIC_TO_EVERYONE`.
- **Rate limits**: TikTok-side quotas are advisory, account-dependent, and may change; Publora does not contractually enforce a posts-per-day number.
### Common Error Messages
| Error Code | Description | Solution |
|------------|-------------|----------|
| `spam_risk_too_many_posts` | Daily post limit reached | Wait 24 hours before posting again |
| `duration_check_failed` | Video duration out of range | Ensure video is between 3 seconds and your account's max duration (default 10 minutes) |
| `file_format_check_failed` | Unsupported media format | Use MP4, MOV, or WebM for video, or JPEG, PNG, or WebP for photos. (The message may reference '.mp4' only, but these formats are all accepted.) |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/youtube
# YouTube API - Upload Video via REST API
> **Agency client posts:** use the separate [Company platform settings](../guides/agency-platform-settings.md) contract. The personal API examples below keep their existing shapes and upload workflows.
Upload videos to YouTube programmatically using the Publora REST API. A simpler alternative to the official YouTube Data API, YouTube API client libraries, or Google APIs.
## YouTube API Overview
Publora provides a unified REST API for uploading and publishing videos to YouTube with configurable privacy (public, unlisted, private), metadata (title, description, tags, category, made-for-kids), YouTube playlists, and a tracked custom thumbnail. No need to manage Google OAuth flows, handle resumable uploads, or navigate YouTube API quotas.
### Why Use Publora Instead of YouTube Data API?
| Feature | Publora API | YouTube Data API |
|---------|-------------|------------------|
| Authentication | Single API key | Complex Google OAuth 2.0 |
| Video upload | Simple REST endpoint | Resumable upload protocol |
| Quota management | Handled automatically | Manual quota tracking |
| Multi-platform | Post to 10 platforms | YouTube only |
| Setup time | 5 minutes | Hours (Google Cloud setup) |
| Privacy controls | Full support | Full support |
### Keywords: YouTube API, YouTube upload video API, YouTube Data API, upload to YouTube programmatically, YouTube video upload API, YouTube posting API, YouTube REST API, YouTube developer API, YouTube automation API, publish video YouTube API, YouTube content API
## Platform ID Format
```
youtube-{channelId}
```
Where `{channelId}` is your YouTube channel ID assigned during account connection via Google OAuth.
## Requirements
- A YouTube channel connected via Google OAuth through the Publora dashboard
- API key from Publora
- Video content is **required** (YouTube is a video platform)
> **Refresh token lifespan:** When the OAuth provider does not specify an expiry, Publora defaults the refresh token lifespan to approximately 182 days (~6 months), calculated as `365/2` days in the code. After that period, the user will need to re-authenticate via the Publora dashboard to reconnect their YouTube channel.
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text only | No | YouTube requires a video |
| Images | No | Not supported as standalone posts |
| Videos | Yes | MP4, MOV, AVI, WebM formats, single video only |
> **Important:** YouTube posts through Publora support only a single video per post. If you attempt to attach multiple videos, the API will reject the request. To publish multiple videos, create separate posts for each.
## Platform-Specific Settings
YouTube supports a `platformSettings` object for video metadata, a YouTube playlist, and a tracked custom thumbnail:
```json
{
"platformSettings": {
"youtube": {
"privacy": "public",
"title": "My video title",
"tags": ["api", "tutorial"],
"categoryId": "22",
"madeForKids": false,
"aiGenerated": false,
"playlist": {
"id": "PLxxxxxxxx",
"platformId": "youtube-UCxxxxxxxx"
},
"thumbnail": {
"mediaId": "665f...",
"url": "https://media.publora.com/..."
}
}
}
}
```
| Setting | Values | Default | Description |
|---------|--------|---------|-------------|
| `privacy` | `"private"`, `"public"`, `"unlisted"` | `"public"` | Video visibility on YouTube |
| `title` | string | `""` (empty string) | Title displayed on the video page. If empty, the publisher derives a title from the first 70 characters of the post content at publish time. |
| `tags` | string[] (or comma-separated string) | — | Video tags (`snippet.tags`). YouTube caps the **combined** length at 500 characters (tags containing whitespace are quote-wrapped, costing +2 chars each); the API trims the list to fit, so an oversized list can't fail the upload. Omitted entirely when empty. |
| `categoryId` | string | — | YouTube video category ID (e.g. `"22"` People & Blogs, `"28"` Science & Technology). When omitted, YouTube applies the channel's default. An invalid id will fail the upload — see [Category IDs](#category-ids). |
| `madeForKids` | boolean | `false` | Sets `status.selfDeclaredMadeForKids` — YouTube's required "made for kids" (COPPA) audience declaration. **Always sent** on every upload; defaults to `false` (not made for kids). |
| `aiGenerated` | boolean | `false` | Sets `status.containsSyntheticMedia` — YouTube's "altered or synthetic content" disclosure for realistic AI-generated or AI-altered video or audio. Sent only when `true`. Not needed for scripts, titles, thumbnails, beauty filters or clearly unrealistic content. See [Altered or synthetic content](#altered-or-synthetic-content). |
| `playlist` | object `{ id, platformId }` | — | Add the published video to a YouTube playlist. `playlist.id` is the YouTube playlist id; `playlist.platformId` is the compound channel id (e.g. `youtube-UCxxxxxxxx`) and must match the single selected YouTube channel. Settable on `create-post`; changeable or clearable via `update-post`. See [Playlist](#playlist). |
| `thumbnail` | object `{ mediaId, url }` | — | Custom video thumbnail referencing a Publora-tracked media asset (uploaded via the dedicated thumbnail endpoint, which returns `mediaId` and `url`). Set via `update-post` (the upload requires a `postGroupId`). See [Custom Thumbnail](#custom-thumbnail). |
> **Note:** The full `content` is used as the video description. Pass `platformSettings` directly in the `create-post` request body — the API merges your values with the per-platform defaults.
### Tags
Pass `tags` as an array of strings (`["api", "tutorial"]`) or a comma-separated string (`"api, tutorial"`). The API trims blanks and enforces YouTube's 500-character combined cap by keeping tags until the budget is exhausted, so an over-long list is truncated rather than rejected.
### Made for kids
`madeForKids` maps to YouTube's required `selfDeclaredMadeForKids` audience declaration and is sent on **every** upload (defaulting to `false`). Set it to `true` if your content is directed at children, per YouTube/COPPA rules.
### Altered or synthetic content
`aiGenerated` maps to YouTube's `status.containsSyntheticMedia` disclosure. Set it to `true` when the video contains realistic AI-generated or AI-altered video or audio; YouTube does not require it for scripts, titles, thumbnails, beauty filters or clearly unrealistic content. It defaults to `false` and is omitted from the upload when off. REST accepts the usual string encodings (`"true"`, `"1"`, `"yes"`, `"on"` and their negatives); MCP `create_post`/`update_post` and the Company API accept JSON booleans only. Agency drafts take it inside `draft.platformSettings.youtube`, and changing it invalidates an existing client approval. The same field exists on Instagram, TikTok and X — see [AI-Generated Content Disclosure](../endpoints/create-post.md#ai-generated-content-disclosure).
### Category IDs
`categoryId` accepts a YouTube category ID string. Common values: `"22"` (People & Blogs), `"28"` (Science & Technology), `"24"` (Entertainment), `"27"` (Education), `"10"` (Music). An invalid or region-disallowed id causes YouTube to reject the whole upload, so leave it unset to fall back to the channel default if unsure.
### Playlist
Add the published video to one of the channel's YouTube playlists.
```json
{
"platformSettings": {
"youtube": {
"playlist": {
"id": "PLxxxxxxxx",
"platformId": "youtube-UCxxxxxxxx"
}
}
}
}
```
- `playlist.id` — the YouTube playlist id.
- `playlist.platformId` — the compound YouTube platform id from `platforms` (e.g. `youtube-UCxxxxxxxx`). It must match the single selected YouTube channel.
- A playlist can only be set when **exactly one** YouTube channel is selected.
- Set the playlist on `create-post`, and change or clear it via `update-post`.
- The video is added to the playlist **after** the YouTube upload finishes processing.
- **Best-effort:** if adding the video to the playlist fails, the video stays published — only the playlist association is skipped.
- You **cannot** change the playlist while the post is already `processing` (returns `409`).
**Clear the playlist** by sending empty strings:
```json
{
"platformSettings": {
"youtube": {
"playlist": {
"id": "",
"platformId": ""
}
}
}
}
```
**Playlist errors:**
| Error | Cause |
|-------|-------|
| `platformSettings.youtube.playlistId is not supported; use platformSettings.youtube.playlist.` | Legacy `playlistId` field was sent — use the `playlist` object |
| `platformSettings.youtube.playlist must be an object.` | `playlist` is not an object |
| `platformSettings.youtube.playlist.id must be a string.` | `playlist.id` is not a string |
| `platformSettings.youtube.playlist.platformId must be a string.` | `playlist.platformId` is not a string |
| `YouTube playlist requires both playlist.id and playlist.platformId.` | One of the two fields is missing |
| `YouTube playlist can only be set when exactly one YouTube channel is selected.` | More than one (or no) YouTube channel is selected |
| `YouTube playlist platformId must match the selected YouTube channel.` | `playlist.platformId` does not match the chosen channel |
| `Post group is currently being published; cannot change YouTube playlist. Retry once publishing completes.` | The post is publishing/processing |
### Custom Thumbnail
A custom thumbnail is a **Publora-tracked media asset**, referenced by the `thumbnail` object:
```json
{
"platformSettings": {
"youtube": {
"thumbnail": {
"mediaId": "665f...",
"url": "https://media.publora.com/..."
}
}
}
}
```
**Flow:**
1. Create a draft post (`create-post`).
2. Upload the thumbnail image through the [dedicated YouTube thumbnail upload endpoint](../endpoints/upload-youtube-thumbnail.md) — it requires the `postGroupId`.
3. Use the returned `mediaId` and `url`.
4. Update the post with `platformSettings.youtube.thumbnail` (`update-post`).
5. Schedule the post.
> **Note:** A thumbnail **cannot** be passed on `create-post` — the thumbnail upload requires a `postGroupId`, so the post must exist first.
**Constraints:**
- **Format:** JPEG or PNG.
- **Max size:** 2 MB.
- **Min dimensions:** 640×360. **Recommended:** 1280×720 (16:9).
- **Must be Publora-uploaded / tracked media** — pass the `mediaId` and `url` returned by the thumbnail upload endpoint. Arbitrary URLs (including raw `media.publora.com` links) are not accepted; uploading via the generic media-upload flow is not sufficient.
- The custom thumbnail is applied **after** the video finishes processing, via the YouTube `thumbnails.set` API.
- **Best-effort:** if YouTube rejects the thumbnail (unverified channel, oversized/invalid image), **the video still publishes** — only the thumbnail is skipped.
- **Requires a verified YouTube channel.**
- You **cannot** change the thumbnail while the post is already `processing` (returns `409`).
**Clear the thumbnail** by sending an empty `url`:
```json
{
"platformSettings": {
"youtube": {
"thumbnail": {
"url": ""
}
}
}
}
```
### Privacy Settings
| Value | Description |
|-------|-------------|
| `private` | Only you can view the video |
| `public` | Anyone can search for and view the video |
| `unlisted` | Anyone with the link can view, but it will not appear in search results |
### Title Behavior
If you do not specify a `title` in the platform settings, the API defaults the title to an empty string `""` at post creation. The publisher service may derive a title from the first 70 characters of the post content at publish time. The full `content` is used as the video description. Pass `platformSettings` directly in the `create-post` request body. The API merges user-provided settings with defaults per platform.
## Examples
### Upload a Public Video
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'How to Build a REST API in 10 Minutes - A complete tutorial covering Express.js setup, routing, middleware, error handling, and deployment to production. Perfect for beginners who want to get started with backend development.',
platforms: ['youtube-UCxxxxxxxx'],
platformSettings: {
youtube: {
privacy: 'public',
title: 'How to Build a REST API in 10 Minutes'
}
}
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'How to Build a REST API in 10 Minutes - A complete tutorial covering Express.js setup, routing, middleware, error handling, and deployment to production. Perfect for beginners who want to get started with backend development.',
'platforms': ['youtube-UCxxxxxxxx'],
'platformSettings': {
'youtube': {
'privacy': 'public',
'title': 'How to Build a REST API in 10 Minutes'
}
}
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "How to Build a REST API in 10 Minutes - A complete tutorial covering Express.js setup, routing, middleware, error handling, and deployment to production. Perfect for beginners who want to get started with backend development.",
"platforms": ["youtube-UCxxxxxxxx"],
"platformSettings": {
"youtube": {
"privacy": "public",
"title": "How to Build a REST API in 10 Minutes"
}
}
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'How to Build a REST API in 10 Minutes - A complete tutorial covering Express.js setup, routing, middleware, error handling, and deployment to production. Perfect for beginners who want to get started with backend development.',
platforms: ['youtube-UCxxxxxxxx'],
platformSettings: {
youtube: {
privacy: 'public',
title: 'How to Build a REST API in 10 Minutes'
}
}
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** YouTube requires a video. First create the post, then upload the video using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
### Upload an Unlisted Video
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Internal demo recording for the team. This video covers the new dashboard features and upcoming roadmap items. Please do not share this link externally.',
platforms: ['youtube-UCxxxxxxxx'],
platformSettings: {
youtube: {
privacy: 'unlisted',
title: 'Internal Demo - Q1 Dashboard Features'
}
}
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Internal demo recording for the team. This video covers the new dashboard features and upcoming roadmap items. Please do not share this link externally.',
'platforms': ['youtube-UCxxxxxxxx'],
'platformSettings': {
'youtube': {
'privacy': 'unlisted',
'title': 'Internal Demo - Q1 Dashboard Features'
}
}
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Internal demo recording for the team. This video covers the new dashboard features and upcoming roadmap items. Please do not share this link externally.",
"platforms": ["youtube-UCxxxxxxxx"],
"platformSettings": {
"youtube": {
"privacy": "unlisted",
"title": "Internal Demo - Q1 Dashboard Features"
}
}
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Internal demo recording for the team. This video covers the new dashboard features and upcoming roadmap items. Please do not share this link externally.',
platforms: ['youtube-UCxxxxxxxx'],
platformSettings: {
youtube: {
privacy: 'unlisted',
title: 'Internal Demo - Q1 Dashboard Features'
}
}
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Upload with Auto-Generated Title
If you omit the `title` setting, the API defaults the title to an empty string `""` at post creation. The publisher service may derive a title from the first 70 characters of the post content at publish time. To set a custom title, include it in `platformSettings` when calling `create-post`.
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Weekly Vlog: What I learned shipping 3 features in 5 days. This week was intense but incredibly productive. We managed to ship the new analytics dashboard, the team collaboration feature, and a complete redesign of the onboarding flow.',
platforms: ['youtube-UCxxxxxxxx']
})
});
const data = await response.json();
// Note: title defaults to an empty string at post creation — the publisher service may derive one from content at publish time. Include platformSettings.youtube.title to set a custom one
// Description will be the full content
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Weekly Vlog: What I learned shipping 3 features in 5 days. This week was intense but incredibly productive. We managed to ship the new analytics dashboard, the team collaboration feature, and a complete redesign of the onboarding flow.',
'platforms': ['youtube-UCxxxxxxxx']
}
)
data = response.json()
# Note: title defaults to an empty string at post creation — the publisher service may derive one from content at publish time. Include platformSettings.youtube.title to set a custom one
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Weekly Vlog: What I learned shipping 3 features in 5 days. This week was intense but incredibly productive. We managed to ship the new analytics dashboard, the team collaboration feature, and a complete redesign of the onboarding flow.",
"platforms": ["youtube-UCxxxxxxxx"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Weekly Vlog: What I learned shipping 3 features in 5 days. This week was intense but incredibly productive. We managed to ship the new analytics dashboard, the team collaboration feature, and a complete redesign of the onboarding flow.',
platforms: ['youtube-UCxxxxxxxx']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
// Note: title defaults to an empty string at post creation — the publisher service may derive one from content at publish time. Include platformSettings.youtube.title to set a custom one
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
## Platform Quirks
- **Video only**: YouTube does not support text-only or image-only posts through the API. A video file must always be included.
- **MP4, MOV, AVI, WebM supported**: Publora validates video format server-side using the platform limits configuration (`postValidationService.js` calls `isVideoFormatSupported(platform, mimeType)` for all platforms including YouTube). YouTube accepts MP4, MOV, AVI, and WebM formats. If you upload an unsupported format, Publora will reject it before it reaches the YouTube API.
- **Single video only**: Publora supports uploading one video per post. If you attempt to attach multiple videos, the API will reject the request with an error.
- **Default title is empty string**: When no `title` is specified in platform settings, the API defaults the title to an empty string `""` at post creation. The publisher service may derive a title from the first 70 characters of the post content at publish time. It is recommended to explicitly set the title via `platformSettings` in the `create-post` request for best results.
- **Content becomes description**: The full `content` text is used as the YouTube video description, while the `title` (or auto-generated title) is used as the video title.
- **Processing time**: After upload, YouTube processes the video before it becomes available. This can take from a few seconds to several minutes depending on video length and resolution.
- **Daily upload quota**: YouTube enforces daily upload quotas. If you hit the quota, Publora will return the error from the YouTube API.
- **Privacy changes**: You can upload as `private` or `unlisted` first, then manually change the privacy to `public` later through YouTube Studio.
## API Limits
### Text Limits
| Element | Limit |
|---------|-------|
| Video title | 100 characters |
| Video description | 1,000 characters (frontend validation only; YouTube allows up to 5,000) |
| Default title | Empty string `""` at post creation (the publisher service may derive a title from the first 70 characters of post content at publish time) |
| Visible description | First 150 characters (shown before "Show more") |
### Media Limits
| Media Type | Max Size | Max Duration | Supported Formats |
|------------|----------|--------------|-------------------|
| Videos | 256 GB through the presigned API upload flow | 12 hours | MP4, MOV, AVI, WebM |
| Images | Not supported | - | - |
### Additional Notes
- YouTube is a video-only platform; images cannot be posted as standalone content
- The first 150 characters of the description are visible without clicking "Show more"
- Video processing time varies based on length and resolution
- Presigned API uploads support YouTube's 256 GB / 12-hour limit. The separate dashboard multipart video-processing route has a 512 MB multer cap; that cap does not apply to presigned API uploads.
- Publora enforces a 1,000-character limit on video descriptions via frontend validation only. The API itself does not enforce this limit, so API users can send up to YouTube's native 5,000-character limit.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/bluesky
# Bluesky API / AT Protocol - Post to Bluesky via REST API
Post to Bluesky programmatically using the Publora REST API. A simpler alternative to the AT Protocol (atproto) SDK or direct Bluesky API integration.
## Bluesky API Overview
Publora provides a unified REST API for publishing text posts and media content to Bluesky. Supports rich text features like auto-detected hashtags and URLs. No need to manage AT Protocol complexity, handle Bluesky authentication flows, or implement the atproto SDK.
### Why Use Publora Instead of AT Protocol SDK / Bluesky API?
| Feature | Publora API | AT Protocol / Bluesky API |
|---------|-------------|--------------------------|
| Authentication | Single API key | App password + DID resolution |
| Rich text | Automatic facets | Manual facet creation |
| Multi-platform | Post to 10 platforms | Bluesky only |
| Setup time | 5 minutes | 30+ minutes |
| Media handling | Automatic | Manual blob upload |
| Rate limiting | Handled | Manual implementation |
### Keywords: Bluesky API, AT Protocol API, atproto API, Bluesky posting API, post to Bluesky programmatically, Bluesky REST API, Bluesky developer API, Bluesky automation API, Bluesky bot API, decentralized social API, Bluesky skeet API
## Platform ID Format
```
bluesky-{did}
```
Where `{did}` is your Bluesky Decentralized Identifier (DID), assigned during account connection.
## Requirements
- A Bluesky account connected via **identifier + app password** through the Publora dashboard. The `identifier` field is your Bluesky handle (e.g., `yourname.bsky.social`) — not labeled "username" in the connection form.
- You must use an **app password**, not your main account password (generate one in Bluesky Settings > App Passwords)
- API key from Publora
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text | Yes | 300 characters |
| Images | Yes | Up to 4 per post, all images converted to JPEG before upload |
| Videos | Yes | MP4 format |
| Alt text | No via REST | The API media model does not persist the `alt` field read by the publisher |
| Rich text | Yes | Hashtags and URLs auto-detected |
## Rich Text Facets
Bluesky uses a rich text system based on **facets** with byte offsets. Publora handles this complexity automatically:
- **Hashtags**: Any `#hashtag` in your content is automatically detected and converted to a clickable hashtag facet with correct byte offset calculation.
- **URLs**: Any URL in your content (e.g., `https://example.com`) is automatically detected and converted to a clickable link facet.
- **Byte offsets**: Bluesky requires precise byte offsets for facets, not character offsets. Publora calculates these correctly, even for content with multi-byte characters (e.g., emojis, non-Latin scripts).
## Examples
### Post a Text Update
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Just launched our new API documentation! Check it out at https://docs.example.com #devtools #api',
platforms: ['bluesky-did:plc:abc123xyz']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Just launched our new API documentation! Check it out at https://docs.example.com #devtools #api',
'platforms': ['bluesky-did:plc:abc123xyz']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Just launched our new API documentation! Check it out at https://docs.example.com #devtools #api",
"platforms": ["bluesky-did:plc:abc123xyz"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Just launched our new API documentation! Check it out at https://docs.example.com #devtools #api',
platforms: ['bluesky-did:plc:abc123xyz']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
```
### Create an Image-post Draft
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Our new dashboard is live! Here is a preview of the analytics view. #buildinpublic',
platforms: ['bluesky-did:plc:abc123xyz']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** To attach media to a Bluesky post, first create the post, then upload media using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Our new dashboard is live! Here is a preview of the analytics view. #buildinpublic',
'platforms': ['bluesky-did:plc:abc123xyz']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Our new dashboard is live! Here is a preview of the analytics view. #buildinpublic",
"platforms": ["bluesky-did:plc:abc123xyz"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Our new dashboard is live! Here is a preview of the analytics view. #buildinpublic',
platforms: ['bluesky-did:plc:abc123xyz']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with Multiple Images
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Before and after our office renovation. What a transformation!',
platforms: ['bluesky-did:plc:abc123xyz']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Before and after our office renovation. What a transformation!',
'platforms': ['bluesky-did:plc:abc123xyz']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Before and after our office renovation. What a transformation!",
"platforms": ["bluesky-did:plc:abc123xyz"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Before and after our office renovation. What a transformation!',
platforms: ['bluesky-did:plc:abc123xyz']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
## First Comment
Pass `firstComment` to [`create-post`](../endpoints/create-post.md#first-comment) and Publora posts a reply under your own post right after it publishes. Limits are Bluesky's: **300 graphemes and 3,000 UTF-8 bytes**; links and mentions get rich-text facets like a normal post. The reply's `at://` URI is returned in [`get-post` → `posts[].firstCommentResult.commentId`](../endpoints/get-post.md#first-comment-result-postsfirstcommentresult).
## Platform Quirks
- **App password required**: You must use a Bluesky app password, not your main account password. Generate one at Settings > App Passwords in the Bluesky app.
- **Accepted image formats**: JPEG, PNG, and WebP pass scheduling validation; the publisher converts those accepted inputs to JPEG before upload.
- **Up to 4 images**: A maximum of 4 images can be attached to a single post.
- **Rich text auto-detection**: Publora automatically detects hashtags (`#tag`) and URLs in your content and creates the correct Bluesky facets with proper byte offsets. You do not need to do any special formatting.
- **Byte offset precision**: Bluesky facets use byte offsets, not character offsets. This means multi-byte characters (emojis, CJK characters, etc.) are handled correctly by Publora, but if you are debugging, be aware of this distinction.
- **Alt text mapping**: The Bluesky publisher reads an `alt` property from media objects, but the API media model does not persist that property. An `altTexts` value sent to `create-post` is not processed.
- **DID-based platform ID**: Unlike other platforms that use numeric IDs, Bluesky uses a DID (Decentralized Identifier) format like `did:plc:abc123xyz`.
- **Connection testing uses the app password**: `test-connection` validates the stored username/app-password pair by logging in to Bluesky; no OAuth access token is required.
## Character Limits
| Element | Limit |
|---------|-------|
| Post body | 300 characters |
| Alt text | Unavailable through Publora REST; Bluesky's 2,000-character platform limit is therefore not an API-settable contract |
| Images | Up to 4 per post |
## API Limits
**Character Limit:** 300 characters (links count toward the limit in Publora — validation uses total `content.length`, not a link-aware count)
**Image Limits:**
- **Max size: exactly 2,000,000 bytes** (decimal, not 2 MiB)
- Max count: 4
- Input formats: JPEG, PNG, WebP (converted to JPEG before upload to Bluesky). GIF, TIFF, and BMP fail scheduling validation.
**Video Limits:**
- Max duration: 3 minutes
- Max size: 100 MiB (104,857,600 bytes)
- Formats: MP4 only
- **Daily limit: 25 videos per day** (sourced from `@publora/platform-limits`)
- Email verification required before video uploads
**Common Error Messages:**
- `429 Too Many Requests` - Rate limit exceeded
- Video job state `JOB_STATE_FAILED` - Processing failed
**Rate Limits:**
- 25 videos per day (sourced from `@publora/platform-limits`)
## Analytics
Engagement counters for a published post and follower counts for the connected account are available on demand:
```bash
curl -X POST https://api.publora.com/api/v1/post-statistics \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{"posts":[{"platform":"bluesky","platformId":"bluesky-did:plc:3xcxmi4aiok5zyghylsa4dzw","postedId":"at://did:plc:3xcxmi4aiok5zyghylsa4dzw/app.bsky.feed.post/3muxmedtwxd2k"}]}'
```
Bluesky reports `reactions` (likes), `comments` (replies), `reposts`, `quotes` and `saves` (bookmarks). `impressions`, `reach` and `clicks` are `null` — the AppView exposes no such counters. The `postedId` is the AT-URI of the post. Requires a plan with analytics; values are cached for about 2 hours. See [Mastodon and Bluesky Statistics](https://docs.publora.com/endpoints/platform-statistics).
## What you can't do through the REST API
- **Set image alt text:** Neither the presigned-upload flow nor `mediaUrls` stores the `alt` property read by the Bluesky publisher. Do not send `altTexts` expecting it to persist.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/mastodon
# Mastodon API - Post to Fediverse via REST API
Post to Mastodon and the Fediverse programmatically using the Publora REST API. A simpler alternative to the official Mastodon API, Megalodon, or direct ActivityPub integration.
## Mastodon API Overview
Publora provides a unified REST API for publishing text posts and media content to Mastodon and the fediverse. Posts are published to the mastodon.social instance. No need to manage Mastodon OAuth flows, handle ActivityPub protocols, or set up your own Mastodon application.
### Why Use Publora Instead of Mastodon API / Megalodon?
| Feature | Publora API | Mastodon API |
|---------|-------------|--------------|
| Authentication | Single API key | OAuth 2.0 per instance |
| Instance support | mastodon.social | Any instance |
| Multi-platform | Post to 10 platforms | Mastodon/Fediverse only |
| Setup time | 5 minutes | Varies by instance |
| Media handling | Automatic | Manual upload |
| Federation | Automatic | Automatic |
### Keywords: Mastodon API, Mastodon posting API, Fediverse API, ActivityPub API, post to Mastodon programmatically, Mastodon REST API, Mastodon developer API, Mastodon bot API, Mastodon automation API, toot API, Mastodon status API, decentralized social API
## Platform ID Format
```
mastodon-{accountId}
```
Where `{accountId}` is your Mastodon account ID assigned during account connection through the Publora dashboard.
## Requirements
- A Mastodon account on the mastodon.social instance connected through the Publora dashboard (OAuth scopes requested: `read`, `write`, `push`)
- API key from Publora
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text | Yes | 500 characters |
| Images | Yes | JPEG, PNG, GIF, WebP, HEIF, HEIC, AVIF; up to 4 per post |
| Videos | Yes | MP4, WebM, MOV formats |
| Visibility | Yes | Public by default |
## Visibility
Posts on Mastodon are set to **public** visibility by default when posted through Publora. This means they will appear on your profile, in your followers' home timelines, and on the public federated timeline.
## Examples
### Post a Text Update
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Hello fediverse! We just shipped a major update to our open-source project. Check out the changelog at https://example.com/changelog #opensource #fediverse',
platforms: ['mastodon-109876543210']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Hello fediverse! We just shipped a major update to our open-source project. Check out the changelog at https://example.com/changelog #opensource #fediverse',
'platforms': ['mastodon-109876543210']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Hello fediverse! We just shipped a major update to our open-source project. Check out the changelog at https://example.com/changelog #opensource #fediverse",
"platforms": ["mastodon-109876543210"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Hello fediverse! We just shipped a major update to our open-source project. Check out the changelog at https://example.com/changelog #opensource #fediverse',
platforms: ['mastodon-109876543210']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with Media
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'New feature alert: our dashboard now supports dark mode! Here is a side-by-side comparison. #ui #darkmode',
platforms: ['mastodon-109876543210']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** To attach media to a Mastodon post, first create the post, then upload media using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'New feature alert: our dashboard now supports dark mode! Here is a side-by-side comparison. #ui #darkmode',
'platforms': ['mastodon-109876543210']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "New feature alert: our dashboard now supports dark mode! Here is a side-by-side comparison. #ui #darkmode",
"platforms": ["mastodon-109876543210"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'New feature alert: our dashboard now supports dark mode! Here is a side-by-side comparison. #ui #darkmode',
platforms: ['mastodon-109876543210']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with a Video
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Quick demo of our new real-time collaboration feature. Multiple users editing the same document simultaneously!',
platforms: ['mastodon-109876543210']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Quick demo of our new real-time collaboration feature. Multiple users editing the same document simultaneously!',
'platforms': ['mastodon-109876543210']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Quick demo of our new real-time collaboration feature. Multiple users editing the same document simultaneously!",
"platforms": ["mastodon-109876543210"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: 'Quick demo of our new real-time collaboration feature. Multiple users editing the same document simultaneously!',
platforms: ['mastodon-109876543210']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
## First Comment
Pass `firstComment` to [`create-post`](../endpoints/create-post.md#first-comment) and Publora posts a public reply under your own status right after it publishes. Up to **500 characters**, with each `http(s)://` link counted as 23 (punctuation glued to a link counts as ordinary characters). The reply's status ID is returned in [`get-post` → `posts[].firstCommentResult.commentId`](../endpoints/get-post.md#first-comment-result-postsfirstcommentresult).
## Platform Quirks
- **mastodon.social only**: New connections are limited to the mastodon.social instance (the OAuth flow uses a hardcoded instance URL). The test-connection validator attempts to extract the instance URL from the connection's `profileUrl` field, but `profileUrl` is never set during Mastodon connection creation, so it always falls back to mastodon.social. Support for other instances may be added in the future.
- **Public by default**: All posts made through Publora are published with public visibility. They will appear on the federated timeline.
- **Up to 4 images**: A maximum of 4 images can be attached to a single post. Publora enforces this limit at scheduling time via `postValidationService.js` and will reject posts that exceed it before they reach the Mastodon API.
- **Image formats**: Publora's validator accepts JPEG, PNG, GIF, WebP, HEIF, HEIC, and AVIF for Mastodon. The publisher passes supported media through rather than converting it.
- **MP4, WebM, and MOV for videos**: Mastodon accepts MP4, WebM, and MOV video formats. Publora accepts all three as input, but the scheduler currently reports the MIME type as `video/mp4` to Mastodon regardless of the actual format. MP4 uploads work correctly; WebM and MOV files may experience processing issues due to the mismatched MIME type.
- **500-character limit**: Mastodon enforces a strict 500-character limit. Publora will return an error if your content exceeds this. Mastodon does not auto-thread in Publora; only X/Twitter and Meta Threads split long content into a chain.
- **Hashtags**: Hashtags in Mastodon are part of the post body and count toward the character limit. They become clickable and searchable on the platform.
- **Content warnings**: Mastodon supports content warnings (CW), but this feature is not currently available through the Publora API.
- **Federation delay**: Because Mastodon is federated, posts may take a few seconds to propagate to other instances in the fediverse.
## API Limits
### Text Limits
| Element | Limit |
|---------|-------|
| Post body | 500 characters (instance-configurable, some allow 5,000+) |
| Media description (alt text) | 1,500 characters |
### Media Limits
| Media Type | Max Size | Max Count | Supported Formats |
|------------|----------|-----------|-------------------|
| Images | 16 MB | 4 per post | JPEG, PNG, GIF, WebP, HEIF, HEIC, AVIF |
| Videos | ~99 MB | 1 per post | MP4, WebM, MOV |
| Video Constraint | Limit |
|------------------|-------|
| Duration | 86,400 seconds (24 hours) |
### Rate Limits
| Limit Type | Value |
|------------|-------|
| Media uploads | 30 per 30 minutes |
| API requests | 300 per 5 minutes |
### Additional Notes
- Character limits vary by Mastodon instance; mastodon.social uses 500 characters, but some instances allow 5,000+
- Publora currently connects to mastodon.social only (posting is hardcoded to this instance)
- Mastodon does not support auto-threading in the current Publora capability set; X/Twitter and Meta Threads do
- Max image count (4) and video count (1) limits are enforced by Publora at scheduling time via `postValidationService.js`
## Analytics
Engagement counters for a published toot and follower counts for the connected account are available on demand:
```bash
curl -X POST https://api.publora.com/api/v1/post-statistics \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{"posts":[{"platform":"mastodon","platformId":"mastodon-110300915972205108","postedId":"117232239423110999"}]}'
```
Mastodon reports `reactions` (favourites), `comments` (replies), `reposts` (boosts) and, on Mastodon 4.5+, `quotes`. `saves`, `impressions`, `reach` and `clicks` are `null` — Mastodon has no such counters. Requires a plan with analytics; values are cached for about 2 hours. Only posts Publora published for you and stored a `postedId` for can be queried. See [Mastodon and Bluesky Statistics](https://docs.publora.com/endpoints/platform-statistics).
## What you can't do through the REST API
- **Set media descriptions (alt text):** The Mastodon publisher forwards `file.description` when present, but the API media model has no persisted `description` field. The current REST upload flows therefore cannot supply it.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/platforms/telegram
# Telegram API - Post to Channel via REST API
Post to Telegram channels and groups programmatically using the Publora REST API. A simpler alternative to the Telegram Bot API, Telethon, Pyrogram, or MTProto libraries.
## Telegram API Overview
Publora provides a unified REST API for publishing content to Telegram channels and groups via bot or MTProto connection. Supports rich text formatting with markdown syntax, images, and videos. No need to manage Telegram bot tokens directly, handle MTProto complexity, or implement message queuing. Publora supports two connection types: **bot** (using a BotFather token) and **mtproto** (using a user session), each with different capabilities and limits.
### Why Use Publora Instead of Telegram Bot API / Telethon / Pyrogram?
| Feature | Publora API | Telegram Bot API / Telethon |
|---------|-------------|----------------------------|
| Authentication | Single API key | Bot token + channel setup |
| Message formatting | Markdown support | Markdown/HTML support |
| Media handling | Automatic | Manual upload |
| Multi-platform | Post to 10 platforms | Telegram only |
| Setup time | 5 minutes | 15-30 minutes |
| Rate limiting | Handled | Manual implementation |
### Keywords: Telegram API, Telegram Bot API, Telegram channel API, Telegram posting API, post to Telegram programmatically, Telegram REST API, Telegram developer API, Telegram automation API, Telegram message API, send message Telegram API, Telethon alternative, Pyrogram alternative, MTProto API
## Platform ID Format
```
telegram-{chatId}
```
Where `{chatId}` is your Telegram channel or group chat ID assigned during bot connection setup. Bot API chat IDs of channels and supergroups are negative and start with `-100`, so a bot connection's platform ID has a double dash, for example `telegram--1001234567890`. MTProto connections store the channel's own positive ID, so their platform ID has a single dash, for example `telegram-1234567890`. Copy `platformId` verbatim from [`GET /platform-connections`](../endpoints/platform-connections.md) instead of building it.
## Requirements
- A Telegram bot created via [@BotFather](https://t.me/BotFather)
- The bot's token and the target channel, identified during setup by its public `@username` or, for a private channel, by its `-100…` chat ID or a `t.me/c/…` message link
- The bot must be added as an **administrator** of the target channel or supergroup. In a channel, the **`can_post_messages`** (Post Messages) permission must be explicitly enabled; being an admin alone is not enough. Regular (basic) groups are not supported; convert the group to a supergroup or use a channel
- API key from Publora
## Connection Types
Publora supports two connection types for Telegram:
### Bot Connection (Default)
1. Create a bot with [@BotFather](https://t.me/BotFather) on Telegram
2. Copy the bot token provided by BotFather
3. Add the bot as an administrator to your target channel or supergroup
4. In the Publora dashboard, provide the bot token and identify the channel:
- **Public channel:** its username, e.g. `@mychannel`, `mychannel`, or `t.me/mychannel`
- **Private channel** (no public username): its chat ID, e.g. `-1001234567890`, or a link to any message in the channel (choose **Copy Link** on the message), e.g. `https://t.me/c/1234567890/42`. The number after `t.me/c/` is the chat ID without its `-100` prefix.
5. Publora will verify the connection and assign a platform ID
Invite links (`t.me/+…`, `t.me/joinchat/…`) are rejected: the Bot API cannot identify a channel from an invite link. Use the chat ID or a message link instead.
A channel without a public username is saved with `username: null`, and `displayName` holds the channel title. [`GET /platform-connections`](../endpoints/platform-connections.md) and the MCP `list_connections` tool return both fields; [`test-connection`](../endpoints/test-connection.md) returns `username: null` and has no `displayName`.
### MTProto Connection
MTProto connections use a Telegram **user session** instead of a bot, enabling higher limits (2,048-character captions with Premium, 4 GB file uploads). MTProto requires a **Telegram Premium** subscription on the service user account. Note: Publora's code enforces a 4,096-character limit for all text fields, but Telegram's actual caption limit on media posts is 1,024 characters (regular users) or 2,048 characters (Premium). The 4,096 limit applies only to text-only messages. Long captions on media posts may be truncated or rejected by Telegram's API.
**Service user concept:** The MTProto connection operates through a dedicated Telegram user account (the "service user") that acts on behalf of your organization. This user must be an admin of the target channel/group. Because the service user is a regular Telegram account (not a bot), it benefits from the higher user-tier limits. The service user's session is stored encrypted by Publora in the connection record and decrypted at runtime.
> **Note:** MTProto connections require the service user to have an active Telegram Premium subscription. Without Premium, certain features (such as the extended 2,048-character caption limit on media posts) will not be available. For self-hosted deployments, the `TELEGRAM_MT_ALLOW_NON_PREMIUM` environment variable can be set to bypass the Premium requirement for MTProto connections.
## Supported Content
| Type | Supported | Limits |
|------|-----------|--------|
| Text | Yes | 4,096 characters (text-only messages, both bot and MTProto); 1,024 characters (captions with media, bot API) |
| Images | Yes | JPEG, PNG, GIF, BMP, WebP (WebP auto-converted to JPEG) |
| Videos | Yes | MP4, MOV, AVI, MKV, WebM |
| Formatting | Yes | Bold, italic, code, links, blockquotes |
## Text Formatting
Telegram supports markdown-style formatting in message text. You can use the following syntax in your `content`:
| Syntax | Result | Example |
|--------|--------|---------|
| `*text*` | **Bold** | `*important*` |
| `_text_` | _Italic_ | `_emphasis_` |
| `` `code` `` | `Inline code` | `` `variable` `` |
| ```` ```code``` ```` | Code block | ```` ```print("hello")``` ```` |
| `[text](url)` | Hyperlink | `[click here](https://example.com)` |
| `> text` | Blockquote | `> quoted text` |
## Caption vs. Message
When posting with media (images or videos), the text content is sent as a **caption** attached to the media. Captions have a stricter limit of 1,024 characters when using the bot API. MTProto with Premium supports up to 2,048-character captions on media posts (not 4,096 -- the 4,096 limit applies only to text-only messages). Text-only messages (without media) support up to 4,096 characters for both bot API and MTProto connections.
## Telegram Post Options
Publora supports Telegram-specific post options that control message delivery and content protection. These options are available in the Publora dashboard under "Telegram Presets" when creating or editing a post with a Telegram channel selected.
### Available Options
| Option | Description | API Parameter |
|--------|-------------|---------------|
| **Disable link preview** | Prevents Telegram from generating link previews for URLs in the message | `disableWebPagePreview` |
| **Silent notification** | Sends the message without triggering a notification sound on recipients' devices | `disableNotification` |
| **Protect content** | Prevents recipients from forwarding, saving, or copying the message content | `protectContent` |
"Caption above media" is not currently configurable. `showCaptionAboveMedia` is a latent read in the internal MTProto publisher, but there is no dashboard setter, persisted post-group field, or reachable product flow that supplies it. It is not an accepted REST `platformSettings.telegram` key; sending it through the API returns `400 PLATFORM_SETTING_UNKNOWN`.
### Using Post Options via API
To set Telegram-specific options via the API, include the `platformSettings.telegram` object in your request:
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: '*Exclusive Update*\n\nThis content is protected and cannot be forwarded.',
platforms: ['telegram--1001234567890'],
platformSettings: {
telegram: {
disableNotification: true, // Send silently
disableWebPagePreview: true, // No link previews
protectContent: true // Prevent forwarding/saving
}
}
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': '*Exclusive Update*\n\nThis content is protected and cannot be forwarded.',
'platforms': ['telegram--1001234567890'],
'platformSettings': {
'telegram': {
'disableNotification': True,
'disableWebPagePreview': True,
'protectContent': True
}
}
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Option Details
#### Disable Link Preview (`disableWebPagePreview`)
When enabled, Telegram will not generate preview cards for URLs in your message. Useful for:
- Keeping messages compact
- Avoiding preview images that may not represent your content well
- Reducing visual clutter in channels with frequent link sharing
#### Silent Notification (`disableNotification`)
When enabled, recipients will receive the message without a notification sound. The message still appears in their chat list and shows an unread badge. Useful for:
- Posting during off-hours without disturbing subscribers
- High-frequency update channels
- Non-urgent announcements
#### Protect Content (`protectContent`)
When enabled, Telegram restricts what recipients can do with your message:
- Cannot forward the message to other chats
- Cannot save media to device
- Cannot copy text (on mobile apps)
- Screenshot restrictions on some platforms
Useful for:
- Exclusive or premium content
- Time-sensitive announcements
- Content you want to keep within your channel
> **Note:** Content protection is enforced by Telegram clients but is not 100% foolproof. Users with modified clients or screen capture tools may still be able to save content.
## Examples
### Post a Text Message
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: '*Product Update v2.5*\n\nWe have shipped the following improvements:\n\n- _Faster API response times_ (avg 45ms)\n- New `batch` endpoint for bulk operations\n- Improved error messages with `error_code` field\n\n> This update is backward compatible. No migration needed.\n\nFull changelog: [docs.example.com/changelog](https://docs.example.com/changelog)',
platforms: ['telegram--1001234567890']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
content = """*Product Update v2.5*
We have shipped the following improvements:
- _Faster API response times_ (avg 45ms)
- New `batch` endpoint for bulk operations
- Improved error messages with `error_code` field
> This update is backward compatible. No migration needed.
Full changelog: [docs.example.com/changelog](https://docs.example.com/changelog)"""
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': content,
'platforms': ['telegram--1001234567890']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "*Product Update v2.5*\n\nWe have shipped the following improvements:\n\n- _Faster API response times_ (avg 45ms)\n- New `batch` endpoint for bulk operations\n- Improved error messages with `error_code` field\n\n> This update is backward compatible. No migration needed.\n\nFull changelog: [docs.example.com/changelog](https://docs.example.com/changelog)",
"platforms": ["telegram--1001234567890"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const content = `*Product Update v2.5*
We have shipped the following improvements:
- _Faster API response times_ (avg 45ms)
- New \`batch\` endpoint for bulk operations
- Improved error messages with \`error_code\` field
> This update is backward compatible. No migration needed.
Full changelog: [docs.example.com/changelog](https://docs.example.com/changelog)`;
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content,
platforms: ['telegram--1001234567890']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
### Post with an Image
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: '*New Dashboard Preview*\n\nHere is a sneak peek at our redesigned analytics dashboard. Key improvements include real-time data refresh and customizable widgets.',
platforms: ['telegram--1001234567890']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': '*New Dashboard Preview*\n\nHere is a sneak peek at our redesigned analytics dashboard. Key improvements include real-time data refresh and customizable widgets.',
'platforms': ['telegram--1001234567890']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "*New Dashboard Preview*\n\nHere is a sneak peek at our redesigned analytics dashboard. Key improvements include real-time data refresh and customizable widgets.",
"platforms": ["telegram--1001234567890"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: '*New Dashboard Preview*\n\nHere is a sneak peek at our redesigned analytics dashboard. Key improvements include real-time data refresh and customizable widgets.',
platforms: ['telegram--1001234567890']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
> **Note:** To attach media to a Telegram post, first create the post, then upload media using the [media upload workflow](../guides/media-uploads.md) with the returned `postGroupId`.
### Post with a Video
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: '*Feature Demo*\n\nWatch our 60-second demo of the new collaboration tools.',
platforms: ['telegram--1001234567890']
})
});
const data = await response.json();
console.log(data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': '*Feature Demo*\n\nWatch our 60-second demo of the new collaboration tools.',
'platforms': ['telegram--1001234567890']
}
)
data = response.json()
print(data)
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "*Feature Demo*\n\nWatch our 60-second demo of the new collaboration tools.",
"platforms": ["telegram--1001234567890"]
}'
# Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const response = await axios.post('https://api.publora.com/api/v1/create-post', {
content: '*Feature Demo*\n\nWatch our 60-second demo of the new collaboration tools.',
platforms: ['telegram--1001234567890']
}, {
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
console.log(response.data);
// Response: { "success": true, "postGroupId": "abc123...", "scheduledTime": null }
```
## Platform Quirks
- **Bot must be admin**: The Telegram bot must be added as an administrator to the target channel or supergroup, with the `can_post_messages` permission in a channel. The admin permission check happens at **connection time** and again when you call [`test-connection`](../endpoints/test-connection.md#telegram-connections), not at posting time — if the bot lacks these rights, the connection will be rejected during setup. If the bot loses posting rights later, `test-connection` returns `Bot needs channel administrator posting rights`, or `Request failed with status code ` if the bot was removed from a private channel.
- **Caption overflow behavior**: When posting with media, the text is sent as a caption (1,024-character limit via bot API). If the content exceeds 1,024 characters and media is attached, the text is sent as a separate reply message to the media post rather than being truncated or rejected. Text-only messages support up to 4,096 characters via MTProto.
- **Caption validation gap**: Publora's validation layer (`postValidationService.js`) does **not** currently validate caption length for Telegram. A 1,024-character caption limit exists at the Telegram API level, but Publora does not pre-check this. If your caption exceeds 1,024 characters on a media post, the error will come from Telegram's API at publish time, not from Publora's validation.
- **WebP auto-conversion**: WebP images are automatically converted to JPEG before sending to Telegram.
- **Markdown formatting**: Telegram supports a subset of markdown. Publora's `safeParseMarkdown` uses single asterisks for bold: `*bold*`, `_italic_`, `` `code` ``, `[text](url)`, and `> blockquote`. Note that this differs from standard Markdown where `**double asterisks**` denote bold. Not all markdown features are supported (e.g., headers are not rendered as headers).
- **Mixed media types not supported**: A single post cannot contain both images and videos. Attempting to send mixed media types will result in an error. Note that Publora's backend validation does **not** enforce mixed media type restrictions for Telegram (it only does so for Instagram). If Telegram rejects mixed media, the error comes from the Telegram API itself, not from Publora's validation layer.
- **Bot connection media group limitations**: Bot connections support either a single video OR multiple photos in a media group, but not multiple videos. Multi-video posts are not supported for bot connections. If you need to post multiple videos, create separate posts for each video.
- **Channel identifier format**: For a public channel, provide its username with or without the `@` prefix, or its `t.me/mychannel` link. For a private channel without a public `@username`, provide its `-100…` chat ID or a `t.me/c/…` link to any of its messages. Invite links (`t.me/+…`, `t.me/joinchat/…`) and public message links (`t.me/mychannel/123`) are not accepted.
- **Private channels have no username**: A channel without a public username is saved with `username: null`; its title is in `displayName`. Label such connections by `displayName`, and keep targeting posts by `platformId`.
- **Bot token security**: Your bot token is stored by Publora in the connection record and is never exposed in API responses. Treat your bot token like a password. Bot tokens are stored in plaintext in the connection record. Encryption at rest is planned but not yet implemented. MTProto sessions, however, ARE encrypted at rest (the service user's session is stored encrypted and decrypted at runtime).
- **MTProto test-connection limitation**: The `test-connection` endpoint always fails for MTProto connections. The Telegram validator only checks bot connections, so an MTProto connection (`connectionType: 'mtproto'`) returns `status: "error"` with the message `Invalid bot connection`. This is a known limitation; MTProto connections work correctly for posting despite failing the test-connection check.
- **Message editing**: Once posted, Telegram messages can be edited, but this capability is not currently exposed through the Publora API.
## API Limits
Understanding the difference between Bot API limits and regular user limits is critical for successful Telegram integration.
### Character Limits
| Element | Limit |
|---------|-------|
| Text message | 4,096 characters |
| **Bot caption** | **1,024 characters** (bots cannot get Premium 2,048 caption limit; the 4,096 limit is for text-only messages, not captions) |
| Bot username | 32 characters |
| Channel name | 128 characters |
### Image Limits (Bot API)
| Property | Limit |
|----------|-------|
| Max size | 10 MB |
| Max count | 10 images per media group |
| Formats | JPEG, PNG, GIF, WebP, BMP |
### Video Limits (Bot API)
| Property | Limit |
|----------|-------|
| Duration | No limit (only size matters) |
| **Max size** | **50 MB** (NOT 4 GB - that's for regular users!) |
| Local Bot API Server | 2 GB max |
| Formats | MP4, MOV, AVI, MKV, WebM |
### CRITICAL: Bot API vs User Limits
Bots have significantly lower limits than regular Telegram users. This is a common source of errors:
| Limit | Bot API | Regular Users |
|-------|---------|---------------|
| File size | 50 MB | 4 GB |
| Caption | 1,024 chars | 4,096 chars |
### Common Error Messages
| Error | Cause |
|-------|-------|
| `MEDIA_CAPTION_TOO_LONG` | Caption exceeds 1,024 characters (bots) |
| `Bad Request: file is too big` | File exceeds 50 MB |
### Rate Limits
Telegram-side message quotas are external, context-dependent, and not a Publora numeric contract. Consult Telegram's current Bot API documentation.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/mcp-server
# Publora MCP Server
Control Publora directly from AI assistants like Claude Code, Claude Desktop, Cursor, and any MCP-compatible client. No coding required -- just describe what you want in plain English.
## Overview
[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect to external tools and services. Publora provides a remote MCP server at `mcp.publora.com` -- one-time setup, then just talk to your AI.
**Perfect for:**
- **Marketers** -- schedule campaigns, check analytics, manage multiple accounts
- **Content creators** -- post to all platforms at once without leaving your AI chat
- **Business owners** -- delegate social media tasks to your AI assistant
- **Developers** -- integrate Publora into AI-powered workflows
**Just describe what you want:**
> "Show my connected social accounts"
> "Schedule a post to LinkedIn for tomorrow at 9am"
> "Delete my scheduled post for tomorrow"
> "Post this announcement to all my accounts"
## Quick Start
### Using Claude? Start here
Publora is in the Claude connectors directory. Open [claude.ai/directory/publora](https://claude.ai/directory/publora) and select **Connect** — that is the whole setup, on web, desktop and mobile alike. The steps below cover other MCP clients and Claude Code, which can sign in with OAuth or use a static key.
### 1. Get Your API Key
Log in to [Publora](https://publora.com) → **API** in the sidebar → Copy your key (`sk_...`). Click **MCP** in the sidebar for additional setup instructions.
### 2. Configure Your MCP Client
Add Publora to your MCP configuration:
```json
{
"mcpServers": {
"publora": {
"type": "http",
"url": "https://mcp.publora.com",
"headers": {
"Authorization": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
> **Note:** Both `https://mcp.publora.com/` and `https://mcp.publora.com/mcp` work as the MCP endpoint URL.
### 3. Restart Your Client
After restarting, your client lists 20 personal tools + 52 Company tools (72 total). Personal tools are included on every plan, with individual features subject to plan limits; Company tools require the appropriate Company account and role; client workspace publishing requires Agency access. Try asking:
> "List my connected social media accounts"
---
## Client-Specific Setup
### Claude Code (CLI)
Sign in with OAuth — no API key:
```bash
claude mcp add --transport http --scope user publora https://mcp.publora.com/mcp
```
Then run `/mcp`, select **publora**, choose **Authenticate** and sign in to Publora in the browser.
To use a static key instead (CI, headless machines), edit `~/.claude.json` or create `.mcp.json` in your project:
```json
{
"mcpServers": {
"publora": {
"type": "http",
"url": "https://mcp.publora.com/mcp",
"headers": {
"Authorization": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
Restart Claude Code. Verify with `/mcp` command.
### Claude Desktop
Claude Desktop uses the same connectors as Claude on the web: open [claude.ai/directory/publora](https://claude.ai/directory/publora) and select **Connect**. There is no config file to edit — **Settings → Developer → Edit Config** is for local MCP servers only. To add Publora by URL instead, see [MCP Client Setup](../mcp/client-setup.md).
### Cursor
Create `.cursor/mcp.json` in your project:
```json
{
"mcpServers": {
"publora": {
"type": "http",
"url": "https://mcp.publora.com",
"headers": {
"Authorization": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
### Using with Other MCP Servers
MCP servers don't conflict -- Claude loads all servers and merges their tools. Example with Context7:
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
},
"publora": {
"type": "http",
"url": "https://mcp.publora.com",
"headers": {
"Authorization": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
---
## Available Tools (72 total)
Publora exposes 20 personal tools + 52 Company tools (72 total). The tables below list the personal tools. The [52 `company_*` tools](../mcp/tools-reference.md#company-tools-52) cover Agency client work and permitted Company account administration; the [Agency quickstart](agency-quickstart.md) shows the client post flow. Access follows the current account type and role.
### Posts
| Tool | Description |
|------|-------------|
| `list_posts` | List posts with filters (status, platform, dates, pagination; `responseFormat: concise` for token-lean previews) |
| `create_post` | Create a draft, schedule a post, or publish now with `publishNow: true`; accepts `mediaUrls` (fast media path), `platformSettings` and first comments |
| `get_post` | Get post group details |
| `update_post` | Edit a draft/scheduled post: replace `content` or the `platforms` target set, change status/schedule, publish now with `publishNow: true`, append `mediaUrls`, or merge `platformSettings` |
| `delete_post` | Delete a post group and all platform posts |
### Media
| Tool | Description |
|------|-------------|
| `attach_media` | Attach a file from ChatGPT (for example, one the user uploaded) with an optional SEO `fileName`; Publora downloads and checks it and leaves the post as a draft |
| `get_upload_url` | Get a presigned S3 URL for media upload |
| `complete_media` | Finalize a file uploaded via `get_upload_url` |
| `delete_media` | Remove a media slot from a post |
| `prune_media_reference` | Remove a stale media reference that `delete_media` cannot handle (fixes `MEDIA_REFERENCE_MISSING`) |
### Account and Connections
| Tool | Description |
|------|-------------|
| `account_context` | Your plan, available features, publishing quotas and schedule horizon — check before a batch of posts or after a quota error |
| `list_connections` | List all connected social media accounts |
### Statistics (Mastodon and Bluesky)
| Tool | Description |
|------|-------------|
| `post_stats` | Engagement counters for published Mastodon or Bluesky posts |
| `profile_stats` | Followers, following and post count of a connected Mastodon or Bluesky account |
### LinkedIn Engagement
| Tool | Description |
|------|-------------|
| `linkedin_create_reaction` | React to a post (LIKE, PRAISE, EMPATHY, etc.) |
| `linkedin_delete_reaction` | Remove a reaction |
| `linkedin_create_comment` | Post a comment on a LinkedIn post |
| `linkedin_delete_comment` | Delete a comment from a LinkedIn post |
| `linkedin_create_reshare` | Reshare a LinkedIn post, optionally with commentary and visibility settings |
| `linkedin_list_mentionables` | List mentionable LinkedIn people with ready-to-paste mention tokens (paid plans) |
> The two statistics tools need a plan with analytics (Pro, or a legacy Premium plan). LinkedIn **analytics/followers/profile-summary** endpoints are **not** MCP tools — use the [REST OpenAPI reference](https://docs.publora.com/openapi.yaml). LinkedIn feed-retrieval tools (`linkedin_posts`, `linkedin_post_comments`, `linkedin_post_reactions`) are implemented but disabled pending LinkedIn's `r_member_social` approval.
---
## Example Conversations
> **Note:** Analytics examples below illustrate REST-API capabilities. Over MCP, statistics reads cover only Mastodon and Bluesky (`post_stats`, `profile_stats`); LinkedIn metrics come from the [REST OpenAPI reference](https://docs.publora.com/openapi.yaml).
### Schedule a Post
> **You:** Schedule a post to my LinkedIn saying "Excited to announce our new product launch!" for tomorrow at 9am EST
> **Claude:** I'll schedule that post for you. Let me first check your connected accounts...
>
> Done! Post scheduled to LinkedIn for 2026-02-20 at 9am EST.
### Cross-Platform Posting
> **You:** Post "We're hiring! Check out our careers page" to Twitter, LinkedIn, and Bluesky right now
> **Claude:** I'll post that to all three platforms...
>
> Done! Published to:
> - Twitter: https://twitter.com/...
> - LinkedIn: https://linkedin.com/...
> - Bluesky: https://bsky.app/...
### Check Post Analytics
> **You:** How did my last LinkedIn post perform?
> **Claude:** Your post from Feb 15 received:
> - 1,250 impressions
> - 680 unique viewers
> - 28 reactions, 5 comments, 3 reshares
> - Engagement rate: 2.9%
### Content Planning
> **You:** Show me all my scheduled posts for next week
> **Claude:** You have 5 scheduled posts:
> 1. Mon 9am - LinkedIn: "Product update..."
> 2. Tue 2pm - Twitter + LinkedIn: "Blog post..."
> 3. Wed 10am - LinkedIn: "Case study..."
> 4. Thu 3pm - Twitter: "Quick tip..."
> 5. Fri 9am - LinkedIn + Bluesky: "Week recap..."
### Campaign Management
> **You:** Cancel all my draft posts and show me what's still scheduled
> **Claude:** Deleted 3 draft posts. You still have 2 scheduled:
> - Tomorrow 10am - LinkedIn: "Q1 results..."
> - Friday 2pm - Twitter: "Weekend tips..."
### Weekly Review
> **You:** Give me a summary of how my LinkedIn performed this week
> **Claude:** This week's LinkedIn performance:
> - 5 posts published
> - 4,230 total impressions
> - 89 reactions, 12 comments
> - Best performer: "Product launch" (1,850 impressions)
> - Follower growth: +47
---
## Python Client Example
For programmatic access or testing:
```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
headers = {"Authorization": "Bearer sk_YOUR_API_KEY"}
async with streamablehttp_client("https://mcp.publora.com", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
# List tools
tools = await session.list_tools()
print(f"Available: {len(tools.tools)} tools")
# Get connections
result = await session.call_tool("list_connections", {})
print(result.content[0].text)
asyncio.run(main())
```
Install dependencies:
```bash
pip install mcp httpx
```
---
## Verification
### Health Check
```bash
curl https://mcp.publora.com/health
# {"status":"ok","service":"publora-mcp"}
```
### Test MCP Handshake
```bash
curl -X POST https://mcp.publora.com \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
```
---
## Authentication
Tool calls are authenticated in one of two ways:
- **OAuth 2.1 sign-in** — Claude, Claude Code and other browser-capable clients open a Publora window; approving it mints a dedicated key for that client.
- **Your Publora API key** (the same key as for the REST API) via `Authorization: Bearer sk_...` (recommended) or `x-publora-key: sk_...`.
---
## HTTP Endpoints
| Method | Path | Purpose |
|--------|------|---------|
| POST | `/mcp` or `/` | MCP messages (Streamable HTTP) |
| GET | `/mcp` or `/` | SSE stream (server notifications) |
| DELETE | `/mcp` or `/` | Close session |
| GET | `/health` | Health check |
---
## Troubleshooting
### "API key required" Error
Ensure your Authorization header is correctly formatted:
- Correct: `Authorization: Bearer sk_abc123...`
- Wrong: `Authorization: sk_abc123...`
### Tools Not Showing
1. Check your MCP config syntax (valid JSON)
2. Verify the `type` is `"http"` (not `"url"`)
3. Restart your MCP client completely
4. Run `/mcp` in Claude Code to verify connection
### Session Errors
MCP uses sessions for stateful connections. If you see "Invalid or missing session", the server will automatically create a new one on the next request.
---
## Comparison: MCP vs REST API
| Feature | MCP Server | REST API |
|---------|------------|----------|
| **Interface** | Natural language via AI | HTTP requests |
| **Best for** | Interactive exploration, quick tasks | Programmatic integration, automation |
| **Setup** | One-time config | Per-request auth |
| **Tools** | 20 personal tools + 52 Company tools (72 total; Company account and role required; Agency access for client publishing) | Full API access |
| **Rate limits** | Same as REST API | Same |
Use MCP for conversational workflows. Use REST API for production integrations.
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/cross-platform
# Cross-Platform Posting
This guide covers how to publish a single post to multiple social media platforms simultaneously through the Publora API, including platform-specific behavior and content adaptation.
## How It Works
Publora lets you compose a single post and distribute it across multiple social media platforms in one API call. The API handles platform-specific formatting, character limits, and media requirements automatically.
### Plan Restrictions
> **API access note:** API access is controlled by the `apiAccess` entitlement on your account. This entitlement is **enabled by default on all plans, including the free Starter plan** (15 posts/month, 3 accounts); only custom accounts with `apiAccess` explicitly disabled are blocked. If your account does not have the `apiAccess` entitlement, API calls will return a `403` error. The same applies to `mcpAccess` for MCP integrations.
### Platform IDs
Each connected social account is identified by a **platform ID** in the format:
```
{platform}-{platformId}
```
For example:
- `twitter-123456` -- a connected Twitter/X account
- `linkedin-ABCDEF` -- a connected LinkedIn profile
- `instagram-789012` -- a connected Instagram account
- `tiktok-345678` -- a connected TikTok account
- `facebook-901234` -- a connected Facebook page
- `youtube-567890` -- a connected YouTube channel
- `threads-111213` -- a connected Threads account
- `telegram-141516` -- a connected Telegram channel
- `bluesky-171819` -- a connected Bluesky account
- `mastodon-202122` -- a connected Mastodon account
Retrieve your connected accounts and their platform IDs from the `GET /api/v1/platform-connections` endpoint.
> **Pinterest:** Pinterest is registered in the platform registry (`SUPPORTED_PLATFORM_KEYS`) but publishing support is not yet fully available or tested. Pinterest support is on the roadmap.
### Character Limits by Platform
| Platform | Character Limit |
|---|---|
| Twitter / X | 280 |
| LinkedIn | 3,000 |
| Threads | 500 |
| Telegram | 4,096 (text) / 1,024 (media captions) |
| Facebook | 63,206 |
| Instagram | 2,200 |
| TikTok | 2,200 |
| YouTube | 5,000 (description) |
| Bluesky | 300 |
| Mastodon | 500 |
### Automatic Content Adaptation
When your content exceeds a platform's character limit, Publora adapts it automatically:
- **Twitter / X:** Long text is split into a **thread** (multiple tweets chained together).
- **Threads:** Long text is split into a **thread** (multiple posts chained together), each part replying to the previous one.
- **Other platforms:** Content that exceeds the platform's character limit will return a validation error. Content is **not** auto-truncated for non-threading platforms.
> **Threads note:** Threads chains need the `threads_manage_replies` permission on the connection. A connection whose token predates that permission is rejected before anything is published — reconnect the account in Publora Channels to grant it.
### Platform-Specific Defaults
`platformSettings` can be passed directly in the `create-post` request body. The API merges user-provided settings with defaults per platform.
>
> **⚠️ Supported platforms for `platformSettings`:** The API merges `platformSettings` for **TikTok**, **Instagram**, **YouTube**, **Threads**, **X** (`twitter`), **Telegram**, and **LinkedIn**. Unknown top-level platforms or nested fields are rejected with `400 PLATFORM_SETTING_UNKNOWN`; they are not silently ignored. See the canonical [create-post platformSettings allowlist](../endpoints/create-post.md#unknown-platformsettings-paths), [X Reply and Quote Settings](../endpoints/create-post.md#x-reply-and-quote-settings) for the `twitter` keys, and [AI-Generated Content Disclosure](../endpoints/create-post.md#ai-generated-content-disclosure) for the `aiGenerated` flag shared by Instagram, TikTok, YouTube and X.
>
> **⚠️ Field semantics differ:** The external API `update-post` endpoint accepts `content`, `platforms`, `status`, `scheduledTime`, `platformSettings` (merged per-platform), and `mediaUrls`; every field is a patch, so an omitted field keeps its stored value. Three of them do **not** behave alike: `platformSettings` is *merged* per-platform, `platforms` *replaces* the whole target set, and `mediaUrls` *appends* to existing media rather than replacing it (ingestion is limited to 60 URLs/hour, and a retry re-appends — send an `Idempotency-Key`). See [update-post](../endpoints/update-post.md).
Publora applies sensible defaults for platform-specific settings:
- **TikTok:** Default privacy and interaction settings are applied automatically.
- **Instagram:** Video posts are published as **Reels** by default. Set `videoType: "STORIES"` to post as a Story instead. An optional `coverUrl` (public JPEG URL) sets a custom Reels cover.
- **YouTube:** Videos are set to **public** visibility by default.
- **LinkedIn:** Repost settings can specify the parent post URN and `PUBLIC` or `CONNECTIONS` visibility. `CONNECTIONS` is personal-profile-only; company-page reposts must use `PUBLIC` and otherwise return `400`.
### Response Status Code
The `create-post` endpoint returns HTTP `200` (not `201`) on success. This applies to all post creation calls, including scheduled posts. Check `response.ok` or `response.status === 200` in your code.
## Examples
### Post to All Connected Platforms
**JavaScript (fetch)**
```javascript
// First, get all connected platform IDs
const connectionsResponse = await fetch(
'https://api.publora.com/api/v1/platform-connections',
{
headers: { 'x-publora-key': 'YOUR_API_KEY' }
}
);
const { connections } = await connectionsResponse.json();
const platforms = connections.map(c => c.platformId);
console.log('Connected platforms:', platforms);
// Create a post targeting all platforms
const postResponse = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'We just launched our new feature! Check it out at https://example.com',
platforms: platforms,
scheduledTime: '2026-03-15T14:00:00.000Z'
})
});
const post = await postResponse.json();
console.log('Post scheduled to all platforms:', post.postGroupId);
```
**Python (requests)**
```python
import requests
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
# Get all connected platform IDs
connections_response = requests.get(
f'{API_URL}/platform-connections',
headers=HEADERS
)
connections = connections_response.json()['connections']
platforms = [c['platformId'] for c in connections]
print(f"Connected platforms: {platforms}")
# Create a post targeting all platforms
post_response = requests.post(
f'{API_URL}/create-post',
headers=HEADERS,
json={
'content': 'We just launched our new feature! Check it out at https://example.com',
'platforms': platforms,
'scheduledTime': '2026-03-15T14:00:00.000Z'
}
)
post = post_response.json()
print(f"Post scheduled to all platforms: {post['postGroupId']}")
```
**cURL**
```bash
# Get all connected platform IDs
CONNECTIONS=$(curl -s https://api.publora.com/api/v1/platform-connections \
-H "x-publora-key: YOUR_API_KEY")
echo "Connected platforms:"
echo "$CONNECTIONS" | jq '.connections[].platformId'
# Extract platform IDs into a JSON array
PLATFORMS=$(echo "$CONNECTIONS" | jq '[.connections[].platformId]')
# Create a post targeting all platforms
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d "{
\"content\": \"We just launched our new feature! Check it out at https://example.com\",
\"platforms\": $PLATFORMS,
\"scheduledTime\": \"2026-03-15T14:00:00.000Z\"
}"
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
// Get all connected platform IDs
const { data: connectionsData } = await api.get('/platform-connections');
const platforms = connectionsData.connections.map(c => c.platformId);
console.log('Connected platforms:', platforms);
// Create a post targeting all platforms
const { data: post } = await api.post('/create-post', {
content: 'We just launched our new feature! Check it out at https://example.com',
platforms: platforms,
scheduledTime: '2026-03-15T14:00:00.000Z'
});
console.log('Post scheduled to all platforms:', post.postGroupId);
```
---
### Post to Specific Platforms (Twitter + LinkedIn + Instagram)
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Big news! We are expanding to 3 new markets this quarter. Stay tuned for more details.',
platforms: [
'twitter-123456',
'linkedin-ABCDEF',
'instagram-789012'
],
scheduledTime: '2026-03-15T09:00:00.000Z'
})
});
const post = await response.json();
console.log('Post created:', post.postGroupId);
// On Twitter, text above the connected account's applicable limit becomes a thread automatically.
// On LinkedIn (3000 char limit) and Instagram (2200 char limit), the full text is posted as-is.
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Big news! We are expanding to 3 new markets this quarter. Stay tuned for more details.',
'platforms': [
'twitter-123456',
'linkedin-ABCDEF',
'instagram-789012'
],
'scheduledTime': '2026-03-15T09:00:00.000Z'
}
)
post = response.json()
print(f"Post created: {post['postGroupId']}")
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Big news! We are expanding to 3 new markets this quarter. Stay tuned for more details.",
"platforms": [
"twitter-123456",
"linkedin-ABCDEF",
"instagram-789012"
],
"scheduledTime": "2026-03-15T09:00:00.000Z"
}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const { data: post } = await axios.post(
'https://api.publora.com/api/v1/create-post',
{
content: 'Big news! We are expanding to 3 new markets this quarter. Stay tuned for more details.',
platforms: [
'twitter-123456',
'linkedin-ABCDEF',
'instagram-789012'
],
scheduledTime: '2026-03-15T09:00:00.000Z'
},
{
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
}
);
console.log('Post created:', post.postGroupId);
```
---
### Handle Long Content Across Platforms
When posting long-form content, Publora automatically adapts it for each platform. Here is an example with text that exceeds a standard Twitter account's 280-character limit.
**JavaScript (fetch)**
```javascript
const longContent = `We are thrilled to announce that our platform now supports 10 social media channels!
Here is what's new:
- Twitter/X threading for long posts
- LinkedIn articles with rich formatting
- Instagram Reels for video content
- TikTok with automatic settings
- YouTube with public visibility defaults
- Facebook pages
- Threads support
- Telegram channels
- Bluesky integration
- Mastodon support
This has been months in the making, and we cannot wait for you to try it out. Visit our website to learn more and connect your accounts today.`;
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: longContent,
platforms: [
'twitter-123456', // Becomes a thread on a standard account (exceeds 280 chars)
'linkedin-ABCDEF', // Full text posted (under 3000 chars)
'threads-111213', // Will become a thread (exceeds 500 chars)
'telegram-141516', // Handled within Telegram limits
'bluesky-171819' // Bluesky: 300 char limit (no threading — content must fit within limit)
],
scheduledTime: '2026-03-15T10:00:00.000Z'
})
});
const post = await response.json();
console.log('Post created:', post.postGroupId);
// After publishing, check individual platform results
const statusResponse = await fetch(
`https://api.publora.com/api/v1/get-post/${post.postGroupId}`,
{
headers: { 'x-publora-key': 'YOUR_API_KEY' }
}
);
const status = await statusResponse.json();
// Each platform post may have its own status
if (status.posts) {
for (const platformPost of status.posts) {
console.log(`${platformPost.platform}: ${platformPost.status}`);
}
}
```
**Python (requests)**
```python
import requests
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
long_content = """We are thrilled to announce that our platform now supports 10 social media channels!
Here is what's new:
- Twitter/X threading for long posts
- LinkedIn articles with rich formatting
- Instagram Reels for video content
- TikTok with automatic settings
- YouTube with public visibility defaults
- Facebook pages
- Threads support
- Telegram channels
- Bluesky integration
- Mastodon support
This has been months in the making, and we cannot wait for you to try it out. Visit our website to learn more and connect your accounts today."""
response = requests.post(
f'{API_URL}/create-post',
headers=HEADERS,
json={
'content': long_content,
'platforms': [
'twitter-123456',
'linkedin-ABCDEF',
'threads-111213',
'telegram-141516',
'bluesky-171819'
],
'scheduledTime': '2026-03-15T10:00:00.000Z'
}
)
post = response.json()
print(f"Post created: {post['postGroupId']}")
# Check individual platform results after publishing
status_response = requests.get(
f"{API_URL}/get-post/{post['postGroupId']}",
headers=HEADERS
)
status = status_response.json()
if 'posts' in status:
for platform_post in status['posts']:
print(f" {platform_post['platform']}: {platform_post['status']}")
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "We are thrilled to announce that our platform now supports 10 social media channels!\n\nHere is what'\''s new:\n- Twitter/X threading for long posts\n- LinkedIn articles with rich formatting\n- Instagram Reels for video content\n- TikTok with automatic settings\n- YouTube with public visibility defaults\n- Facebook pages\n- Threads support\n- Telegram channels\n- Bluesky integration\n- Mastodon support\n\nThis has been months in the making, and we cannot wait for you to try it out.",
"platforms": [
"twitter-123456",
"linkedin-ABCDEF",
"threads-111213",
"telegram-141516",
"bluesky-171819"
],
"scheduledTime": "2026-03-15T10:00:00.000Z"
}'
# Check post status (replace POST_GROUP_ID with the actual postGroupId)
curl -s https://api.publora.com/api/v1/get-post/POST_GROUP_ID \
-H "x-publora-key: YOUR_API_KEY" | jq '.posts[]? | {platform, status}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
const longContent = `We are thrilled to announce that our platform now supports 10 social media channels!
Here is what's new:
- Twitter/X threading for long posts
- LinkedIn articles with rich formatting
- Instagram Reels for video content
- TikTok with automatic settings
- YouTube with public visibility defaults
- Facebook pages
- Threads support
- Telegram channels
- Bluesky integration
- Mastodon support
This has been months in the making, and we cannot wait for you to try it out. Visit our website to learn more and connect your accounts today.`;
const { data: post } = await api.post('/create-post', {
content: longContent,
platforms: [
'twitter-123456',
'linkedin-ABCDEF',
'threads-111213',
'telegram-141516',
'bluesky-171819'
],
scheduledTime: '2026-03-15T10:00:00.000Z'
});
console.log('Post created:', post.postGroupId);
// Check platform-level results after publishing
const { data: status } = await api.get(`/get-post/${post.postGroupId}`);
if (status.posts) {
for (const platformPost of status.posts) {
console.log(` ${platformPost.platform}: ${platformPost.status}`);
}
}
```
## Best Practices
1. **Keep text concise for multi-platform posts.** If you want the same text to appear identically on all platforms, keep it under 280 characters (the smallest common limit for Twitter/X). Otherwise, expect automatic threading on supported platforms or a validation error on platforms that do not support threading.
2. **Retrieve platform IDs dynamically.** Do not hardcode platform IDs. Use `GET /api/v1/platform-connections` to discover connected accounts, since users may add or remove connections.
3. **Check post status after publishing.** A post group may end up `partially_published` if some platforms succeed and others fail. Always inspect individual platform post statuses via `GET /api/v1/get-post/:postGroupId`.
4. **Be aware of media requirements per platform.** Instagram requires media; TikTok accepts a photo carousel or one video; YouTube requires video. Ensure shared media satisfies every target or use separate post groups.
5. **Test with a single platform first.** When developing your integration, start by posting to one platform, verify it works, and then expand to multiple platforms.
6. **Use the same post group for analytics.** Since all platform posts belong to one post group, you can track the overall performance of a campaign through a single postGroupId.
## Common Issues
| Problem | Cause | Solution |
|---|---|---|
| Post succeeds on some platforms but not others | Different requirements per platform (e.g., Instagram needs media) | Check which platforms need media and ensure your post includes it, or create separate post groups |
| Twitter or Threads post appears as a thread | Text exceeds the connected account's applicable limit (500 characters per part on Threads) | This is expected behavior -- Publora auto-threads long X/Twitter and Meta Threads content. A Threads chain needs `threads_manage_replies` on the connection |
| `400` error with invalid platform ID | Platform ID does not match the `{platform}-{id}` format, or account is not connected | Verify the format and check `GET /api/v1/platform-connections` for valid IDs |
| Content rejected on some platforms | Platform character limit is lower than your text length and platform does not support threading | Shorten content to fit within the platform's limit, or post to those platforms separately with shorter text |
| Video post fails on Instagram | Instagram requires specific video formats for Reels | Ensure your video is MP4, meets Instagram's aspect ratio requirements, and is within duration limits |
| `403` `PLATFORM_NOT_AVAILABLE` | The target platform connection is not available on the account (e.g. the account is not connected) | Connect the account in the dashboard, then retry |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/scheduling
# Scheduling Posts
This guide covers how to schedule social media posts through the Publora API, including creating drafts, scheduling for specific times, and managing post lifecycles.
## How It Works
Every post in Publora follows a lifecycle defined by its status:
```
status field: draft --> scheduled --> published
\-> failed
\-> partially_published
processingStatus field: pending --> processing --> finished
```
- **draft** -- A post saved without a `scheduledTime`. It will not be published until you update it with a valid time.
- **scheduled** -- A post with a future `scheduledTime`. The Publora scheduler checks for due posts every minute.
- **published** -- All platform posts succeeded.
- **failed** -- All platform posts failed.
- **partially_published** -- Some platform posts succeeded while others failed.
> **Note:** `processing` is **not** a value of the `status` field. Processing state is tracked separately via the `processingStatus` field, which transitions through `pending` -> `processing` -> `finished`. The `status` field only contains: `draft`, `scheduled`, `published`, `failed`, or `partially_published`.
### Key Rules
- `scheduledTime` must be in **ISO 8601 UTC format** (e.g., `2026-03-15T14:30:00.000Z`). An invalid format returns a `400 "Invalid scheduled time format"` error.
- A `scheduledTime` that is in the past or exactly equal to `now` (`scheduledTime <= now`) is **never silently accepted**. See [Past scheduled times](#past-scheduled-times) below -- the API either clamps it and warns you, or rejects it.
- The `scheduledPosts` limit counts active platform-level posts across the whole account for every plan. A post group targeting 3 platforms consumes 3 slots; it is not a per-connection limit.
- **Schedule horizon:** Starter plan users can schedule up to **7 days** in advance. Current Pro plans have no horizon limit. [`GET /account-context`](../endpoints/account-context.md) returns your exact `maxScheduledDate`.
- **Monthly post limits:** Starter allows **15 posts/month** (account-wide); current Pro plans allow **5,000 posts/month per connection** (fair use). Legacy plans keep their own limits — see [Rate Limits](rate-limits.md) and read your live numbers from [`GET /account-context`](../endpoints/account-context.md). Note: scheduled posts are counted per-platform post, not per post group. A single post group targeting 3 platforms counts as 3 posts toward your limit.
- **Starter plan can post to every platform except X/Twitter**; `allowedPlatforms` in [`GET /account-context`](../endpoints/account-context.md) lists the platforms of your plan.
- **Publish now:** send `publishNow: true` to [create-post](../endpoints/create-post.md#publish-now) or [update-post](../endpoints/update-post.md#publish-an-existing-post-now) to publish immediately at server time. It uses the monthly allowance but not the `scheduledPosts` queue or the horizon.
- The scheduler runs every minute, so posts are published within roughly 60 seconds of their scheduled time.
### Past scheduled times
Previously, a `scheduledTime` in the past was silently rewritten to the current time -- so "post at 09:00" computed a few seconds late, or a stale retry of an old request, published **immediately** with no signal. That is fixed: the API now always tells you.
| How far in the past | Today | When strict mode is active (scheduled **2026-08-25** by default) |
|---|---|---|
| Less than 5 minutes (clock skew) | Clamped to server time + `warnings` in the 2xx body | Unchanged -- still clamped + warned |
| 5 minutes or more | Clamped to server time + `warnings` in the 2xx body | **`400 SCHEDULED_TIME_IN_PAST`** |
The 5-minute tolerance for clock skew is permanent. The 5-minutes-or-more case is scheduled to become strict on 2026-08-25 unless production configuration overrides the date either way.
**Warning (2xx)** -- the post *was* created; `effective` is the time actually stored:
```json
{
"success": true,
"postGroupId": "664f1a2b3c4d5e6f7a8b9c0d",
"scheduledTime": "2026-03-15T14:30:02.104Z",
"warnings": [
{
"code": "SCHEDULED_TIME_COERCED",
"message": "Requested scheduled time 2026-03-15T14:29:58.000Z was in the past and was changed to server time 2026-03-15T14:30:02.104Z.",
"requested": "2026-03-15T14:29:58.000Z",
"effective": "2026-03-15T14:30:02.104Z"
}
]
}
```
**Rejection (400)** -- once the change lands, nothing is created:
```json
{
"error": "Scheduled time is in the past. Server time is 2026-03-15T14:30:02.104Z UTC.",
"code": "SCHEDULED_TIME_IN_PAST",
"serverTime": "2026-03-15T14:30:02.104Z"
}
```
`serverTime` is the authoritative UTC clock -- compare it against your own to detect drift, and retry with a `scheduledTime` after it.
**What to do now**
- Treat `SCHEDULED_TIME_COERCED` as an error in the making; strict mode is scheduled for 2026-08-25 unless production configuration overrides it.
- Build times from UTC (`new Date().toISOString()`, `datetime.now(timezone.utc)`), not local wall-clock.
- Add a small buffer (30-60s) when scheduling "now" to absorb network and clock skew.
- To confirm what the server kept, read the post back -- [`GET /get-post`](../endpoints/get-post.md) returns the stored **effective** `scheduledTime`, not what you asked for.
## Examples
### Schedule a Post for a Specific Time
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Excited to announce our new product launch!',
platforms: ['twitter-123', 'linkedin-ABC'],
scheduledTime: '2026-03-15T14:30:00.000Z'
})
});
const data = await response.json();
// Response: { success: true, postGroupId: "664f1a2b3c4d5e6f7a8b9c0d", scheduledTime: "2026-03-15T14:30:00.000Z" }
console.log('Post group created:', data.postGroupId);
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Excited to announce our new product launch!',
'platforms': ['twitter-123', 'linkedin-ABC'],
'scheduledTime': '2026-03-15T14:30:00.000Z'
}
)
data = response.json()
# Response: { "success": true, "postGroupId": "664f1a2b3c4d5e6f7a8b9c0d", "scheduledTime": "2026-03-15T14:30:00.000Z" }
print(f"Post group created: {data['postGroupId']}")
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Excited to announce our new product launch!",
"platforms": ["twitter-123", "linkedin-ABC"],
"scheduledTime": "2026-03-15T14:30:00.000Z"
}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const { data } = await axios.post(
'https://api.publora.com/api/v1/create-post',
{
content: 'Excited to announce our new product launch!',
platforms: ['twitter-123', 'linkedin-ABC'],
scheduledTime: '2026-03-15T14:30:00.000Z'
},
{
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
}
);
console.log('Post group created:', data.postGroupId);
```
---
### Create a Draft, Then Schedule It Later
Sometimes you want to prepare content first and schedule it at a later time. Omit `scheduledTime` to create a draft, then update it with a `PUT` request. When scheduling a draft, you must send **both** `scheduledTime` and `status: "scheduled"` in the update request.
> **Note:** Platform availability checks (`assertPlatformsAllowed`) run at `create-post` time for ALL posts, regardless of status. Other plan limits (monthly post count, scheduled post count, schedule horizon) run when a post transitions to `scheduled` status.
**JavaScript (fetch)**
```javascript
// Step 1: Create a draft (no scheduledTime)
const draftResponse = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Draft content that needs review before publishing.',
platforms: ['twitter-123', 'linkedin-ABC']
// No scheduledTime -- this creates a draft
})
});
const draft = await draftResponse.json();
console.log('Draft created:', draft.postGroupId);
// Step 2: After review, schedule the draft
const scheduleResponse = await fetch(
`https://api.publora.com/api/v1/update-post/${draft.postGroupId}`,
{
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-20T09:00:00.000Z'
})
}
);
const scheduled = await scheduleResponse.json();
// Response: { success: true, message: "Post updated successfully", scheduledTime: "2026-03-20T09:00:00.000Z", postGroup: { _id: "...", status: "scheduled", scheduledTime: "2026-03-20T09:00:00.000Z" } }
console.log('Now scheduled:', scheduled.postGroup.status); // "scheduled"
```
> **Note:** The `update-post` response always includes top-level `scheduledTime` (`null` for a draft), plus `message: "Post updated successfully"` and a `postGroup` object containing `_id`, `status`, and optionally its nested `scheduledTime` when scheduled.
**Python (requests)**
```python
import requests
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
# Step 1: Create a draft
draft_response = requests.post(
f'{API_URL}/create-post',
headers=HEADERS,
json={
'content': 'Draft content that needs review before publishing.',
'platforms': ['twitter-123', 'linkedin-ABC']
}
)
draft = draft_response.json()
print(f"Draft created: {draft['postGroupId']}")
# Step 2: Schedule the draft (both status and scheduledTime are required)
schedule_response = requests.put(
f"{API_URL}/update-post/{draft['postGroupId']}",
headers=HEADERS,
json={
'status': 'scheduled',
'scheduledTime': '2026-03-20T09:00:00.000Z'
}
)
scheduled = schedule_response.json()
print(f"Now scheduled: {scheduled['postGroup']['status']}") # "scheduled"
```
**cURL**
```bash
# Step 1: Create a draft
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Draft content that needs review before publishing.",
"platforms": ["twitter-123", "linkedin-ABC"]
}'
# Step 2: Schedule it (replace POST_GROUP_ID with the postGroupId from step 1)
curl -X PUT https://api.publora.com/api/v1/update-post/POST_GROUP_ID \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"status": "scheduled",
"scheduledTime": "2026-03-20T09:00:00.000Z"
}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
// Step 1: Create a draft
const { data: draft } = await api.post('/create-post', {
content: 'Draft content that needs review before publishing.',
platforms: ['twitter-123', 'linkedin-ABC']
});
console.log('Draft created:', draft.postGroupId);
// Step 2: Schedule the draft (both status and scheduledTime are required)
const { data: scheduled } = await api.put(`/update-post/${draft.postGroupId}`, {
status: 'scheduled',
scheduledTime: '2026-03-20T09:00:00.000Z'
});
console.log('Now scheduled:', scheduled.postGroup.status); // "scheduled"
```
---
### Batch Schedule a Week of Content
You can loop through a set of posts and schedule them across an entire week. This is useful for content calendars and automated pipelines.
**JavaScript (fetch)**
```javascript
const posts = [
{ content: 'Monday motivation: Start the week strong!', day: 1 },
{ content: 'Tuesday tip: Automate your social media with Publora.', day: 2 },
{ content: 'Wednesday wisdom: Consistency beats perfection.', day: 3 },
{ content: 'Thursday thought: Your audience is waiting.', day: 4 },
{ content: 'Friday feature: Check out our new analytics dashboard!', day: 5 },
{ content: 'Saturday story: How we built Publora.', day: 6 },
{ content: 'Sunday summary: Week in review.', day: 7 }
];
const baseDate = new Date('2026-03-16T10:00:00.000Z'); // Monday at 10 AM UTC
const results = [];
for (const post of posts) {
const scheduledTime = new Date(baseDate);
scheduledTime.setUTCDate(baseDate.getUTCDate() + (post.day - 1));
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: post.content,
platforms: ['twitter-123', 'linkedin-ABC'],
scheduledTime: scheduledTime.toISOString()
})
});
const data = await response.json();
results.push({ postGroupId: data.postGroupId, scheduledTime: scheduledTime.toISOString() });
console.log(`Scheduled "${post.content.slice(0, 30)}..." for ${scheduledTime.toISOString()}`);
}
console.log(`Successfully scheduled ${results.length} posts for the week.`);
```
**Python (requests)**
```python
import requests
from datetime import datetime, timedelta, timezone
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
posts = [
{'content': 'Monday motivation: Start the week strong!', 'day': 0},
{'content': 'Tuesday tip: Automate your social media with Publora.', 'day': 1},
{'content': 'Wednesday wisdom: Consistency beats perfection.', 'day': 2},
{'content': 'Thursday thought: Your audience is waiting.', 'day': 3},
{'content': 'Friday feature: Check out our new analytics dashboard!', 'day': 4},
{'content': 'Saturday story: How we built Publora.', 'day': 5},
{'content': 'Sunday summary: Week in review.', 'day': 6},
]
base_date = datetime(2026, 3, 16, 10, 0, 0, tzinfo=timezone.utc) # Monday 10 AM UTC
results = []
for post in posts:
scheduled_time = base_date + timedelta(days=post['day'])
response = requests.post(
f'{API_URL}/create-post',
headers=HEADERS,
json={
'content': post['content'],
'platforms': ['twitter-123', 'linkedin-ABC'],
'scheduledTime': scheduled_time.isoformat()
}
)
data = response.json()
results.append({'postGroupId': data['postGroupId'], 'scheduledTime': scheduled_time.isoformat()})
print(f"Scheduled: {post['content'][:30]}... for {scheduled_time.isoformat()}")
print(f"Successfully scheduled {len(results)} posts for the week.")
```
**cURL**
```bash
#!/bin/bash
API_KEY="YOUR_API_KEY"
BASE_URL="https://api.publora.com/api/v1/create-post"
TEXTS=(
"Monday motivation: Start the week strong!"
"Tuesday tip: Automate your social media with Publora."
"Wednesday wisdom: Consistency beats perfection."
"Thursday thought: Your audience is waiting."
"Friday feature: Check out our new analytics dashboard!"
"Saturday story: How we built Publora."
"Sunday summary: Week in review."
)
# Base date: Monday 2026-03-16 at 10:00 UTC
for i in "${!TEXTS[@]}"; do
SCHEDULED_TIME=$(date -u -d "2026-03-16 10:00:00 UTC + $i days" +"%Y-%m-%dT%H:%M:%S.000Z")
curl -s -X POST "$BASE_URL" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d "{
\"content\": \"${TEXTS[$i]}\",
\"platforms\": [\"twitter-123\", \"linkedin-ABC\"],
\"scheduledTime\": \"$SCHEDULED_TIME\"
}"
echo "Scheduled day $((i+1)): $SCHEDULED_TIME"
done
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
const posts = [
{ content: 'Monday motivation: Start the week strong!', day: 0 },
{ content: 'Tuesday tip: Automate your social media with Publora.', day: 1 },
{ content: 'Wednesday wisdom: Consistency beats perfection.', day: 2 },
{ content: 'Thursday thought: Your audience is waiting.', day: 3 },
{ content: 'Friday feature: Check out our new analytics dashboard!', day: 4 },
{ content: 'Saturday story: How we built Publora.', day: 5 },
{ content: 'Sunday summary: Week in review.', day: 6 },
];
const baseDate = new Date('2026-03-16T10:00:00.000Z');
const results = [];
for (const post of posts) {
const scheduledTime = new Date(baseDate);
scheduledTime.setUTCDate(baseDate.getUTCDate() + post.day);
const { data } = await api.post('/create-post', {
content: post.content,
platforms: ['twitter-123', 'linkedin-ABC'],
scheduledTime: scheduledTime.toISOString()
});
results.push({ postGroupId: data.postGroupId, scheduledTime: scheduledTime.toISOString() });
console.log(`Scheduled: ${post.content.slice(0, 30)}... for ${scheduledTime.toISOString()}`);
}
console.log(`Successfully scheduled ${results.length} posts for the week.`);
```
## Best Practices
1. **Always use UTC times.** Store and transmit all times in ISO 8601 UTC format. Convert to local time only in your UI layer.
2. **Schedule at least 2 minutes ahead.** Although the scheduler runs every minute, scheduling too close to "now" risks the post not being picked up in the current cycle.
3. **Monitor post status.** After scheduling, poll `GET /api/v1/get-post/:postGroupId` to check whether the post moved to `published`, `failed`, or `partially_published`.
4. **Respect Starter plan limits.** Starter plan users can have at most 3 pending (scheduled) posts and 15 posts per month. Exceeding these limits returns a `403` error with a structured `LimitExceededError` response. Upgrade your plan or wait for existing posts to publish before scheduling more.
5. **Use drafts for content approval workflows.** Create posts as drafts, pass them through your review process, and only set `scheduledTime` once approved.
6. **Spread out scheduling times.** Avoid scheduling dozens of posts for the exact same minute. Stagger them by a few minutes to ensure smooth processing.
## Common Issues
| Problem | Cause | Solution |
|---|---|---|
| `400 "Invalid scheduled time format"` | The `scheduledTime` is not valid ISO 8601 | Use `YYYY-MM-DDTHH:mm:ss.sssZ`. Past times follow the warned clamp/strict-rejection policy above; they are never silently rounded. |
| `403` limit exceeded | More than 3 pending posts on the Starter plan, or monthly limit reached | Wait for existing posts to publish, delete some, or upgrade your plan. The response includes a structured `LimitExceededError` with `metric`, `limit`, `used`, and `remaining` fields |
| Post stuck in `scheduled` status | The scheduled time has not arrived yet | Check the `scheduledTime` field -- the scheduler runs every minute |
| `400 "Cannot update post: post is currently in {status} status"` | Trying to reschedule a post that is in a non-editable status | Only `draft` and `scheduled` posts can be updated |
| Post shows `partially_published` | Some platforms succeeded, others failed | Check the individual platform post statuses within the post group for details |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/bulk-scheduling
# Bulk Scheduling Guide
Schedule multiple posts at once using batch operations, CSV imports, and content calendars.
## Overview
Bulk scheduling allows you to:
- Schedule a week or month of content in one script
- Import posts from CSV or spreadsheets
- Create content calendars with automated publishing
- Batch update or delete multiple posts
## Schedule Multiple Posts
### JavaScript: Schedule a Week of Content
```javascript
const PUBLORA_API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
const headers = {
'Content-Type': 'application/json',
'x-publora-key': PUBLORA_API_KEY
};
async function scheduleWeekOfContent(posts, platforms, startDate = new Date()) {
const results = [];
for (let i = 0; i < posts.length; i++) {
// Schedule each post on a different day at 10 AM UTC
const scheduledDate = new Date(startDate);
scheduledDate.setDate(startDate.getDate() + i);
scheduledDate.setUTCHours(10, 0, 0, 0);
const response = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers,
body: JSON.stringify({
content: posts[i].content,
platforms,
scheduledTime: scheduledDate.toISOString()
})
});
const result = await response.json();
results.push({
day: i + 1,
date: scheduledDate.toDateString(),
postGroupId: result.postGroupId,
success: response.ok
});
console.log(`Day ${i + 1}: ${response.ok ? '✓' : '✗'} ${scheduledDate.toDateString()}`);
// Small delay to avoid rate limits
await new Promise(r => setTimeout(r, 200));
}
return results;
}
// Example: 7 days of content
const weeklyPosts = [
{ content: 'Monday motivation: Start your week with intention!' },
{ content: 'Tech tip Tuesday: Always version your APIs.' },
{ content: 'Wednesday wisdom: Ship fast, iterate faster.' },
{ content: 'Throwback Thursday: How we grew from 0 to 10K users.' },
{ content: 'Feature Friday: Check out our new analytics dashboard!' },
{ content: 'Saturday reading: Top 5 dev articles this week.' },
{ content: 'Sunday reflection: What will you build next week?' }
];
scheduleWeekOfContent(weeklyPosts, ['twitter-123456', 'linkedin-ABC123']);
```
### Python: Schedule a Month of Content
```python
import requests
from datetime import datetime, timedelta
import time
PUBLORA_API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.publora.com/api/v1'
headers = {
'Content-Type': 'application/json',
'x-publora-key': PUBLORA_API_KEY
}
def schedule_month_of_content(posts, platforms, start_date=None):
if start_date is None:
start_date = datetime.utcnow()
results = []
for i, post in enumerate(posts):
scheduled_date = start_date + timedelta(days=i)
scheduled_date = scheduled_date.replace(hour=10, minute=0, second=0, microsecond=0)
response = requests.post(
f'{BASE_URL}/create-post',
headers=headers,
json={
'content': post['content'],
'platforms': platforms,
'scheduledTime': scheduled_date.isoformat() + 'Z'
}
)
result = {
'day': i + 1,
'date': scheduled_date.strftime('%Y-%m-%d'),
'success': response.ok
}
if response.ok:
result['postGroupId'] = response.json()['postGroupId']
results.append(result)
print(f"Day {i + 1}: {'✓' if response.ok else '✗'} {scheduled_date.strftime('%Y-%m-%d')}")
time.sleep(0.2) # Rate limiting
successful = sum(1 for r in results if r['success'])
print(f"\nScheduled {successful}/{len(posts)} posts")
return results
# Example: Generate 30 days of content
monthly_posts = [
{'content': f'Day {i+1} of our 30-day challenge! #30daychallenge'}
for i in range(30)
]
schedule_month_of_content(monthly_posts, ['twitter-123456'])
```
## Import from CSV
### CSV Format
Create a CSV file with your content:
```csv
content,platforms,scheduled_time
"Monday motivation: Start strong!",twitter-123456;linkedin-ABC123,2026-03-01T09:00:00Z
"Check out our new feature!",twitter-123456,2026-03-01T14:00:00Z
"Weekly roundup thread",twitter-123456,2026-03-02T10:00:00Z
"LinkedIn deep dive post",linkedin-ABC123,2026-03-02T12:00:00Z
"Behind the scenes",instagram-789012,2026-03-03T11:00:00Z
```
### JavaScript CSV Import
```javascript
const fs = require('fs');
const csv = require('csv-parse/sync');
async function importFromCSV(filePath) {
const fileContent = fs.readFileSync(filePath, 'utf-8');
const records = csv.parse(fileContent, {
columns: true,
skip_empty_lines: true
});
const results = [];
for (const row of records) {
const platforms = row.platforms.split(';').map(p => p.trim());
const payload = {
content: row.content,
platforms,
scheduledTime: row.scheduled_time
};
const response = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers,
body: JSON.stringify(payload)
});
const result = await response.json();
results.push({
content: row.content.substring(0, 30) + '...',
success: response.ok,
postGroupId: result.postGroupId
});
console.log(`${response.ok ? '✓' : '✗'} ${row.content.substring(0, 40)}...`);
await new Promise(r => setTimeout(r, 200));
}
const successful = results.filter(r => r.success).length;
console.log(`\nImported ${successful}/${results.length} posts`);
return results;
}
importFromCSV('./posts.csv');
```
### Python CSV Import
```python
import csv
import requests
import time
def import_from_csv(file_path):
results = []
with open(file_path, 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
for row in reader:
platforms = [p.strip() for p in row['platforms'].split(';')]
payload = {
'content': row['content'],
'platforms': platforms,
'scheduledTime': row['scheduled_time']
}
response = requests.post(
f'{BASE_URL}/create-post',
headers=headers,
json=payload
)
result = {
'content': row['content'][:30] + '...',
'success': response.ok
}
if response.ok:
result['postGroupId'] = response.json()['postGroupId']
else:
result['error'] = response.json().get('error', 'Unknown error')
results.append(result)
status = '✓' if response.ok else '✗'
print(f"{status} {row['content'][:40]}...")
time.sleep(0.2)
successful = sum(1 for r in results if r['success'])
print(f"\nImported {successful}/{len(results)} posts")
return results
import_from_csv('posts.csv')
```
## Content Calendar Patterns
### Schedule at Optimal Times
```javascript
// Optimal posting times by platform (UTC)
const OPTIMAL_TIMES = {
twitter: [9, 12, 17], // 9 AM, 12 PM, 5 PM
linkedin: [7, 10, 17], // 7 AM, 10 AM, 5 PM
instagram: [11, 14, 19], // 11 AM, 2 PM, 7 PM
facebook: [9, 13, 16] // 9 AM, 1 PM, 4 PM
};
function getOptimalTime(platform, dayOffset = 0) {
const times = OPTIMAL_TIMES[platform] || [10];
const randomTime = times[Math.floor(Math.random() * times.length)];
const date = new Date();
date.setDate(date.getDate() + dayOffset);
date.setUTCHours(randomTime, 0, 0, 0);
return date;
}
async function scheduleAtOptimalTimes(posts) {
for (let i = 0; i < posts.length; i++) {
const post = posts[i];
for (const platformId of post.platforms) {
const platform = platformId.split('-')[0];
const optimalTime = getOptimalTime(platform, i);
await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers,
body: JSON.stringify({
content: post.content,
platforms: [platformId],
scheduledTime: optimalTime.toISOString()
})
});
console.log(`Scheduled for ${platform} at ${optimalTime.toISOString()}`);
}
}
}
```
### Stagger Posts Across Platforms
```javascript
async function staggerAcrossPlatforms(content, platforms, baseTime, intervalMinutes = 30) {
const results = [];
for (let i = 0; i < platforms.length; i++) {
const scheduledTime = new Date(baseTime);
scheduledTime.setMinutes(scheduledTime.getMinutes() + (i * intervalMinutes));
const response = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers,
body: JSON.stringify({
content,
platforms: [platforms[i]],
scheduledTime: scheduledTime.toISOString()
})
});
results.push({
platform: platforms[i],
scheduledTime: scheduledTime.toISOString(),
success: response.ok
});
}
return results;
}
// Post to Twitter at 10:00, LinkedIn at 10:30, Threads at 11:00
staggerAcrossPlatforms(
'Exciting announcement coming!',
['twitter-123456', 'linkedin-ABC123', 'threads-789012'],
new Date('2026-03-01T10:00:00Z'),
30
);
```
### Weekly Recurring Schedule
```javascript
async function createWeeklyRecurring(content, platforms, dayOfWeek, timeUTC, weeks = 4) {
const results = [];
// Find next occurrence of dayOfWeek (0 = Sunday, 1 = Monday, etc.)
const startDate = new Date();
while (startDate.getDay() !== dayOfWeek) {
startDate.setDate(startDate.getDate() + 1);
}
startDate.setUTCHours(timeUTC, 0, 0, 0);
for (let i = 0; i < weeks; i++) {
const scheduledTime = new Date(startDate);
scheduledTime.setDate(startDate.getDate() + (i * 7));
const response = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers,
body: JSON.stringify({
content,
platforms,
scheduledTime: scheduledTime.toISOString()
})
});
results.push({
week: i + 1,
scheduledTime: scheduledTime.toISOString(),
success: response.ok
});
console.log(`Week ${i + 1}: ${scheduledTime.toDateString()}`);
}
return results;
}
// Post every Monday at 9 AM UTC for 4 weeks
createWeeklyRecurring(
'Happy Monday! What are your goals this week?',
['twitter-123456', 'linkedin-ABC123'],
1, // Monday
9, // 9 AM UTC
4 // 4 weeks
);
```
## Batch Operations
### Retrieve Draft Post IDs
Before performing batch operations, you can retrieve your existing posts (including drafts) using the `list-posts` endpoint:
```javascript
// List all draft posts
const response = await fetch(`${BASE_URL}/list-posts?status=draft`, {
headers: { 'x-publora-key': PUBLORA_API_KEY }
});
const { posts } = await response.json();
const draftIds = posts.map(pg => pg.postGroupId);
console.log(`Found ${draftIds.length} drafts:`, draftIds);
```
```python
# List all draft posts
response = requests.get(
f'{BASE_URL}/list-posts',
headers={'x-publora-key': PUBLORA_API_KEY},
params={'status': 'draft'}
)
posts = response.json()['posts']
draft_ids = [pg['postGroupId'] for pg in posts]
print(f"Found {len(draft_ids)} drafts:", draft_ids)
```
> **Note:** Post group IDs (`postGroupId`) are MongoDB ObjectIds (e.g., `6626a1f5e4b0c91a2d3f4567`). The `list-posts` endpoint returns results in a `posts` array and supports the following query parameters:
>
> | Parameter | Type | Description |
> |---|---|---|
> | `status` | `string` | Filter by status: `draft`, `scheduled`, `published`, `failed`, `partially_published` |
> | `platform` | `string` | Filter by platform (e.g., `twitter`, `linkedin`) |
> | `page` | `number` | Page number (default: 1) |
> | `limit` | `number` | Results per page (default: 20) |
> | `fromDate` | `string` | Filter posts scheduled on or after this ISO 8601 date |
> | `toDate` | `string` | Filter posts scheduled on or before this ISO 8601 date |
> | `sortBy` | `string` | Field to sort by: `createdAt`, `updatedAt`, or `scheduledTime` |
> | `sortOrder` | `string` | Sort direction: `asc` or `desc` |
>
> The response includes a `pagination` object alongside the `posts` array:
> ```json
> {
> "success": true,
> "posts": [...],
> "pagination": {
> "page": 1,
> "limit": 20,
> "totalItems": 47,
> "totalPages": 3,
> "hasNextPage": true,
> "hasPrevPage": false
> }
> }
> ```
### Batch Update Scheduled Times
```javascript
async function batchReschedule(postGroupIds, newBaseTime, intervalHours = 2) {
const results = [];
for (let i = 0; i < postGroupIds.length; i++) {
const newTime = new Date(newBaseTime);
newTime.setHours(newTime.getHours() + (i * intervalHours));
const response = await fetch(`${BASE_URL}/update-post/${postGroupIds[i]}`, {
method: 'PUT',
headers,
body: JSON.stringify({
status: 'scheduled',
scheduledTime: newTime.toISOString()
})
});
results.push({
postGroupId: postGroupIds[i],
newTime: newTime.toISOString(),
success: response.ok
});
}
return results;
}
// Reschedule all posts starting from a new date
batchReschedule(
['6626a1f5e4b0c91a2d3f4567', '6626a1f5e4b0c91a2d3f4568', '6626a1f5e4b0c91a2d3f4569'],
new Date('2026-03-15T10:00:00Z'),
2 // 2 hours apart
);
```
### Batch Delete
> **Note:** The `delete-post` endpoint returns `{ "success": true }` on success.
```javascript
async function batchDelete(postGroupIds) {
const results = [];
for (const postGroupId of postGroupIds) {
const response = await fetch(`${BASE_URL}/delete-post/${postGroupId}`, {
method: 'DELETE',
headers: { 'x-publora-key': PUBLORA_API_KEY }
});
results.push({
postGroupId,
success: response.ok
});
await new Promise(r => setTimeout(r, 100));
}
const successful = results.filter(r => r.success).length;
console.log(`Deleted ${successful}/${results.length} posts`);
return results;
}
```
### Convert Drafts to Scheduled
```javascript
async function publishAllDrafts(draftIds, startTime, intervalMinutes = 60) {
const results = [];
for (let i = 0; i < draftIds.length; i++) {
const scheduledTime = new Date(startTime);
scheduledTime.setMinutes(scheduledTime.getMinutes() + (i * intervalMinutes));
const response = await fetch(`${BASE_URL}/update-post/${draftIds[i]}`, {
method: 'PUT',
headers,
body: JSON.stringify({
status: 'scheduled',
scheduledTime: scheduledTime.toISOString()
})
});
results.push({
postGroupId: draftIds[i],
scheduledTime: scheduledTime.toISOString(),
success: response.ok
});
}
return results;
}
```
## Rate Limiting Best Practices
```javascript
class RateLimitedScheduler {
constructor(apiKey, requestsPerSecond = 5) {
this.apiKey = apiKey;
this.minInterval = 1000 / requestsPerSecond;
this.lastRequest = 0;
}
async schedule(post) {
// Wait if needed to respect rate limit
const now = Date.now();
const elapsed = now - this.lastRequest;
if (elapsed < this.minInterval) {
await new Promise(r => setTimeout(r, this.minInterval - elapsed));
}
this.lastRequest = Date.now();
const response = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': this.apiKey
},
body: JSON.stringify(post)
});
return response.json();
}
async scheduleBatch(posts) {
const results = [];
for (const post of posts) {
const result = await this.schedule(post);
results.push(result);
}
return results;
}
}
// Usage
const scheduler = new RateLimitedScheduler(PUBLORA_API_KEY, 5);
const posts = [
{ content: 'Post 1', platforms: ['twitter-123456'], scheduledTime: '2026-03-01T10:00:00Z' },
{ content: 'Post 2', platforms: ['twitter-123456'], scheduledTime: '2026-03-01T12:00:00Z' },
{ content: 'Post 3', platforms: ['twitter-123456'], scheduledTime: '2026-03-01T14:00:00Z' }
];
scheduler.scheduleBatch(posts);
```
## Error Handling
```javascript
async function scheduleWithRetry(post, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers,
body: JSON.stringify(post)
});
if (response.ok) {
return { success: true, data: await response.json() };
}
const error = await response.json();
// Most client errors should not be retried unchanged.
// mediaUrls ingestion can return 429 MEDIA_URL_RATE_LIMITED with Retry-After.
if (response.status === 429 && error.code === 'MEDIA_URL_RATE_LIMITED') {
const retryAfter = Number(response.headers.get('Retry-After') || 60);
await new Promise(r => setTimeout(r, retryAfter * 1000));
continue;
}
if (response.status >= 400 && response.status < 500) {
return { success: false, error: error.error || error.message };
}
} catch (error) {
if (attempt === maxRetries) {
return { success: false, error: error.error || error.message };
}
await new Promise(r => setTimeout(r, 1000 * attempt));
}
}
return { success: false, error: 'Max retries exceeded' };
}
```
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/media-uploads
# Media Uploads
This guide covers how to upload images, videos, and PDF document assets to Publora using pre-signed S3 URLs, and how to attach post media to your scheduled posts.
## How It Works
Publora uses a **pre-signed S3 URL workflow** for media uploads. This means your files are uploaded directly to cloud storage without passing through the Publora API server, ensuring fast and reliable transfers.
The workflow has three steps:
```
1. Create a post group first POST /api/v1/create-post
2. Request a pre-signed upload URL POST /api/v1/get-upload-url (with postGroupId)
3. Upload the file directly to S3 PUT {uploadUrl}
```
Media is automatically attached to the post group via the `postGroupId` you provide when requesting the upload URL.
> **Note:** Pre-signed upload URLs expire after **1 hour**. If you do not complete the upload within that time, request a new URL via `POST /api/v1/get-upload-url`.
> **⚠ Attach/remove media on a *scheduled* post = demoted to draft.** Requesting an upload URL (`get-upload-url`) or deleting media (`DELETE /api/v1/media/:mediaId`) for a post that is already `scheduled` demotes it back to `draft` so the changed media set is re-validated. The response carries `postGroupDemoted: true`. **Re-schedule** with `update-post` (`status: "scheduled"`) afterward, or the post never publishes. Build media on a **draft** first to avoid this entirely.
> **One-shot alternative:** `create-post` (and `update-post`) accept an optional `mediaUrls` array of public **https** URLs (up to 10). Publora downloads them server-side and attaches them before validation, so you can attach media and schedule in a single call — no `get-upload-url`/`PUT`/`complete-media` round-trip. Rate-limited to 60 URLs/hour.
> **File-reference alternative (ChatGPT):** [`POST /attach-media/:postGroupId`](../endpoints/attach-media.md), or the MCP tool `attach_media`, attaches one image or video from an HTTPS download URL plus a stable file ID. That is the form in which ChatGPT supplies a file from the conversation. You can pass an optional descriptive `fileName`. Publora downloads the file right away, so there is no `get-upload-url`/`PUT`/`complete-media` step. When you send an `Idempotency-Key` (the MCP tool always does), a retry with a refreshed URL is matched on the post, file ID and file name and doesn't attach a duplicate; without one, every call attaches another copy. It uses the same 60 URLs/hour allowance and always leaves the post in `draft`, so schedule it with `update-post` afterward.
### Supported Formats
| Upload family | Accepted by `get-upload-url` |
|---|---|
| Images | Any `image/*` MIME type |
| Videos | Any `video/*` MIME type |
| Documents | `application/pdf` |
These are the upload-family gates. Scheduling applies the destination platform's stricter image/video format and count allowlists; PDF files are document assets, not ordinary post-media carousel items.
### Limits
- **Upload size:** The public presigned flow signs one S3 `PutObject`, so its effective upload ceiling is 5 GB before any lower destination-platform limit applies. Platform tables describe validation limits, not a multipart upload capability: files larger than 5 GB are not currently uploadable through the public API. The dashboard-only `/media/process-video` route has a separate 512 MB multer cap.
- **Per post:** Twitter/X, Bluesky, and Mastodon allow up to **4 images**; Instagram allows **10**, Threads **20**, and LinkedIn, Facebook, and Telegram **10**. Video posts are limited to **1 video** per post. These limits are validated at the scheduling gate.
- **Instagram restriction:** Instagram does not allow mixing images and videos in the same post. A post must contain either all images or a single video. This is validated at scheduling time.
- **Threads carousels:** Up to **20 images** (video items in carousels are not currently supported by Publora; standalone video posts work normally)
### Automatic Processing
- **WebP images** are automatically converted to JPEG for platforms that do not support WebP natively.
- **Video metadata** is automatically extracted upon upload, including: resolution, codec, FPS, bitrate, duration, and aspect ratio. This metadata is used for platform-specific validation (e.g., TikTok FPS requirements).
## Examples
### Upload an Image and Create a Post
> **Important:** Create the post as a **draft** (omit `scheduledTime`), upload media, then schedule via update-post. This ensures media is fully uploaded before the scheduler processes your post.
**JavaScript (fetch)**
```javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
// Step 1: Create a draft post (no scheduledTime)
const postResponse = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
content: 'Check out our latest product!',
platforms: ['twitter-123', 'linkedin-ABC', 'instagram-456']
// No scheduledTime = draft
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Get a pre-signed upload URL
const uploadUrlResponse = await fetch(`${BASE_URL}/get-upload-url`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
fileName: 'product-photo.jpg',
contentType: 'image/jpeg',
type: 'image',
postGroupId: postGroupId
})
});
const { success, uploadUrl, fileUrl, mediaId } = await uploadUrlResponse.json();
// Response: { success: true, uploadUrl: "...", fileUrl: "...", mediaId: "..." }
// Step 3: Upload the file directly to S3
const fileBuffer = await fs.promises.readFile('./product-photo.jpg');
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: fileBuffer
});
console.log('Image uploaded:', fileUrl);
// Step 4: Schedule the post
await fetch(`${BASE_URL}/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-15T14:30:00.000Z'
})
});
console.log('Post scheduled!');
```
**Python (requests)**
```python
import requests
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
# Step 1: Create a draft post (no scheduledTime)
post_response = requests.post(
f'{API_URL}/create-post',
headers=HEADERS,
json={
'content': 'Check out our latest product!',
'platforms': ['twitter-123', 'linkedin-ABC', 'instagram-456']
# No scheduledTime = draft
}
)
post_group_id = post_response.json()['postGroupId']
# Step 2: Get a pre-signed upload URL
upload_url_response = requests.post(
f'{API_URL}/get-upload-url',
headers=HEADERS,
json={
'fileName': 'product-photo.jpg',
'contentType': 'image/jpeg',
'type': 'image',
'postGroupId': post_group_id
}
)
upload_data = upload_url_response.json()
# Step 3: Upload the file directly to S3
with open('./product-photo.jpg', 'rb') as f:
requests.put(
upload_data['uploadUrl'],
headers={'Content-Type': 'image/jpeg'},
data=f.read()
)
print(f"Image uploaded: {upload_data['fileUrl']}")
# Step 4: Schedule the post
requests.put(
f'{API_URL}/update-post/{post_group_id}',
headers=HEADERS,
json={
'status': 'scheduled',
'scheduledTime': '2026-03-15T14:30:00.000Z'
}
)
print('Post scheduled!')
```
**cURL**
```bash
API_KEY="YOUR_API_KEY"
# Step 1: Create a draft post (no scheduledTime)
POST_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"content": "Check out our latest product!",
"platforms": ["twitter-123", "linkedin-ABC", "instagram-456"]
}')
POST_GROUP_ID=$(echo "$POST_RESPONSE" | jq -r '.postGroupId')
# Step 2: Get a pre-signed upload URL
UPLOAD_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/get-upload-url \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d "{
\"fileName\": \"product-photo.jpg\",
\"contentType\": \"image/jpeg\",
\"type\": \"image\",
\"postGroupId\": \"$POST_GROUP_ID\"
}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
# Step 3: Upload the file directly to S3
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
--data-binary @./product-photo.jpg
# Step 4: Schedule the post
curl -X PUT "https://api.publora.com/api/v1/update-post/$POST_GROUP_ID" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"status": "scheduled",
"scheduledTime": "2026-03-15T14:30:00.000Z"
}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const fs = require('fs');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
// Step 1: Create a draft post (no scheduledTime)
const { data: postData } = await api.post('/create-post', {
content: 'Check out our latest product!',
platforms: ['twitter-123', 'linkedin-ABC', 'instagram-456']
// No scheduledTime = draft
});
// Step 2: Get a pre-signed upload URL
const { data: uploadData } = await api.post('/get-upload-url', {
fileName: 'product-photo.jpg',
contentType: 'image/jpeg',
type: 'image',
postGroupId: postData.postGroupId
});
// Step 3: Upload the file directly to S3
const fileBuffer = fs.readFileSync('./product-photo.jpg');
await axios.put(uploadData.uploadUrl, fileBuffer, {
headers: { 'Content-Type': 'image/jpeg' }
});
console.log('Image uploaded:', uploadData.fileUrl);
// Step 4: Schedule the post
await api.put(`/update-post/${postData.postGroupId}`, {
status: 'scheduled',
scheduledTime: '2026-03-15T14:30:00.000Z'
});
console.log('Post scheduled!');
```
---
### Upload a Video and Create a Post
> **Important:** Create the post as a **draft** first, upload the video, then schedule.
**JavaScript (fetch)**
```javascript
const fs = require('fs');
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
// Step 1: Create a draft post (no scheduledTime)
const postResponse = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
content: 'Watch our latest promo video!',
platforms: ['twitter-123', 'tiktok-789', 'youtube-012']
// No scheduledTime = draft
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Get a pre-signed upload URL for the video
const uploadUrlResponse = await fetch(`${BASE_URL}/get-upload-url`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
fileName: 'promo-video.mp4',
contentType: 'video/mp4',
type: 'video',
postGroupId: postGroupId
})
});
const { uploadUrl } = await uploadUrlResponse.json();
// Step 3: Upload the video to S3
const videoBuffer = await fs.promises.readFile('./promo-video.mp4');
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'video/mp4' },
body: videoBuffer
});
console.log('Video uploaded:', postGroupId);
// Step 4: Schedule the post
await fetch(`${BASE_URL}/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-15T16:00:00.000Z'
})
});
console.log('Post scheduled!');
```
**Python (requests)**
```python
import requests
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
# Step 1: Create a draft post (no scheduledTime)
post_response = requests.post(
f'{API_URL}/create-post',
headers=HEADERS,
json={
'content': 'Watch our latest promo video!',
'platforms': ['twitter-123', 'tiktok-789', 'youtube-012']
# No scheduledTime = draft
}
)
post_group_id = post_response.json()['postGroupId']
# Step 2: Get a pre-signed upload URL
upload_response = requests.post(
f'{API_URL}/get-upload-url',
headers=HEADERS,
json={
'fileName': 'promo-video.mp4',
'contentType': 'video/mp4',
'type': 'video',
'postGroupId': post_group_id
}
)
upload_url = upload_response.json()['uploadUrl']
# Step 3: Upload the video to S3
with open('./promo-video.mp4', 'rb') as f:
requests.put(upload_url, headers={'Content-Type': 'video/mp4'}, data=f.read())
print(f"Video uploaded: {post_group_id}")
# Step 4: Schedule the post
requests.put(
f'{API_URL}/update-post/{post_group_id}',
headers=HEADERS,
json={
'status': 'scheduled',
'scheduledTime': '2026-03-15T16:00:00.000Z'
}
)
print('Post scheduled!')
```
**cURL**
```bash
API_KEY="YOUR_API_KEY"
# Step 1: Create a draft post (no scheduledTime)
POST_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"content": "Watch our latest promo video!",
"platforms": ["twitter-123", "tiktok-789", "youtube-012"]
}')
POST_GROUP_ID=$(echo "$POST_RESPONSE" | jq -r '.postGroupId')
# Step 2: Get upload URL
UPLOAD_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/get-upload-url \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d "{
\"fileName\": \"promo-video.mp4\",
\"contentType\": \"video/mp4\",
\"type\": \"video\",
\"postGroupId\": \"$POST_GROUP_ID\"
}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
# Step 3: Upload video to S3
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--data-binary @./promo-video.mp4
# Step 4: Schedule the post
curl -X PUT "https://api.publora.com/api/v1/update-post/$POST_GROUP_ID" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"status": "scheduled",
"scheduledTime": "2026-03-15T16:00:00.000Z"
}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const fs = require('fs');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
// Step 1: Create a draft post (no scheduledTime)
const { data: postData } = await api.post('/create-post', {
content: 'Watch our latest promo video!',
platforms: ['twitter-123', 'tiktok-789', 'youtube-012']
// No scheduledTime = draft
});
// Step 2: Get upload URL
const { data: uploadData } = await api.post('/get-upload-url', {
fileName: 'promo-video.mp4',
contentType: 'video/mp4',
type: 'video',
postGroupId: postData.postGroupId
});
// Step 3: Upload video
const videoBuffer = fs.readFileSync('./promo-video.mp4');
await axios.put(uploadData.uploadUrl, videoBuffer, {
headers: { 'Content-Type': 'video/mp4' },
maxContentLength: Infinity,
maxBodyLength: Infinity
});
console.log('Video uploaded:', postData.postGroupId);
// Step 4: Schedule the post
await api.put(`/update-post/${postData.postGroupId}`, {
status: 'scheduled',
scheduledTime: '2026-03-15T16:00:00.000Z'
});
console.log('Post scheduled!');
```
---
### Upload Multiple Images for a Carousel Post
You can attach multiple images to a single post (the limit varies by platform). Each image requires its own upload URL.
> **Important:** Create the post as a **draft** first, upload all images, then schedule.
**JavaScript (fetch)**
```javascript
const fs = require('fs');
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
// Step 1: Create a draft post (no scheduledTime)
const postResponse = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
content: 'Our product lineup for 2026 -- swipe to see all!',
platforms: ['twitter-123', 'linkedin-ABC', 'instagram-456']
// No scheduledTime = draft
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Upload each image
const images = [
{ path: './slide1.jpg', name: 'slide1.jpg', type: 'image/jpeg' },
{ path: './slide2.png', name: 'slide2.png', type: 'image/png' },
{ path: './slide3.jpg', name: 'slide3.jpg', type: 'image/jpeg' },
{ path: './slide4.jpg', name: 'slide4.jpg', type: 'image/jpeg' }
];
for (const image of images) {
// Get upload URL for each image
const uploadUrlResponse = await fetch(`${BASE_URL}/get-upload-url`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
fileName: image.name,
contentType: image.type,
type: 'image',
postGroupId: postGroupId
})
});
const { uploadUrl } = await uploadUrlResponse.json();
// Upload the file to S3
const fileBuffer = await fs.promises.readFile(image.path);
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': image.type },
body: fileBuffer
});
console.log(`Uploaded ${image.name}`);
}
// Step 3: Schedule the post
await fetch(`${BASE_URL}/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-15T12:00:00.000Z'
})
});
console.log('Carousel post scheduled!');
```
**Python (requests)**
```python
import requests
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
# Step 1: Create a draft post (no scheduledTime)
post_response = requests.post(
f'{API_URL}/create-post',
headers=HEADERS,
json={
'content': 'Our product lineup for 2026 -- swipe to see all!',
'platforms': ['twitter-123', 'linkedin-ABC', 'instagram-456']
# No scheduledTime = draft
}
)
post_group_id = post_response.json()['postGroupId']
# Step 2: Upload each image
images = [
{'path': './slide1.jpg', 'name': 'slide1.jpg', 'type': 'image/jpeg'},
{'path': './slide2.png', 'name': 'slide2.png', 'type': 'image/png'},
{'path': './slide3.jpg', 'name': 'slide3.jpg', 'type': 'image/jpeg'},
{'path': './slide4.jpg', 'name': 'slide4.jpg', 'type': 'image/jpeg'},
]
for image in images:
# Get upload URL
upload_response = requests.post(
f'{API_URL}/get-upload-url',
headers=HEADERS,
json={
'fileName': image['name'],
'contentType': image['type'],
'type': 'image',
'postGroupId': post_group_id
}
)
upload_data = upload_response.json()
# Upload to S3
with open(image['path'], 'rb') as f:
requests.put(
upload_data['uploadUrl'],
headers={'Content-Type': image['type']},
data=f.read()
)
print(f"Uploaded {image['name']}")
# Step 3: Schedule the post
requests.put(
f'{API_URL}/update-post/{post_group_id}',
headers=HEADERS,
json={
'status': 'scheduled',
'scheduledTime': '2026-03-15T12:00:00.000Z'
}
)
print('Carousel post scheduled!')
```
**cURL**
```bash
API_KEY="YOUR_API_KEY"
# Step 1: Create a draft post (no scheduledTime)
POST_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"content": "Our product lineup for 2026 -- swipe to see all!",
"platforms": ["twitter-123", "linkedin-ABC", "instagram-456"]
}')
POST_GROUP_ID=$(echo "$POST_RESPONSE" | jq -r '.postGroupId')
# Step 2: Upload 4 images
for FILE in slide1.jpg slide2.png slide3.jpg slide4.jpg; do
CONTENT_TYPE="image/jpeg"
if [[ "$FILE" == *.png ]]; then
CONTENT_TYPE="image/png"
fi
UPLOAD_RESPONSE=$(curl -s -X POST https://api.publora.com/api/v1/get-upload-url \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d "{
\"fileName\": \"$FILE\",
\"contentType\": \"$CONTENT_TYPE\",
\"type\": \"image\",
\"postGroupId\": \"$POST_GROUP_ID\"
}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
curl -s -X PUT "$UPLOAD_URL" \
-H "Content-Type: $CONTENT_TYPE" \
--data-binary @"./$FILE"
echo "Uploaded $FILE"
done
# Step 3: Schedule the post
curl -X PUT "https://api.publora.com/api/v1/update-post/$POST_GROUP_ID" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"status": "scheduled",
"scheduledTime": "2026-03-15T12:00:00.000Z"
}'
```
**Node.js (axios)**
```javascript
const axios = require('axios');
const fs = require('fs');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
// Step 1: Create a draft post (no scheduledTime)
const { data: postData } = await api.post('/create-post', {
content: 'Our product lineup for 2026 -- swipe to see all!',
platforms: ['twitter-123', 'linkedin-ABC', 'instagram-456']
// No scheduledTime = draft
});
// Step 2: Upload each image
const images = [
{ path: './slide1.jpg', name: 'slide1.jpg', type: 'image/jpeg' },
{ path: './slide2.png', name: 'slide2.png', type: 'image/png' },
{ path: './slide3.jpg', name: 'slide3.jpg', type: 'image/jpeg' },
{ path: './slide4.jpg', name: 'slide4.jpg', type: 'image/jpeg' }
];
for (const image of images) {
const { data: uploadData } = await api.post('/get-upload-url', {
fileName: image.name,
contentType: image.type,
type: 'image',
postGroupId: postData.postGroupId
});
const fileBuffer = fs.readFileSync(image.path);
await axios.put(uploadData.uploadUrl, fileBuffer, {
headers: { 'Content-Type': image.type }
});
console.log(`Uploaded ${image.name}`);
}
// Step 3: Schedule the post
await api.put(`/update-post/${postData.postGroupId}`, {
status: 'scheduled',
scheduledTime: '2026-03-15T12:00:00.000Z'
});
console.log('Carousel post scheduled!');
```
## Best Practices
1. **Validate against the destination platform before uploading.** Presigned API uploads have no shared Publora cap; platform-specific limits are enforced when scheduling/publishing.
2. **Use the correct `contentType`.** The `contentType` you pass to `get-upload-url` must match the `Content-Type` header you send when uploading to S3. A mismatch will cause the upload to fail.
3. **Prefer JPEG over WebP.** While WebP is supported and will be auto-converted, starting with JPEG avoids the conversion step and ensures consistent quality across all platforms.
4. **Upload images in parallel when possible.** For carousel posts, you can request all 4 upload URLs at once and upload concurrently to speed things up.
5. **For large video files, stream the upload** instead of reading the entire file into memory.
## Common Issues
| Problem | Cause | Solution |
|---|---|---|
| S3 upload returns `403 Forbidden` | Pre-signed URL expired or `Content-Type` mismatch | Request a fresh upload URL and ensure the `Content-Type` header matches exactly |
| `400` when uploading media | Missing `fileName`, `contentType`, or `postGroupId`, or an unsupported upload family | Supply the three required fields. `type` is optional: when omitted, the API infers `image`, `video`, or `document` from `contentType`. |
| WebP image looks different after posting | Auto-conversion to JPEG for incompatible platforms | Upload as JPEG directly if quality consistency is critical |
| Video post fails on TikTok | Video does not meet TikTok requirements (FPS, format, duration) | Check video metadata -- ensure proper FPS, supported codec, and acceptable duration |
| Upload is slow for large files | File being read entirely into memory | Use streaming upload for large video files |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/analytics
# LinkedIn Analytics Guide
Track the performance of your LinkedIn posts with Publora's analytics endpoints.
## Overview
Publora provides analytics for LinkedIn posts, including:
- **Post-level metrics:** impressions, reach, reactions, comments, reshares
- **Account-level metrics:** aggregated impressions, reactions, comments, reshares, and reach
> **Note:** This guide covers the LinkedIn analytics endpoints. Mastodon and Bluesky have their own, simpler pair of endpoints — see [Mastodon and Bluesky Statistics](https://docs.publora.com/endpoints/platform-statistics). No other platform exposes analytics through Publora yet.
## Available Metrics
| Metric | Description |
|--------|-------------|
| `IMPRESSION` | Total number of times the post was displayed |
| `MEMBERS_REACHED` | Unique LinkedIn members who saw the post |
| `RESHARE` | Number of times the post was reposted |
| `REACTION` | Total reactions (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT) |
| `COMMENT` | Total number of comments |
## Get Post Statistics
### Endpoint
```
POST /api/v1/linkedin-post-statistics
```
### Request
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN (e.g., `urn:li:share:7123456789012345678`) |
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123`) |
| `queryType` | string | No | Single metric: `IMPRESSION`, `MEMBERS_REACHED`, `RESHARE`, `REACTION`, `COMMENT` |
| `queryTypes` | string[] or `"ALL"` | No | Multiple metrics at once. Use `"ALL"` for all 5 metrics. |
Use either `queryType` (single) or `queryTypes` (multiple), not both.
### Get All Metrics
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
platformId: 'linkedin-ABC123DEF',
queryTypes: 'ALL'
})
});
const data = await response.json();
console.log('Impressions:', data.metrics.IMPRESSION);
console.log('Reach:', data.metrics.MEMBERS_REACHED);
console.log('Engagement:', data.metrics.REACTION + data.metrics.COMMENT + data.metrics.RESHARE);
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-post-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:share:7123456789012345678',
'platformId': 'linkedin-ABC123DEF',
'queryTypes': 'ALL'
}
)
data = response.json()
metrics = data['metrics']
print(f"Impressions: {metrics['IMPRESSION']}")
print(f"Reach: {metrics['MEMBERS_REACHED']}")
print(f"Engagement: {metrics['REACTION'] + metrics['COMMENT'] + metrics['RESHARE']}")
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-post-statistics \
-H "x-publora-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postedId": "urn:li:share:7123456789012345678",
"platformId": "linkedin-ABC123DEF",
"queryTypes": "ALL"
}'
```
### Response (All Metrics)
```json
{
"success": true,
"metrics": {
"IMPRESSION": 15420,
"MEMBERS_REACHED": 8234,
"RESHARE": 23,
"REACTION": 456,
"COMMENT": 89
},
"cached": false
}
```
Post statistics are cached for 2 hours. `cached: true` means the data was served from cache.
### Get a Single Metric
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:share:7123456789012345678',
platformId: 'linkedin-ABC123DEF',
queryType: 'IMPRESSION'
})
});
const data = await response.json();
console.log(`Impressions: ${data.count}`); // Single metric returns { success, count, cached }
```
### Response (Single Metric)
```json
{
"success": true,
"count": 15420,
"cached": false
}
```
## Get Account Statistics
### Endpoint
```
POST /api/v1/linkedin-account-statistics
```
### Request
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platformId` | string | Yes | LinkedIn connection ID (format: `linkedin-ABC123`) |
| `queryType` | string | No | Single metric (same options as post statistics) |
| `queryTypes` | string[] or `"ALL"` | No | Multiple metrics at once |
| `aggregation` | string | No | `"TOTAL"` (default) or `"DAILY"` |
| `dateRange` | object | No | `{ start: { year, month, day }, end: { year, month, day } }` |
> **Note:** `MEMBERS_REACHED` with `DAILY` aggregation is not supported by the LinkedIn API.
**JavaScript (fetch)**
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-account-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-ABC123DEF',
queryTypes: 'ALL',
aggregation: 'TOTAL'
})
});
const data = await response.json();
console.log('Total impressions:', data.metrics.IMPRESSION);
console.log('Total engagement:', data.metrics.REACTION + data.metrics.COMMENT);
```
**Python (requests)**
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-account-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'platformId': 'linkedin-ABC123DEF',
'queryTypes': 'ALL',
'aggregation': 'TOTAL'
}
)
data = response.json()
print(f"Total impressions: {data['metrics']['IMPRESSION']}")
```
**cURL**
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-account-statistics \
-H "x-publora-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platformId": "linkedin-ABC123DEF",
"queryTypes": "ALL",
"aggregation": "TOTAL"
}'
```
### Response (Total Aggregation, Multiple Metrics)
```json
{
"success": true,
"metrics": {
"IMPRESSION": 45230,
"MEMBERS_REACHED": 22150,
"RESHARE": 89,
"REACTION": 1234,
"COMMENT": 256
},
"aggregation": "TOTAL",
"cached": false
}
```
### Daily Aggregation with Date Range
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-account-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
platformId: 'linkedin-ABC123DEF',
queryType: 'IMPRESSION',
aggregation: 'DAILY',
dateRange: {
start: { year: 2026, month: 1, day: 1 },
end: { year: 2026, month: 1, day: 31 }
}
})
});
const data = await response.json();
// Returns array of daily values
for (const entry of data.data) {
console.log(`${JSON.stringify(entry.dateRange)}: ${entry.count} impressions`);
}
```
### Response (Daily Aggregation, Single Metric)
```json
{
"success": true,
"data": [
{
"count": 150,
"dateRange": { "start": { "year": 2026, "month": 1, "day": 1 }, "end": { "year": 2026, "month": 1, "day": 1 } }
},
{
"count": 220,
"dateRange": { "start": { "year": 2026, "month": 1, "day": 2 }, "end": { "year": 2026, "month": 1, "day": 2 } }
}
],
"aggregation": "DAILY",
"cached": false
}
```
## Finding the Post URN
When you create a post via Publora, the response includes the platform-specific post ID. For LinkedIn, this is the URN.
### From Post Creation Response
```javascript
const createResponse = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'My LinkedIn post',
platforms: ['linkedin-ABC123DEF']
})
});
const result = await createResponse.json();
const postGroupId = result.postGroupId;
// Wait for post to be published, then get details
const postDetails = await fetch(`https://api.publora.com/api/v1/get-post/${postGroupId}`, {
headers: { 'x-publora-key': 'YOUR_API_KEY' }
}).then(r => r.json());
// Find the LinkedIn postedId
const linkedinPost = postDetails.posts.find(p => p.platform === 'linkedin');
const postedId = linkedinPost.postedId; // e.g., "urn:li:share:7123456789012345678"
```
## Analytics Dashboard Example
Build a simple analytics tracker for your LinkedIn posts.
### JavaScript Implementation
```javascript
const PUBLORA_API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
async function getPostAnalytics(platformId, postedIds) {
const results = [];
for (const postedId of postedIds) {
const response = await fetch(`${BASE_URL}/linkedin-post-statistics`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': PUBLORA_API_KEY
},
body: JSON.stringify({ platformId, postedId, queryTypes: 'ALL' })
});
const data = await response.json();
const metrics = data.metrics;
results.push({
postedId,
...metrics,
totalEngagement: metrics.REACTION + metrics.COMMENT + metrics.RESHARE
});
}
return results;
}
async function generateReport(platformId, postedIds) {
console.log('=== LinkedIn Analytics Report ===\n');
const postStats = await getPostAnalytics(platformId, postedIds);
const totals = postStats.reduce((acc, post) => ({
IMPRESSION: acc.IMPRESSION + post.IMPRESSION,
MEMBERS_REACHED: acc.MEMBERS_REACHED + post.MEMBERS_REACHED,
REACTION: acc.REACTION + post.REACTION,
COMMENT: acc.COMMENT + post.COMMENT,
RESHARE: acc.RESHARE + post.RESHARE
}), { IMPRESSION: 0, MEMBERS_REACHED: 0, REACTION: 0, COMMENT: 0, RESHARE: 0 });
console.log('Post Performance:');
console.log('-'.repeat(60));
postStats.forEach((post, i) => {
console.log(`\nPost ${i + 1}: ${post.postedId}`);
console.log(` Impressions: ${post.IMPRESSION.toLocaleString()}`);
console.log(` Reach: ${post.MEMBERS_REACHED.toLocaleString()}`);
console.log(` Engagement: ${post.totalEngagement} (${post.REACTION} reactions, ${post.COMMENT} comments, ${post.RESHARE} reshares)`);
console.log(` Engagement Rate: ${((post.totalEngagement / post.IMPRESSION) * 100).toFixed(2)}%`);
});
const totalEngagement = totals.REACTION + totals.COMMENT + totals.RESHARE;
console.log('\n' + '='.repeat(60));
console.log('TOTALS:');
console.log(` Total Impressions: ${totals.IMPRESSION.toLocaleString()}`);
console.log(` Total Reach: ${totals.MEMBERS_REACHED.toLocaleString()}`);
console.log(` Total Engagement: ${totalEngagement}`);
console.log(` Avg Engagement Rate: ${((totalEngagement / totals.IMPRESSION) * 100).toFixed(2)}%`);
return { postStats, totals };
}
// Usage
const postedIds = [
'urn:li:share:7123456789012345678',
'urn:li:share:7234567890123456789',
'urn:li:share:7345678901234567890'
];
generateReport('linkedin-ABC123DEF', postedIds);
```
### Python Implementation
```python
import requests
from datetime import datetime
PUBLORA_API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.publora.com/api/v1'
def get_post_analytics(platform_id, post_urns):
results = []
for posted_id in post_urns:
response = requests.post(
f'{BASE_URL}/linkedin-post-statistics',
headers={
'Content-Type': 'application/json',
'x-publora-key': PUBLORA_API_KEY
},
json={
'platformId': platform_id,
'postedId': posted_id,
'queryTypes': 'ALL'
}
)
data = response.json()
metrics = data['metrics']
metrics['postedId'] = posted_id
metrics['totalEngagement'] = metrics['REACTION'] + metrics['COMMENT'] + metrics['RESHARE']
results.append(metrics)
return results
def generate_report(platform_id, post_urns):
print('=== LinkedIn Analytics Report ===')
print(f'Generated: {datetime.now().strftime("%Y-%m-%d %H:%M")}\n')
post_stats = get_post_analytics(platform_id, post_urns)
totals = {
'IMPRESSION': sum(p['IMPRESSION'] for p in post_stats),
'MEMBERS_REACHED': sum(p['MEMBERS_REACHED'] for p in post_stats),
'REACTION': sum(p['REACTION'] for p in post_stats),
'COMMENT': sum(p['COMMENT'] for p in post_stats),
'RESHARE': sum(p['RESHARE'] for p in post_stats)
}
print('Post Performance:')
print('-' * 60)
for i, post in enumerate(post_stats, 1):
engagement_rate = (post['totalEngagement'] / post['IMPRESSION'] * 100) if post['IMPRESSION'] > 0 else 0
print(f"\nPost {i}: {post['postedId']}")
print(f" Impressions: {post['IMPRESSION']:,}")
print(f" Reach: {post['MEMBERS_REACHED']:,}")
print(f" Engagement: {post['totalEngagement']} ({post['REACTION']} reactions, {post['COMMENT']} comments, {post['RESHARE']} reshares)")
print(f" Engagement Rate: {engagement_rate:.2f}%")
total_engagement = totals['REACTION'] + totals['COMMENT'] + totals['RESHARE']
avg_engagement_rate = (total_engagement / totals['IMPRESSION'] * 100) if totals['IMPRESSION'] > 0 else 0
print('\n' + '=' * 60)
print('TOTALS:')
print(f" Total Impressions: {totals['IMPRESSION']:,}")
print(f" Total Reach: {totals['MEMBERS_REACHED']:,}")
print(f" Total Engagement: {total_engagement}")
print(f" Avg Engagement Rate: {avg_engagement_rate:.2f}%")
return {'post_stats': post_stats, 'totals': totals}
# Usage
post_urns = [
'urn:li:share:7123456789012345678',
'urn:li:share:7234567890123456789',
'urn:li:share:7345678901234567890'
]
report = generate_report('linkedin-ABC123DEF', post_urns)
```
## Best Practices
### 1. Wait Before Fetching Analytics
LinkedIn analytics take time to populate. Wait at least 24 hours after publishing for meaningful data.
### 2. Use Caching Wisely
Account statistics are cached for 2 hours (`TOTAL`) or 1 hour (`DAILY`). The `cached` field tells you if data was served from cache.
### 3. Calculate Engagement Rate
```javascript
function calculateEngagementRate(metrics) {
const engagement = metrics.REACTION + metrics.COMMENT + metrics.RESHARE;
return metrics.IMPRESSION > 0
? (engagement / metrics.IMPRESSION) * 100
: 0;
}
// Good engagement rate for LinkedIn: 2-5%
// Great engagement rate: 5%+
```
## Other Platforms
Mastodon and Bluesky engagement is served by two separate endpoints with a different, much smaller contract:
```
POST /api/v1/post-statistics # up to 50 posts at once, mixed platforms
POST /api/v1/profile-statistics # followers / following / post count
```
They return a fixed, always-present metric shape (`reactions`, `comments`, `reposts`, `quotes`, `saves`, `impressions`, `reach`, `clicks`) where anything the platform does not expose is `null` rather than `0`, and they are gated by the same analytics plan feature as the LinkedIn endpoints. Full reference: [Mastodon and Bluesky Statistics](https://docs.publora.com/endpoints/platform-statistics).
## Error Handling
```javascript
async function getStatisticsSafe(platformId, postedId) {
try {
const response = await fetch('https://api.publora.com/api/v1/linkedin-post-statistics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({ platformId, postedId, queryTypes: 'ALL' })
});
if (!response.ok) {
const error = await response.json();
if (response.status === 404) {
console.log('LinkedIn connection not found');
return null;
}
throw new Error(error.error || 'Failed to fetch statistics');
}
return response.json();
} catch (error) {
console.error('Analytics error:', error.message);
return null;
}
}
```
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/error-handling
# Error Handling
This guide covers how to handle errors from the Publora API, including HTTP status codes, error response formats, retry strategies, and dealing with partial failures.
For a code-by-code lookup covering top-level, validation, media-ingestion, and plan-limit errors, see the [API Error Code Catalog](./error-codes.md).
## How It Works
The Publora API uses standard HTTP status codes to indicate success or failure. When an error occurs, the response body contains a JSON object with details about what went wrong.
### HTTP Status Codes
| Code | Meaning | Description |
|---|---|---|
| `200` | OK | Request succeeded (GET, PUT, DELETE, and most POST endpoints including `create-post`) |
| `201` | Created | Resource created successfully (used by specific POST endpoints such as `POST /webhooks` and LinkedIn reaction and comment creation) |
| `400` | Bad Request | Invalid input, missing required fields, or malformed data |
| `401` | Unauthorized | Missing or invalid API key |
| `403` | Forbidden | Valid API key but insufficient permissions or plan limits reached |
| `404` | Not Found | Resource does not exist or does not belong to your account |
| `409` | Conflict | Duplicate or conflicting operation, or an `Idempotency-Key` request that is still in flight |
| `422` | Unprocessable Entity | An `Idempotency-Key` was reused with a different request body |
| `500` | Internal Server Error | Something went wrong on Publora's side |
> **Note:** Most POST endpoints (including `create-post`) return `200` on success, but some creation endpoints (`POST /webhooks`, `POST /linkedin-reactions`, `POST /linkedin-comments`) return `201`. Check for both `200` and `201` as success codes in your error handling logic.
### Error Response Format
Errors are returned as JSON in one of two formats:
```json
{
"error": "Human-readable error message"
}
```
or
```json
{
"message": "Detailed description of what went wrong"
}
```
Both formats may also carry a machine-readable `code` field. Prefer branching on `code` over matching `error` text — messages may be reworded, codes are stable.
### The API tells you, or refuses — it never silently rewrites your request
Publora no longer quietly changes a request it cannot take literally. It either **warns** (2xx + `warnings[]`) or **refuses** (4xx + `code`).
#### `warnings[]` on successful responses
A `200` from `create-post` or `update-post` may include a `warnings` array. It is **omitted entirely when empty** — never assume the key exists. Each entry has at least `code` and `message`. Surface warnings to your users; do not treat them as failures.
```json
{
"success": true,
"postGroupId": "664f1a2b3c4d5e6f7a8b9c0d",
"scheduledTime": "2026-03-15T14:00:00.000Z",
"warnings": [
{
"code": "SCHEDULED_TIME_COERCED",
"message": "Requested scheduled time 2026-03-15T13:59:00.000Z was in the past and was changed to server time 2026-03-15T14:00:00.000Z.",
"requested": "2026-03-15T13:59:00.000Z",
"effective": "2026-03-15T14:00:00.000Z"
}
]
}
```
#### `scheduledTime` in the past
| Situation | Behaviour |
|---|---|
| Less than 5 minutes in the past | **Always** clamped to server time + `SCHEDULED_TIME_COERCED` warning (tolerates clock skew). This tolerance is permanent — it does not change after the sunset. |
| 5 minutes or more in the past, **before** the strict sunset (`2026-08-25`) | Clamped to server time + `SCHEDULED_TIME_COERCED` warning |
| 5 minutes or more in the past, **on or after** the configured sunset (default `2026-08-25`) | Rejected: `400` `SCHEDULED_TIME_IN_PAST` |
Production configuration can force strict mode on or off, or move the sunset, so the calendar date is not unconditional.
**Migrate now:** `SCHEDULED_TIME_COERCED` means the request will fail whenever strict mode becomes active. Compare `requested` against `serverTime`/`effective` to detect clock skew.
### Common Errors
| Status | Error Message | Cause | Resolution |
|---|---|---|---|
| `401` | `"API key is required"` | The `x-publora-key` header is missing | Include a valid API key in the `x-publora-key` header |
| `401` | `"Invalid API key"` | The `x-publora-key` header contains an invalid or revoked key | Verify your API key is correct |
| `401` | `"Invalid API key owner"` | The key exists but its owner account could not be resolved | Verify the API key is associated with a valid account, or regenerate the key |
| `403` | `"API access is not enabled for this account"` | API access is disabled for this account (a custom plan with `apiAccess` turned off — standard plans, including the free Starter plan, include API access) | Contact support if you expect API access |
| `403` | `"Subscription required"` | Your account does not have an active subscription. Response includes `message: "No active plan entitlements found for this account."` **Note:** This error is currently unreachable in practice because `resolveEntitlementsForOwner()` always falls back to the Starter plan when no paid subscription exists. The middleware code exists and is documented here for completeness, but with the current entitlement resolution logic this error cannot occur. | Subscribe to a paid plan |
| `403` | `"Account on hold"` | Your account has been placed on hold. Response includes `message: "Your account is temporarily on hold. Please contact support."`, `holdExpiresAt` (ISO 8601 timestamp), and `holdReason` fields. **Note:** This error only applies to dashboard routes, not the external REST API. The `checkHold` middleware is not applied to external API endpoints. | Wait until the hold expires or contact support to resolve the issue |
| `403` | `"Account inactive"` | Your account has been deactivated. Response includes `message: "Your account is inactive."` **Note:** This error is currently unreachable. The `checkSubscription` middleware is imported but never mounted on any route (dead code), so this error cannot occur on either dashboard or external API endpoints. It is documented here for completeness. | Contact support@publora.com to reactivate your account |
| `403` | Limit exceeded (structured) | You have exceeded a usage limit for your plan. Response uses `LimitExceededError` format with fields: `code`, `error` (short label), `message` (long text), `metric`, `limit`, `used`, `requested`, `remaining`, `periodStart`, `periodEnd`, `planName`, plus context-specific fields (see below) | Wait for the current period to reset, reduce usage, or upgrade your plan |
| `403` | `"MCP access is not enabled for this account"` | Your account does not have MCP access enabled | Contact support or upgrade your plan to enable MCP access |
| `400` | `"Invalid scheduled time format"` | The `scheduledTime` is not a valid ISO 8601 string | Use a valid time in the format `YYYY-MM-DDTHH:mm:ss.sssZ` |
| `404` | `"Post group not found"` | The post group ID does not exist or does not belong to your account | Verify the ID and ensure you are using the correct API key |
| `400` | `"Cannot update post: post is currently in {status} status"` | Attempting to modify a post that is in a non-editable status (e.g., `published`, `failed`) | Only `draft` and `scheduled` posts can be updated. The external API and dashboard have **different** update rules. The external API rejects any post not in `draft` or `scheduled` status. The dashboard controller rejects posts in `published` or `failed` status — meaning `partially_published` posts **can** be updated via the dashboard but **not** via the API. Neither checks `processingStatus`. Note: `processing` is not a value of the `status` field — it is tracked separately via the `processingStatus` field (values: `pending`, `processing`, `finished`). The `status` field values are: `draft`, `scheduled`, `published`, `failed`, `partially_published`. |
### Scheduled-Time Errors
| Status | Code | Error Message | Cause | Resolution |
|---|---|---|---|---|
| `400` | `SCHEDULED_TIME_IN_PAST` | `"Scheduled time is in the past. Server time is {ISO} UTC."` | `scheduledTime` was 5+ minutes in the past and strict mode is active (see the sunset table above). Response also includes `serverTime` (ISO 8601, the server's clock at the moment of the request). | Send a future time. If your time looked correct, compare it to `serverTime` — you likely have clock skew or a timezone/UTC bug. |
| `200` | `SCHEDULED_TIME_COERCED` | *(not an error — a `warnings[]` entry)* | A past `scheduledTime` was clamped to server time. Entry fields: `code`, `message`, `requested`, `effective`. | None required, but fix the sending clock: after the strict sunset this same request returns `400`. |
### platformSettings Errors
| Status | Code | Error Message | Cause | Resolution |
|---|---|---|---|---|
| `400` | `PLATFORM_SETTING_UNKNOWN` | `"Unknown platformSettings path: {path}"` | An unknown platform key or an unknown nested field inside `platformSettings`. Previously such paths were silently dropped and the post published without the setting. The response includes `field` with the **exact** offending dotted path (e.g. `instagram.coverurl`). | Read `field`, fix the typo or remove the key. See the platformSettings schema for the supported paths per platform. |
### Idempotency Errors
Applies to `POST /create-post`, `PUT /update-post` and `POST /attach-media` when you send an `Idempotency-Key` header. On `attach-media`, only the post, `file_id` and final file name are compared, so a changed `download_url` or `mime_type` replays the original response instead of conflicting.
The `code` field is the contract — branch on it, not on the message text.
| Status | Code | Cause | Resolution |
|---|---|---|---|
| `422` | `IDEMPOTENCY_KEY_CONFLICT` | The same `Idempotency-Key` was reused with a **different** request body. Bodies are compared by a canonical hash, so key order and formatting do not matter — only actual values do. | Use a new key for a new request, or resend the equivalent original body to replay the stored response. |
| `409` | `IDEMPOTENCY_IN_FLIGHT` | A request with this key is still being processed, or your claim on it was superseded by a concurrent request. Several distinct messages map to this one code — match on `code`. | Wait briefly and retry the identical request; once the original completes you receive its stored response. Do **not** switch to a new key — that risks a duplicate post. |
| `400` | `IDEMPOTENCY_BODY_TOO_COMPLEX` | The request body nests deeper than 200 levels and cannot be hashed. | Flatten the payload. No real `platformSettings` / `mediaUrls` body reaches this depth — it usually signals a serialization bug. |
> **Replays are not errors.** Resending an identical request with the same `Idempotency-Key` returns the **original** response — same status code, same body (including any `warnings[]`) — without performing the mutation again.
### Post Creation Errors
| Status | Error Message | Cause | Resolution |
|---|---|---|---|
| `400` | `"Content is required"` | The `content` field is empty or missing in a create-post request | Provide a non-empty `content` string |
| `400` | `"Platforms are required"` | The `platforms` field is missing from the request body | Include a `platforms` field in the request |
| `400` | `"At least one platform is required"` | The `platforms` array is present but empty | Add at least one platform ID to the `platforms` array |
| `400` | `"Invalid platform ID format: {platformId}"` | A platform ID in the `platforms` array does not match the expected `{platform}-{id}` format | Use the correct format, e.g., `"twitter-123456"` |
| `400` | `"Invalid platforms JSON format"` | The `platforms` field could not be parsed as valid JSON | Ensure `platforms` is a valid JSON array |
| `400` | `"Platforms must be an array"` | The `platforms` field is not an array (e.g., a string or object) | Pass `platforms` as a JSON array of platform ID strings |
| `400` | `"Invalid platformSettings JSON"` | The `platformSettings` field could not be parsed as valid JSON | Ensure `platformSettings` is a valid JSON object |
| `400` | `"platformSettings must be an object"` | The `platformSettings` field is not a JSON object | Pass `platformSettings` as a JSON object, not an array or primitive |
| `400` | `"Unknown platformSettings path: {path}"` | An unknown platform or nested key in `platformSettings` (code `PLATFORM_SETTING_UNKNOWN`, with the exact `field`) | See [platformSettings Errors](#platformsettings-errors) |
### Post Update Errors
| Status | Error Message | Cause | Resolution |
|---|---|---|---|
| `400` | `"At least one of status, scheduledTime, content, platforms, platformSettings, or mediaUrls must be provided"` | An update-post request omitted all six accepted fields | Include at least one of `status`, `scheduledTime`, `content`, `platforms`, `platformSettings`, or `mediaUrls` in the request body |
| `400` | `"Status must be either 'draft' or 'scheduled'"` | The `status` field in an update-post request contains an invalid value | Set `status` to either `"draft"` or `"scheduled"` |
| `422` / `409` / `400` | Idempotency errors | An `Idempotency-Key` was reused with a different body, is still in flight, or the body is too deeply nested | See [Idempotency Errors](#idempotency-errors) |
### Media Upload Errors
| Status | Error Message | Cause | Resolution |
|---|---|---|---|
| `400` | `"fileName, contentType, and postGroupId are required"` | A get-upload-url request is missing one or more required fields | Include all three fields: `fileName`, `contentType`, and `postGroupId` |
### LimitExceededError Codes
The `code` field in a `LimitExceededError` response identifies the specific limit that was exceeded:
| Code | Description |
|---|---|
| `POST_LIMIT_REACHED` | Monthly post limit for the plan has been reached |
| `SCHEDULED_POST_LIMIT_REACHED` | Maximum number of pending scheduled posts reached |
| `SCHEDULE_HORIZON_REACHED` | Scheduled time exceeds the plan's maximum scheduling horizon |
| `PLATFORM_NOT_AVAILABLE` | The target platform is not available on the current plan |
| `CONNECTIONS_OVER_LIMIT` | Number of connected accounts exceeds the plan limit |
| `CHANNEL_LIMIT_REACHED` | Maximum number of channels for the plan has been reached |
> **Note on `CHANNEL_LIMIT_REACHED`:** The `checkConnectionLimit` middleware returns a **different response format** from the standard `LimitExceededError`. When `canExpand: true`, the response includes `planKey`, `planName`, `currentQuantity`, `targetQuantity`, `connectionCount`, and `pricing` (expansion pricing details). When `canExpand: false`, the same fields are present with `targetQuantity` and `pricing` set to `null`. Every variant also carries `error`, `message` and `upgradeUrl`. If you are handling connection limit errors specifically, parse these fields rather than the standard `LimitExceededError` shape.
### LimitExceededError Context Fields
In addition to the standard fields (`code`, `error`, `message`, `metric`, `limit`, `used`, `requested`, `remaining`, `periodStart`, `periodEnd`, `planName`), the response spreads `...this.context` into the top-level response object. This means context-specific fields appear conditionally depending on the error code -- they are not guaranteed to be present on every `LimitExceededError` response:
| Context Field | Appears With | Description |
|---|---|---|
| `overLimitBy` | `CONNECTIONS_OVER_LIMIT` | How many units over the limit the request would go |
| `disallowedPlatforms` | `PLATFORM_NOT_AVAILABLE` | Array of platforms in the request that are not available on the current plan |
| `allowedPlatforms` | `PLATFORM_NOT_AVAILABLE` | Array of platforms that are available on the current plan |
| `projectedUsed` | `CHANNEL_LIMIT_REACHED` | The projected usage count if the operation were to proceed |
| `blockedPlatforms` | `POST_LIMIT_REACHED` | Per-connection `{ platformSelection, used, remaining }` entries; present only for connection-scoped monthly-post limits |
| `limitScope` | `POST_LIMIT_REACHED` | Monthly-post scope: `"account"` or `"connection"` |
| `scheduledTime` | `SCHEDULE_HORIZON_REACHED` | The requested scheduled time that exceeded the horizon |
| `maxScheduledDate` | `SCHEDULE_HORIZON_REACHED` | The latest allowed scheduled date for the current plan |
### Threads-Specific Errors
Multi-part chains require the `threads_manage_replies` permission on the connection. Publora checks the grant when you schedule a chain — from a per-connection cache up to five minutes old — and re-checks it against Meta immediately before publishing, so a missing permission never leaves a half-published chain.
| Code | HTTP | Error Message | Cause | Resolution |
|---|---:|---|---|---|
| `THREADS_PERMISSION_REQUIRED` | 400 | `"Reconnect your Threads account and allow reply publishing to publish a thread with multiple posts."` — or `"Reconnect your Threads account before scheduling a thread."` when the connection no longer exists | The token does not grant `threads_manage_replies` | Reconnect that account in Publora **Channels** and approve all requested permissions |
| `TOKEN_EXPIRED` | 400 | `"Threads authorization has expired. Reconnect your Threads account."` | Meta reports the stored token invalid | Reconnect the account |
| `THREADS_PERMISSIONS_UNAVAILABLE` | 503 | `"Unable to check Threads permissions. Please try scheduling again shortly."` | Publora's own permission lookup failed — **not** an account problem | Retry in a few seconds. Never prompt the user to reconnect. If it keeps failing it is a Publora-side configuration issue, so stop retrying and contact support |
The first two arrive inside the standard `validation.errors[]` envelope. `THREADS_PERMISSIONS_UNAVAILABLE` does not: its body is `{ "code": "THREADS_PERMISSIONS_UNAVAILABLE", "error": "…" }` with no `validation` object. Treat the 503 as transient and the 400s as user action, and match on the code rather than the message — `THREADS_PERMISSION_REQUIRED` has two variants.
**Note:** Single Threads posts and drafts skip the permission check entirely — it runs only for a target that resolves to more than one part. See [Threads chain codes](./error-codes.md#threads-chain-codes) for the publish-time codes.
### Post-Level Errors (Partial Failures)
A post group can target multiple platforms. Even if some platforms succeed, others may fail. This results in a `partially_published` status on the post group.
When checking a post group's status, each individual platform post has its own `status` field:
```json
{
"success": true,
"postGroupId": "664f1a2b3c4d5e6f7a8b9c0d",
"status": "partially_published",
"scheduledTime": "2026-03-15T14:00:00.000Z",
"platformSettings": {},
"platforms": ["twitter-123456", "tiktok-789012", "linkedin-ABCDEF"],
"posts": [
{
"_id": "664f1a2b3c4d5e6f7a8b9c01",
"platform": "twitter",
"platformId": "123456",
"status": "published",
"content": "Check out our latest product launch!",
"postedId": "1234567890123456789",
"permalink": null
},
{
"_id": "664f1a2b3c4d5e6f7a8b9c02",
"platform": "tiktok",
"platformId": "789012",
"status": "failed",
"content": "Check out our latest product launch!",
"postedId": null,
"permalink": null,
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded",
"platformStatusCode": 429,
"platformError": null,
"failedAt": "2026-03-15T14:01:12.000Z",
"retryable": true
}
},
{
"_id": "664f1a2b3c4d5e6f7a8b9c03",
"platform": "linkedin",
"platformId": "ABCDEF",
"status": "published",
"content": "Check out our latest product launch!",
"postedId": "urn:li:share:7000000000000000000",
"permalink": null
}
],
"media": []
}
```
**Note:** Top-level `status` is the aggregate post-group status. Each `posts[].status` is the outcome for one platform target. The top-level response also includes `success`, `postGroupId`, `scheduledTime`, `platformSettings`, `platforms`, and `media`; `content` remains per-platform inside `posts[]`.
> **`error` field format:** The `error` field on individual platform posts is a structured object, not a plain string. The `get-post` endpoint returns the full error object with fields: `code`, `message`, `platformStatusCode`, `platformError`, `failedAt`, and `retryable`.
> **`platformId` vs platform ID string:** In the `get-post` response, `platform` and `platformId` are separate fields. The `platform` field contains the platform name (e.g., `"twitter"`), and `platformId` contains just the account identifier (e.g., `"123456"`). This is different from the `{platform}-{id}` combined format (e.g., `"twitter-123456"`) used in the `platforms` array when creating posts.
### Platform-Specific Validation Errors
Some platforms have strict media requirements that are checked before publishing:
- **TikTok:** Minimum FPS requirement, specific video format requirements, duration limits
- **Instagram:** Video aspect ratio and duration requirements for Reels
- **YouTube:** Video format and size requirements
These errors appear at the individual platform post level, not at the HTTP response level.
## Examples
### Error Handling Wrapper (JavaScript)
```javascript
class PubloraApiError extends Error {
constructor(status, message, body) {
super(message);
this.name = 'PubloraApiError';
this.status = status;
this.body = body;
}
}
async function publoraRequest(endpoint, options = {}) {
const url = `https://api.publora.com/api/v1${endpoint}`;
const response = await fetch(url, {
...options,
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY',
...options.headers
}
});
const body = await response.json();
if (!response.ok) {
const message = body.error || body.message || 'Unknown API error';
throw new PubloraApiError(response.status, message, body);
}
return body;
}
// Usage
try {
const post = await publoraRequest('/create-post', {
method: 'POST',
body: JSON.stringify({
content: 'Hello from Publora!',
platforms: ['twitter-123456'],
scheduledTime: '2026-03-15T14:00:00.000Z'
})
});
console.log('Post created:', post.postGroupId);
} catch (error) {
if (error instanceof PubloraApiError) {
switch (error.status) {
case 401:
console.error('Authentication failed. Check your API key.');
break;
case 403:
console.error('Access denied:', error.message);
// Could be "Subscription required", limit exceeded, or account hold
break;
case 400:
console.error('Bad request:', error.message);
// Could be "Invalid scheduled time" or validation errors
break;
case 404:
console.error('Resource not found:', error.message);
break;
case 409:
console.error('Conflict:', error.message);
break;
case 500:
console.error('Server error. Retry later.');
break;
default:
console.error(`API error (${error.status}):`, error.message);
}
} else {
console.error('Network or unexpected error:', error.message);
}
}
```
### Error Handling Wrapper (Python)
```python
import requests
class PubloraApiError(Exception):
def __init__(self, status_code, message, body):
super().__init__(message)
self.status_code = status_code
self.body = body
class PubloraClient:
BASE_URL = 'https://api.publora.com/api/v1'
def __init__(self, api_key):
self.session = requests.Session()
self.session.headers.update({
'Content-Type': 'application/json',
'x-publora-key': api_key
})
def _request(self, method, endpoint, **kwargs):
url = f'{self.BASE_URL}{endpoint}'
response = self.session.request(method, url, **kwargs)
try:
body = response.json()
except ValueError:
body = {}
if not response.ok:
message = body.get('error') or body.get('message') or 'Unknown API error'
raise PubloraApiError(response.status_code, message, body)
return body
def create_post(self, content, platform_ids, scheduled_time=None):
payload = {
'content': content,
'platforms': platform_ids
}
if scheduled_time:
payload['scheduledTime'] = scheduled_time
return self._request('POST', '/create-post', json=payload)
def get_post(self, post_group_id):
return self._request('GET', f'/get-post/{post_group_id}')
# Usage
client = PubloraClient('YOUR_API_KEY')
try:
post = client.create_post(
content='Hello from Publora!',
platforms=['twitter-123456'],
scheduled_time='2026-03-15T14:00:00.000Z'
)
print(f"Post created: {post['postGroupId']}")
except PubloraApiError as e:
if e.status_code == 401:
print('Authentication failed. Check your API key.')
elif e.status_code == 403:
print(f'Access denied: {e}')
elif e.status_code == 400:
print(f'Bad request: {e}')
elif e.status_code == 404:
print(f'Resource not found: {e}')
elif e.status_code == 500:
print('Server error. Retry later.')
else:
print(f'API error ({e.status_code}): {e}')
except requests.RequestException as e:
print(f'Network error: {e}')
```
### cURL with Error Checking
```bash
#!/bin/bash
API_KEY="YOUR_API_KEY"
BASE_URL="https://api.publora.com/api/v1"
# Make a request and capture both HTTP status and body
HTTP_RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$BASE_URL/create-post" \
-H "Content-Type: application/json" \
-H "x-publora-key: $API_KEY" \
-d '{
"content": "Hello from Publora!",
"platforms": ["twitter-123456"],
"scheduledTime": "2026-03-15T14:00:00.000Z"
}')
# Split response body and status code
HTTP_BODY=$(echo "$HTTP_RESPONSE" | sed '$d')
HTTP_STATUS=$(echo "$HTTP_RESPONSE" | tail -1)
case $HTTP_STATUS in
200|201)
echo "Success:"
echo "$HTTP_BODY" | jq .
;;
400)
echo "Bad request:"
echo "$HTTP_BODY" | jq '.error // .message'
;;
401)
echo "Authentication failed. Check your x-publora-key header."
;;
403)
echo "Access denied:"
echo "$HTTP_BODY" | jq '.error // .message'
;;
404)
echo "Not found:"
echo "$HTTP_BODY" | jq '.error // .message'
;;
500)
echo "Server error. Retry later."
;;
*)
echo "Unexpected status: $HTTP_STATUS"
echo "$HTTP_BODY"
;;
esac
```
### Node.js (axios) with Error Handling
```javascript
const axios = require('axios');
const api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
});
// Add a response interceptor for centralized error handling
api.interceptors.response.use(
(response) => response,
(error) => {
if (error.response) {
const { status, data } = error.response;
const message = data.error || data.message || 'Unknown error';
switch (status) {
case 401:
console.error('Authentication failed. Check your API key.');
break;
case 403:
console.error('Access denied:', message);
break;
case 400:
console.error('Bad request:', message);
break;
case 404:
console.error('Not found:', message);
break;
case 500:
console.error('Server error. Retry later.');
break;
default:
console.error(`API error (${status}):`, message);
}
} else if (error.request) {
console.error('No response received. Check your network connection.');
} else {
console.error('Request setup error:', error.message);
}
return Promise.reject(error);
}
);
// Usage
try {
const { data: post } = await api.post('/create-post', {
content: 'Hello from Publora!',
platforms: ['twitter-123456'],
scheduledTime: '2026-03-15T14:00:00.000Z'
});
console.log('Post created:', post.postGroupId);
} catch (error) {
// Error already logged by the interceptor
// Add any additional handling here
}
```
---
### Retry Logic with Exponential Backoff
Server errors (`500`) and network failures are usually transient. Implement retry logic for these cases.
**JavaScript (fetch)**
```javascript
async function publoraRequestWithRetry(endpoint, options = {}, maxRetries = 3) {
const url = `https://api.publora.com/api/v1${endpoint}`;
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
const response = await fetch(url, {
...options,
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY',
...options.headers
}
});
const body = await response.json();
if (response.ok) {
return body;
}
// Do not retry client errors (4xx) -- they will not succeed on retry
if (response.status >= 400 && response.status < 500) {
throw new Error(`Client error ${response.status}: ${body.error || body.message}`);
}
// Retry on server errors (5xx)
if (attempt < maxRetries) {
const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
console.log(`Server error (${response.status}). Retrying in ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
throw new Error(`Server error ${response.status} after ${maxRetries} retries`);
} catch (error) {
// Retry on network errors
if (error.name === 'TypeError' && attempt < maxRetries) {
const delay = Math.pow(2, attempt) * 1000;
console.log(`Network error. Retrying in ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
}
// Usage
try {
const post = await publoraRequestWithRetry('/create-post', {
method: 'POST',
body: JSON.stringify({
content: 'Retryable post!',
platforms: ['twitter-123456'],
scheduledTime: '2026-03-15T14:00:00.000Z'
})
});
console.log('Post created:', post.postGroupId);
} catch (error) {
console.error('Failed after retries:', error.message);
}
```
**Python (requests)**
```python
import time
import requests
def publora_request_with_retry(method, endpoint, max_retries=3, **kwargs):
url = f'https://api.publora.com/api/v1{endpoint}'
headers = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
for attempt in range(max_retries + 1):
try:
response = requests.request(method, url, headers=headers, **kwargs)
body = response.json()
if response.ok:
return body
# Do not retry client errors (4xx)
if 400 <= response.status_code < 500:
message = body.get('error') or body.get('message') or 'Unknown error'
raise Exception(f'Client error {response.status_code}: {message}')
# Retry on server errors (5xx)
if attempt < max_retries:
delay = (2 ** attempt) # 1s, 2s, 4s
print(f'Server error ({response.status_code}). Retrying in {delay}s...')
time.sleep(delay)
continue
raise Exception(f'Server error {response.status_code} after {max_retries} retries')
except requests.ConnectionError:
if attempt < max_retries:
delay = (2 ** attempt)
print(f'Network error. Retrying in {delay}s...')
time.sleep(delay)
continue
raise
# Usage
try:
post = publora_request_with_retry(
'POST', '/create-post',
json={
'content': 'Retryable post!',
'platforms': ['twitter-123456'],
'scheduledTime': '2026-03-15T14:00:00.000Z'
}
)
print(f"Post created: {post['postGroupId']}")
except Exception as e:
print(f'Failed after retries: {e}')
```
**Node.js (axios)**
```javascript
const axios = require('axios');
async function publoraRequestWithRetry(method, endpoint, data = null, maxRetries = 3) {
const config = {
method,
url: `https://api.publora.com/api/v1${endpoint}`,
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
data
};
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
const response = await axios(config);
return response.data;
} catch (error) {
const status = error.response?.status;
// Do not retry client errors
if (status && status >= 400 && status < 500) {
const message = error.response.data?.error || error.response.data?.message;
throw new Error(`Client error ${status}: ${message}`);
}
// Retry on server errors or network errors
if (attempt < maxRetries) {
const delay = Math.pow(2, attempt) * 1000;
const reason = status ? `Server error (${status})` : 'Network error';
console.log(`${reason}. Retrying in ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
}
// Usage
try {
const post = await publoraRequestWithRetry('POST', '/create-post', {
content: 'Retryable post!',
platforms: ['twitter-123456'],
scheduledTime: '2026-03-15T14:00:00.000Z'
});
console.log('Post created:', post.postGroupId);
} catch (error) {
console.error('Failed after retries:', error.message);
}
```
---
### Checking for Partial Failures
After a post group has been processed, check whether all platforms succeeded or if some failed.
**JavaScript (fetch)**
```javascript
async function checkPostGroupStatus(postGroupId) {
const response = await fetch(
`https://api.publora.com/api/v1/get-post/${postGroupId}`,
{
headers: { 'x-publora-key': 'YOUR_API_KEY' }
}
);
const postGroup = await response.json();
// Determine overall status from individual posts
const posts = postGroup.posts || [];
const statuses = posts.map(p => p.status);
const allPublished = statuses.every(s => s === 'published');
const allFailed = statuses.every(s => s === 'failed');
const overallStatus = allPublished ? 'published' : allFailed ? 'failed' : 'partially_published';
console.log(`Post group ${postGroup.postGroupId}: ${overallStatus}`);
if (overallStatus === 'partially_published') {
console.log('Some platforms failed:');
const failed = postGroup.posts.filter(p => p.status === 'failed');
const succeeded = postGroup.posts.filter(p => p.status === 'published');
console.log(` Succeeded: ${succeeded.length}`);
for (const p of succeeded) {
console.log(` - ${p.platform}: ${p.postedId}`);
}
console.log(` Failed: ${failed.length}`);
for (const p of failed) {
console.log(` - ${p.platform}: ${p.error}`);
}
return { status: 'partial', succeeded, failed };
}
if (overallStatus === 'failed') {
console.log('All platforms failed.');
for (const p of posts) {
console.log(` - ${p.platform}: ${p.error}`);
}
return { status: 'failed', succeeded: [], failed: posts };
}
if (overallStatus === 'published') {
console.log('All platforms succeeded.');
return { status: 'success', succeeded: posts, failed: [] };
}
// Still processing or scheduled (posts array may be empty or have pending statuses)
console.log('Post is still being processed');
return { status: 'pending', succeeded: [], failed: [] };
}
// Usage
const result = await checkPostGroupStatus('664f1a2b3c4d5e6f7a8b9c0d');
if (result.failed.length > 0) {
// Take action: notify team, retry failed platforms, etc.
}
```
**Python (requests)**
```python
import requests
API_URL = 'https://api.publora.com/api/v1'
HEADERS = {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
}
def check_post_group_status(post_group_id):
response = requests.get(
f'{API_URL}/get-post/{post_group_id}',
headers=HEADERS
)
post_group = response.json()
posts = post_group.get('posts', [])
# Determine overall status from individual posts
statuses = [p['status'] for p in posts]
all_published = all(s == 'published' for s in statuses)
all_failed = all(s == 'failed' for s in statuses)
if all_published:
overall_status = 'published'
elif all_failed:
overall_status = 'failed'
elif posts:
overall_status = 'partially_published'
else:
overall_status = 'pending'
print(f"Post group {post_group['postGroupId']}: {overall_status}")
if overall_status == 'partially_published':
print('Some platforms failed:')
failed = [p for p in posts if p['status'] == 'failed']
succeeded = [p for p in posts if p['status'] == 'published']
print(f" Succeeded: {len(succeeded)}")
for p in succeeded:
print(f" - {p['platform']}: {p.get('postedId', 'N/A')}")
print(f" Failed: {len(failed)}")
for p in failed:
print(f" - {p['platform']}: {p.get('error', 'Unknown error')}")
return {'status': 'partial', 'succeeded': succeeded, 'failed': failed}
if overall_status == 'failed':
print('All platforms failed.')
for p in posts:
print(f" - {p['platform']}: {p.get('error', 'Unknown error')}")
return {'status': 'failed', 'succeeded': [], 'failed': posts}
if overall_status == 'published':
print('All platforms succeeded.')
return {'status': 'success', 'succeeded': posts, 'failed': []}
print(f'Post is still being processed')
return {'status': 'pending', 'succeeded': [], 'failed': []}
# Usage
result = check_post_group_status('664f1a2b3c4d5e6f7a8b9c0d')
if result['failed']:
# Take action: notify team, retry failed platforms, etc.
pass
```
## Best Practices
1. **Always check the HTTP status code.** Do not assume every response is successful. Parse the error body for details.
2. **Do not retry most 4xx responses unchanged.** They usually indicate a problem with the request. The exception is `429 MEDIA_URL_RATE_LIMITED` from `mediaUrls` or `attach-media` ingestion: wait the number of seconds in `Retry-After` (also returned as `retryAfterSec`), then retry with the same `Idempotency-Key` described in item 4.
3. **Use exponential backoff for retries.** Start at 1 second and double with each attempt. Cap at 3-5 retries to avoid infinite loops.
4. **Send an `Idempotency-Key` on every `create-post` / `update-post` / `attach-media` call you might retry.** A timeout does not tell you whether the post was created. Without a key, the retry double-posts (and on `update-post` with `mediaUrls`, or on `attach-media`, double-appends the media). With one, the retry replays the original response.
5. **Read `warnings[]` on successful responses.** A `200` can still mean the API changed something about your request — most often `SCHEDULED_TIME_COERCED`. Log warnings; do not discard them.
6. **Monitor for partial failures.** A `200` response when creating a post does not guarantee all platforms will succeed. Poll the post group status after the scheduled time to detect partial failures.
7. **Log error responses in full.** When debugging, log the entire response body, not just the error message. Additional fields may provide context.
8. **Handle `403` errors gracefully in your UI.** If a user hits a plan limit (returned as a structured `LimitExceededError`), parse the `metric`, `limit`, `used`, and `remaining` fields to show actionable guidance rather than a raw error.
9. **Validate inputs before sending.** Check that `scheduledTime` is in the future and in ISO 8601 format, platform IDs follow the `{platform}-{id}` format, and media counts are within limits. This avoids unnecessary `400` errors.
## Common Issues
| Problem | Cause | Solution |
|---|---|---|
| `401` on every request | API key not set or incorrect | Ensure `x-publora-key` header is present with a valid key |
| `403` but key is valid | Account has no active subscription, hit a usage limit, or account is on hold/inactive | Check subscription status, review the structured error response for limit details, or contact support |
| `400` when scheduling | `scheduledTime` is malformed, or (code `SCHEDULED_TIME_IN_PAST`) 5+ minutes in the past with strict mode active | Always send a future UTC time as `YYYY-MM-DDTHH:mm:ss.sssZ`. Compare your clock against the `serverTime` in the error body. |
| Post scheduled "now" instead of my requested time | The time was in the past and was clamped — the response carried a `SCHEDULED_TIME_COERCED` warning | Send a future time; strict mode may turn this into a hard `400` (scheduled for 2026-08-25 unless configuration overrides it). |
| `422` on retry | Same `Idempotency-Key` reused with a different body | Generate a fresh key per distinct request; reuse a key only to retry the *identical* request |
| `409` on retry | The original request with that key is still processing | Wait and retry the identical request — do not issue a new key |
| `404` when fetching a post | Post group ID is wrong or belongs to another account | Verify the ID and that you are using the correct API key |
| Post group shows `partially_published` | Some platforms failed while others succeeded | Inspect individual platform post statuses for error details |
| TikTok post fails with FPS error | Video frame rate below TikTok's minimum requirement | Re-encode the video with at least 23 FPS before uploading |
| `500` intermittent errors | Temporary server issues | Implement retry logic with exponential backoff |
| Threads chain rejected with `THREADS_PERMISSION_REQUIRED` | The connection has not granted `threads_manage_replies` | Reconnect that Threads account in Channels and approve all permissions; nothing was published, so simply schedule again |
| Threads chain ends `failed` with `THREAD_PARTIALLY_PUBLISHED` | Some parts published, then one failed; Publora does not republish a chain | Read `threadParts` in `get-post`, then publish only the parts still missing — do not recreate the post |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) — the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/error-codes
# API Error Code Catalog
This catalog covers stable codes reachable through API-key-authenticated `/api/v1` routes. It excludes internal X Bookmarks codes and codes emitted only by dashboard sessions, OAuth, billing, or other non-API-key routes.
Codes can appear at the top level, inside `warnings[]`, inside `validation.errors[]`, per URL in `mediaResults[]`, or per connection in `issues` on the analytics routes. Match on the code, not the human-readable message.
For retry patterns and idempotency guidance, see [Error Handling](./error-handling.md).
## Request and scheduling codes
| Code | HTTP | Location | Meaning | Retryable? | Recovery |
|---|---:|---|---|---|---|
| `IDEMPOTENCY_IN_FLIGHT` | 409 | top-level `code` | Another request with this idempotency key is still running, or its claim was superseded | Yes, shortly | Retry the identical request with the same key |
| `IDEMPOTENCY_KEY_CONFLICT` | 422 | top-level `code` | The key was already used with a different body or resource | No, unchanged | Replay the original request or use a new key for the new operation |
| `IDEMPOTENCY_BODY_TOO_COMPLEX` | 400 | top-level `code` | The body is too deeply nested to hash safely for idempotency | No | Simplify the request body or omit `Idempotency-Key` if safe retries are not required |
| `PLATFORM_SETTING_UNKNOWN` | 400 | top-level `code` | A `platformSettings` path is outside the strict allowlist | No | Remove or correct the path named by `field` |
| `PLATFORMS_REQUIRED` | 400 | top-level `code` | Scheduling would leave the post with no target platforms | No | Add at least one platform, or keep the post as a draft |
| `INVALID_CONTENT` | 400 | top-level `code` | `update-post` received a `content` value that is not a string | No | Send `content` as a string; `field` names the offending key |
| `INVALID_PLATFORMS` | 400 | top-level `code` | `update-post` received a `platforms` value that is not a valid, duplicate-free array of connection IDs | No | Send a de-duplicated array of IDs from `GET /platform-connections`; `field` names the offending key |
| `INVALID_PLATFORM_CONNECTION` | 400 | top-level `code` | A platform ID added by an `update-post` edit is not a connection owned by the acting user | No | Use IDs from `GET /platform-connections`; the offending IDs are listed in `invalidPlatforms` |
| `INVALID_PLATFORM_ID` | 400 | top-level `code` | A stored or supplied platform key could not be parsed while reconciling platform posts | No | Send IDs in the `-` form returned by `GET /platform-connections` |
| `POST_NOT_EDITABLE` | 400 | top-level `code` | The post group, or one of its platform posts, is past the editable `draft`/`scheduled` window | No | Create a new post; published and failed posts cannot be edited |
| `POST_PUBLISH_IN_PROGRESS` | 409 | top-level `code` | Publishing has already started for the group or one of its platform posts | Only after re-checking | Re-read with `GET /get-post`; retry only while the post is still `draft` or `scheduled` |
| `POST_GROUP_VERSION_CONFLICT` | 409 | top-level `code` | Another write committed first; this request changed nothing | Yes, after re-reading | Re-read with `GET /get-post`, rebase the edit on the current state, and retry |
| `SCHEDULED_TIME_IN_PAST` | 400 | top-level `code` | Strict mode rejected a time at least five minutes in the past | No | Send a future ISO 8601 UTC time |
| `INVALID_PUBLISH_NOW` | 400 | top-level `code` | `publishNow` on `create-post` or `update-post` is not a boolean | No | Send `true` or `false`, or omit the field |
| `PUBLISH_NOW_CONFLICT` | 400 | top-level `code` | `publishNow: true` was combined with a future `scheduledTime` or with `status: "draft"` | No | Drop `scheduledTime` (server time is used) and send no status or `scheduled` |
| `INVALID_SCHEDULED_TIME` | 400 | top-level `code` | `GET /account-context` received a `scheduledTime` query without `Z`/offset or with an impossible date | No | Send an ISO 8601 date-time with `Z` or an offset, or omit it |
| `SCHEDULED_TIME_COERCED` | 200 | `warnings[].code` | A past time was clamped to server time during the warn-first ramp | Not an error | Read the returned `scheduledTime` and fix the caller to send a future time |
| `MEDIA_URL_RATE_LIMITED` | 429 | top-level `code` | The fixed-window allowance of 60 ingested URLs was exceeded | Yes | Wait the `Retry-After` seconds, then retry; preserve the idempotency key when applicable |
| `INVALID_MEDIA_FILE` | 400 | top-level `code` | `attach-media` received a field other than `file` or `fileName`, a malformed file reference, a `download_url` that fails the static URL checks, or an invalid file name. Nothing was downloaded. | No, unchanged | Send only `file` (with `download_url` and `file_id`) and an optional `fileName`, then schedule separately with `update-post` |
| `FIRST_COMMENT_INVALID` | 400 | top-level `code` | Invalid `firstComment` object or `firstComments[]` list (up to three), including invalid delay or both fields together | No | Fix the field named by `field`; use one input form |
| `FIRST_COMMENT_PLATFORM_UNKNOWN` | 400 | top-level `code` | `firstComment.platforms` names something other than a platform type (for example a connection ID) | No | Use types such as `linkedin` or `twitter`; `allowed` lists the valid types |
| `FIRST_COMMENT_TOO_LONG` | 400 | top-level `code` | The comment exceeds a targeted platform's limit, or the absolute 25,000-character cap | No | Shorten it; `platform`, `limit`, `count` and `unit` say which limit was hit |
| `FIRST_COMMENT_PLATFORM_NOT_TARGETED` | 200 | `warnings[].code` | `firstComment.platforms` lists a type the post is not published to; it is ignored | Not an error | Remove the type or add a target on that platform |
| `FIRST_COMMENT_UNSUPPORTED_PLATFORMS` | 200 | `warnings[].code` | Some targets are on platforms without first-comment support; they will be skipped | Not an error | Nothing required; restrict `firstComment.platforms` to silence it |
## Plan and workspace limit codes
These top-level codes are `LimitExceededError` responses with HTTP 403.
| Code | Meaning | Retryable? | Recovery |
|---|---|---|---|
| `CONNECTIONS_OVER_LIMIT` | The workspace already has more connected channels than its plan permits | After account changes | Disconnect channels or upgrade before scheduling |
| `CHANNEL_LIMIT_REACHED` | Adding or attaching would exceed the channel allowance | After account changes | Disconnect a channel or upgrade |
| `SCHEDULE_HORIZON_REACHED` | The requested time is farther ahead than the plan permits | No, unchanged | Choose an earlier time or upgrade |
| `SCHEDULED_POST_LIMIT_REACHED` | The active scheduled-post queue is full | After capacity frees | Wait for or delete an existing scheduled post, or upgrade |
| `POST_LIMIT_REACHED` | The monthly account/connection post allowance is exhausted | After reset or upgrade | Wait for `periodEnd` or upgrade |
| `PLATFORM_NOT_AVAILABLE` | The plan does not allow one or more selected platforms | No, unchanged | Remove the platforms listed in the top-level `disallowedPlatforms` array or upgrade |
## Media completion codes
These codes are returned by `POST /complete-media/{mediaFileId}`. Its error responses carry only `error` and `code`, and none sends a `Retry-After` header.
| Code | HTTP | Location | Meaning | Retryable? | Recovery |
|---|---:|---|---|---|---|
| `INVALID_MEDIA_FILE_ID` | 400 | top-level `code` | `mediaFileId` is not a Mongo ObjectId | No | Use the `mediaId` returned by `get-upload-url` |
| `MEDIA_FILE_NOT_FOUND` | 404 | top-level `code` | No media row belongs to the caller for that ID | No | Check the ID and API-key owner; upload again if it was deleted |
| `MEDIA_FILE_INDETERMINATE_TYPE` | 400 | top-level `code` | Neither stored type nor MIME prefix identifies image, video, or PDF | No | Re-upload with the correct `Content-Type` |
| `PROBE_FAILED` | 400 | top-level `code` | The bytes failed byte-level validation in this call (`PROBE_TIMEOUT` when probing took too long). The file is now `failed`, and later calls return `MEDIA_VALIDATION_FAILED`. Also returned for a file that failed earlier without a recorded failure code | No | Delete the file and upload a valid one |
| `MEDIA_VALIDATION_FAILED` | 400 | top-level `code` | The file already failed validation, in an earlier `complete-media` call or a scheduling check | No, unchanged | Delete the file with `DELETE /media/:mediaId` and upload a valid one |
| `MEDIA_UPLOAD_MISSING` | 400 | top-level `code` | No object appeared in storage within five minutes of the first `complete-media` call, so the file is now `failed`. Also returned for a file that failed this way earlier | No, unchanged | Delete the file with `DELETE /media/:mediaId`, upload it again, and use the new `mediaId` |
| `MEDIA_FILE_MISSING_URL` | 500 | top-level `code` | The media row has no storage URL | No client-side retry contract | Upload again; contact support if newly created rows repeat this state |
| `PROBE_VERSION_UNVERIFIED` | 503 | top-level `code` | The object version could not be verified before or after probing | Yes | Retry `complete-media` after a few seconds |
| `PROBE_DOWNLOAD_FAILED` | 503 | top-level `code` | A transient S3/CDN download prevented probing | Yes | Retry `complete-media` after a few seconds |
| `PROBE_VERSION_CHANGED` | 503 | top-level `code` | The uploaded object changed while it was being validated | Yes, after upload stabilizes | Stop overwriting the presigned object and retry |
| `MEDIA_UPLOAD_PENDING` | 503 | top-level `code` | The uploaded object is not visible in storage yet: its `PUT` has not finished, or never happened | Yes | Finish the `PUT`, then retry `complete-media` after a few seconds. If there is still no object five minutes after the first `complete-media` call for the file, the file is marked failed and the call returns `400 MEDIA_UPLOAD_MISSING` |
| `MEDIA_STATE_PERSIST_FAILED` | 503 | top-level `code` | The completion request or the validation result could not be saved | Yes | Retry `complete-media` after a few seconds |
| `PROBE_BUSY` | 503 | top-level `code` | Too many media validations are running at once | Yes | Retry `complete-media` after a few seconds |
| `MEDIA_FILE_RACE` | 409 | top-level `code` | The row was deleted or failed concurrently during probing | No | Re-upload and use the new media ID |
## Media scheduling codes
`update-post` checks every attached media file whenever the post's resulting status is `scheduled`. A file still in `uploading` is validated on the spot, and the request waits up to about 23 seconds for that. `create-post` has no such check: the only media it can attach comes from `mediaUrls`, which is validated while it downloads.
When the check does not pass, the post was not scheduled and none of its fields were saved. Media validation progress is kept: a file the check marked `ready` or `failed` stays that way, and a check still running when the response is sent can finish afterwards. Media from `mediaUrls` in the same request is removed again, and an `Idempotency-Key` is released, so a retry with the same key runs the request again instead of replaying the error.
| Code | HTTP | Location | Meaning | Retryable? | Recovery |
|---|---:|---|---|---|---|
| `MEDIA_UPLOAD_PENDING` | 503 | top-level `code` | An attached upload has no object in storage yet: its `PUT` has not finished, or never happened | Yes | Finish the `PUT`, then retry after `Retry-After` seconds. Every attempt returns this code while the bytes are missing. Once `complete-media` has been called for the file and five minutes pass without an object, the file is marked failed and scheduling returns `400 MEDIA_UPLOAD_MISSING` |
| `MEDIA_VALIDATION_PENDING` | 503 | top-level `code` | Validation did not finish within the wait: storage or probing was temporarily unavailable, or a large file is still being checked. `pendingCode` names the last transient result | Yes | Keep the same `mediaId` and retry after `Retry-After` seconds. A check that finishes after the response is kept for the retry |
| `MEDIA_UPLOAD_MISSING` | 400 | top-level `code` | The upload never produced an object in storage | No, unchanged | Delete the file with `DELETE /media/:mediaId`, upload it again, and schedule with the new `mediaId` |
| `MEDIA_VALIDATION_FAILED` | 400 | top-level `code` | The uploaded bytes are not valid media: corrupt, unsupported, or too slow to probe | No, unchanged | Delete the file, upload a supported one, and schedule again |
| `MEDIA_REFERENCE_MISSING` | 400 | top-level `code` | The post references a media record that no longer exists | No, unchanged | Remove the reference with `DELETE /post/:postGroupId/media/:mediaId` (MCP `prune_media_reference`), then schedule again |
| `MEDIA_NOT_READY` | 400 | top-level `code` | Fallback for a file that is not usable and has no more specific code, such as a failed file without a recorded failure code, or an upload whose media type cannot be determined | After fixing media | Delete and re-upload the file, then schedule again |
The 503 responses carry a `Retry-After: 5` header and this body:
```json
{
"code": "MEDIA_UPLOAD_PENDING",
"error": "Media upload is still pending. The post was not scheduled; finish the upload and retry scheduling.",
"mediaFileId": "507f1f77bcf86cd799439012",
"mediaStatus": "uploading",
"pendingCode": "MEDIA_UPLOAD_PENDING",
"attempts": 18,
"retryable": true,
"retryAfterSec": 5,
"suggestions": ["Media bytes are not uploaded or complete yet. PUT the file bytes to the presigned uploadUrl …"]
}
```
`mediaFileId` is the first attached file that is not ready, and `attempts` counts the validation passes made during the wait. `suggestions` holds one recovery hint, worded for MCP tools when the request carries `x-publora-client: mcp`.
The 400 responses return `{ error, code, mediaFileId, mediaStatus, reason, retryable, suggestions }`. `reason` is the file's recorded failure reason or `null`, and `retryable` is `false` once the file has failed.
Earlier versions of this page listed `MEDIA_VALIDATION_PENDING` as a `200` warning. Scheduling no longer succeeds while validation is pending; it returns the 503 above. `complete-media` reports a missing or pending upload with its own codes; see [Media completion codes](#media-completion-codes).
## `mediaUrls` per-URL codes
When create/update or `attach-media` ingestion fails, the request returns HTTP 400 with `error: "Media ingestion failed"`; the URL/fetch codes below can appear in `mediaResults[].code`. On `attach-media`, a `download_url` that fails the static checks (not a URL, not HTTPS, embedded credentials, a non-443 port, a private or loopback IP address, or a `localhost`, `.local` or `.internal` name) is rejected before any download with top-level `INVALID_MEDIA_FILE`. Everything found later, including DNS results, redirects, fetch errors, size, format and probe failures, is reported in `mediaResults[]`. Probe failures are forwarded into the same field using the applicable code from [Media completion codes](#media-completion-codes). The batch is all-or-nothing.
| Code | HTTP | Location | Meaning | Retryable? | Recovery |
|---|---:|---|---|---|---|
| `MEDIA_URL_INVALID` | 400 | `mediaResults[].code` | The value is not a URL | No | Supply a valid public URL |
| `MEDIA_URL_PROTOCOL` | 400 | `mediaResults[].code` | The URL is not HTTPS | No | Use `https://` |
| `MEDIA_URL_CREDENTIALS` | 400 | `mediaResults[].code` | The URL embeds a username or password | No | Use a credential-free URL, such as a signed HTTPS URL |
| `MEDIA_URL_PORT` | 400 | `mediaResults[].code` | The URL uses a non-default HTTPS port | No | Serve it on port 443 |
| `MEDIA_URL_BLOCKED_HOST` | 400 | `mediaResults[].code` | The host name is blocked (`localhost`, `.local`, `.internal`), the URL uses a private or reserved IP address, or any address the host or a redirect target resolves to is private or reserved | No | Use a publicly reachable host |
| `MEDIA_URL_DNS` | 400 | `mediaResults[].code` | Defensive code for a DNS answer that holds no addresses. The system resolver reports that case as a failed lookup instead, so this code is not currently expected: a nonexistent domain and a host with no A or AAAA records are both reported as `MEDIA_URL_FETCH_FAILED` | Not currently expected | If observed, correct the host's DNS, then retry the whole request |
| `MEDIA_URL_REDIRECT` | 400 | `mediaResults[].code` | A redirect lacked a `Location` header | After the origin is fixed | Use the final URL or fix the redirect |
| `MEDIA_URL_TOO_MANY_REDIRECTS` | 400 | `mediaResults[].code` | The fetch exceeded the redirect limit | No, unchanged | Use a direct URL |
| `MEDIA_URL_HTTP_ERROR` | 400 | `mediaResults[].code` | The remote server returned a non-200 response | After the origin is available | Check access/expiry and retry with a working URL |
| `MEDIA_URL_INGEST_TIMEOUT` | 400 | `mediaResults[].code` | The request-wide media ingestion budget expired | Conditionally | Use a faster origin, smaller media, or the presigned upload flow |
| `MEDIA_URL_TOO_LARGE` | 400 | `mediaResults[].code` | One image/video exceeds the URL-ingestion byte cap | No | Use a smaller file or `get-upload-url` |
| `MEDIA_URL_AGGREGATE_TOO_LARGE` | 400 | `mediaResults[].code` | Combined downloaded bytes exceed 300 MiB | No | Reduce the batch or use presigned uploads |
| `MEDIA_URL_UNSUPPORTED_FORMAT` | 400 | `mediaResults[].code` | Magic-byte detection found an unsupported format | No | Convert to a supported image/video format |
| `MEDIA_URL_FETCH_FAILED` | 400 | `mediaResults[].code` | An unexpected network/download failure occurred. This includes a failed DNS lookup, whether the domain does not exist or the host has no A or AAAA records | Conditionally | Verify the URL and the host's DNS, and retry once; otherwise use presigned upload |
| `MEDIA_URL_PROBE_FAILED` | 400 | `mediaResults[].code` | Defensive fallback if a future failed probe supplies no specific code; current `probeAndPersistMedia` failure branches always supply one | Not currently expected | If observed, convert or re-upload valid media and report the unexpected fallback |
| `MEDIA_URL_SKIPPED` | 400 | `mediaResults[].code` | This URL was not attempted after another URL failed | After fixing the root failure | Correct the failing URL and retry the complete batch |
| `MEDIA_URL_ROLLED_BACK` | 400 | `mediaResults[].code` | This URL succeeded, but its media was removed because another URL failed | After fixing the root failure | Correct the failing URL and retry the complete batch |
## Mastodon and Bluesky analytics codes
`POST /post-statistics` reports per-connection problems in the `issues` object of a `200` response, keyed by connection ID (`-`); the affected `postedId` values are `null` in `stats`. `POST /profile-statistics` reports the same conditions in `unavailable` (`AUTH_REVOKED`, `FORBIDDEN`) and `rateLimited`. See [Mastodon and Bluesky Statistics](../endpoints/platform-statistics.md).
| Code | HTTP | Location | Meaning | Retryable? | Recovery |
|---|---:|---|---|---|---|
| `ANALYTICS_PLAN_REQUIRED` | 403 | top-level `code` | The plan has no analytics feature | No, unchanged | Upgrade to a plan that includes analytics |
| `ANALYTICS_REQUEST_TIMEOUT` | 504 | top-level `code` | The request exceeded its 90-second budget | Yes | Retry with fewer posts per request |
| `CONNECTION_NOT_FOUND` | 200 | `issues[]` | No connection of the caller matches that platform and platform ID | No, unchanged | Re-read `GET /platform-connections` |
| `AUTH_REVOKED` | 200 | `issues[]`, `unavailable` | Mastodon rejected the stored token (HTTP 401) | After reconnecting | Reconnect the account |
| `FORBIDDEN` | 200 | `issues[]`, `unavailable` | Mastodon refused analytics access (HTTP 403, scope or moderation). Publishing is unaffected. | Later | Retry later; reconnect if it persists |
| `RATE_LIMITED` | 200 | `issues[]` | The platform is in a cooldown after answering 429 | Yes, after the cooldown | Retry later; the response also carries `rateLimited: true` |
| `FETCH_FAILED` | 200 | `issues[]` | A transient failure reaching the platform | Yes | Retry later |
## LinkedIn symbolic errors
These LinkedIn endpoints use the `error` field for stable symbolic values rather than a separate `code` field.
| Value | HTTP | Meaning | Retryable? | Recovery |
|---|---:|---|---|---|
| `REACTION_ALREADY_EXISTS` | 409 | The actor already has a reaction on the target post | No, unchanged | Delete the existing reaction, then apply the requested type |
| `LINKEDIN_TOKEN_EXPIRED` | 401 | The stored LinkedIn access token is expired | No | Reconnect the LinkedIn account |
| `LINKEDIN_RATE_LIMITED` | 429 | LinkedIn is rate-limiting the analytics resource/account | Yes | Wait the returned `retryAfter` seconds |
| `LINKEDIN_REQUEST_TIMEOUT` | 504 | The backend request deadline elapsed while waiting for LinkedIn | Yes | Retry the read/interaction with normal backoff |
## Post validation codes
Scheduling validation returns HTTP 400. These codes appear in `validation.errors[].code`. A successful request returns no `validation` object at all, so validation warnings are not part of the success contract.
| Code | Meaning | Recovery |
|---|---|---|
| `CONTENT_TOO_LONG` | Content exceeds the selected platform's character limit | Shorten it or change the target platform/account tier |
| `CONTENT_OR_MEDIA_REQUIRED` | The post has neither usable text nor media | Add content or media |
| `MEDIA_REQUIRED` | A selected platform requires media | Attach supported images or video |
| `MEDIA_SIZE_EXCEEDED` | A file exceeds the platform byte limit | Compress or replace it |
| `MEDIA_COUNT_EXCEEDED` | Too many media items are attached | Delete extras and schedule again |
| `MEDIA_TYPE_NOT_SUPPORTED` | The media type is unsupported for the platform | Convert or remove it |
| `MEDIA_DIMENSIONS_INVALID` | Image/video dimensions violate a platform rule | Resize the media |
| `MEDIA_ASPECT_RATIO_INVALID` | Aspect ratio violates a platform rule | Crop or resize the media |
| `VIDEO_REQUIRED` | The selected platform requires video | Attach a supported video |
| `VIDEO_DURATION_EXCEEDED` | Video is longer than the platform maximum | Trim it |
| `VIDEO_DURATION_TOO_SHORT` | Video is shorter than the platform minimum | Use a longer video |
| `IMAGES_NOT_SUPPORTED` | The selected platform does not accept images for this post type | Remove images or change the target |
| `DOCUMENTS_NOT_SUPPORTED` | The selected platform does not accept document media | Remove the document or target LinkedIn |
| `PLATFORM_SETTING_REQUIRED` | A required platform-specific setting is absent | Supply the field identified in the error |
| `PLATFORM_SETTING_INVALID` | A platform-specific setting has an invalid value | Use one of the reported accepted values |
| `PLATFORM_NOT_SUPPORTED` | The validator has no contract for the target platform | Remove the unsupported target |
All validation codes above are non-retryable with the unchanged request.
## Threads chain codes
These codes concern multi-part Threads chains only. A single Threads post never
triggers the permission check.
### At scheduling
| Code | HTTP | Location | Meaning | Retryable? | Recovery |
|---|---:|---|---|---|---|
| `THREADS_PERMISSION_REQUIRED` | 400 | `validation.errors[].code` | The connection's token does not grant `threads_manage_replies`, or the connection no longer exists. Nothing was published | No, unchanged | Reconnect that Threads account in Publora **Channels**, approve all requested permissions, then schedule again |
| `TOKEN_EXPIRED` | 400 | `validation.errors[].code` | The stored Threads token is absent, or Meta reports it invalid | No, unchanged | Reconnect the Threads account |
| `THREADS_PERMISSIONS_UNAVAILABLE` | 503 | top-level `code` | Publora could not complete the permission check itself. This is **not** an account problem and never means reconnect | Usually | Retry scheduling in a few seconds. A lookup that keeps failing is a Publora-side configuration problem no retry will clear — contact support |
| `THREAD_PART_TOO_LONG` | 400 | `validation.errors[].code` | A resolved thread part exceeds 500 characters. Automatic splitting never produces one, but a `[n/m]` part you wrote yourself is not re-split, so an oversized one lands here | No, unchanged | Shorten that part; `field` names its index |
| `INVALID_PLATFORM_CONTENT` | 400 | `validation.errors[].code` | A stored thread part is not a text string | No, unchanged | Edit or remove the invalid part |
> **`THREADS_PERMISSIONS_UNAVAILABLE` has its own envelope.** Unlike the validation
> codes, it returns `{ "code": "THREADS_PERMISSIONS_UNAVAILABLE", "error": "…" }`
> with **no** `validation` object.
> **`THREADS_PERMISSION_REQUIRED` carries one of two messages.** A connection whose
> token lacks the grant returns *"Reconnect your Threads account and allow reply
> publishing to publish a thread with multiple posts."*; a target whose connection no
> longer exists returns *"Reconnect your Threads account before scheduling a thread."*
> Match on the code, not the message.
> **There is no way to pre-check the grant.** `GET /platform-connections` does not
> report granted scopes, so a missing permission first surfaces as
> `THREADS_PERMISSION_REQUIRED` when you schedule a chain.
### At publishing
These appear in `posts[].error.code` from `GET /get-post`, never as an HTTP status.
| Code | Meaning | Retryable? | Recovery |
|---|---|---|---|
| `THREADS_INVALID_THREAD_PART` | A part was empty, not text, or over 500 characters including its numbering | No | Fix the content and create a new post |
| `THREAD_PARTIALLY_PUBLISHED` | Some parts published, then one failed. The published parts are live and Publora will not republish the chain | No | Read `threadParts`, then publish only the missing parts |
| `PUBLISH_OUTCOME_UNKNOWN` | Threads accepted a publish request without returning an ID, so the outcome is genuinely unknown. Automatic retry is disabled to avoid duplicates | No | Check the live Threads account before posting anything further |
| `THREADS_PERMISSION_REQUIRED` | The grant disappeared between scheduling and publishing. Nothing was published | No | Reconnect the account and schedule again |
> **Never resubmit a chain after `THREAD_PARTIALLY_PUBLISHED` or
> `PUBLISH_OUTCOME_UNKNOWN`.** Parts marked `published` in `threadParts` already
> exist on the platform; recreating the post duplicates them.
## Source coverage
- Top-level scheduling and idempotency responses: `backend/src/app/routes/apiRoute.js`.
- Plan entitlement responses: `backend/src/app/services/limitsService.js`.
- Scheduling guards and media state: `backend/src/app/helpers/scheduledPlatformsGuard.js`, `mediaStatusTransitions.js`, `mediaUploadPolicy.js`, `probeMediaUpload.js`, and `apiValidationRecovery.js`.
- Per-URL ingestion: `backend/src/app/helpers/mediaUrlIngest.js` and `mediaUrlSecurity.js`.
- File-reference input for `attach-media`: `backend/src/app/helpers/mediaFileInput.js`.
- Validation codes actually emitted by scheduling: `backend/src/app/services/postValidationService.js` and `errors/ValidationError.js`.
- Threads chain permission and publish errors: `backend/src/app/helpers/threadsPermissions.js`, `backend/src/app/services/threadsPostPreflight.js`, and `scheduler-service/src/app/controllers/threadsController.js`.
- LinkedIn interaction/analytics errors: `backend/src/app/controllers/linkedinController.js`.
- Mastodon/Bluesky analytics responses: `backend/src/app/controllers/platformAnalyticsController.js` and `backend/src/app/services/platformAnalytics/`.
## Company webhook errors
Company `/webhooks` uses `AGENCY_CORE_ACCESS_DENIED` (403),
`COMPANY_WEBHOOK_INPUT_INVALID` (400), `COMPANY_WEBHOOK_NOT_FOUND` (404),
`COMPANY_WEBHOOK_LIMIT`, `COMPANY_WEBHOOK_CONFLICT`,
`COMPANY_WEBHOOK_IDEMPOTENCY_CONFLICT`, `COMPANY_WEBHOOK_IDEMPOTENCY_IN_FLIGHT`,
`COMPANY_WEBHOOK_CLIENT_UPDATE_REQUIRED` (409), and `COMPANY_WEBHOOK_UNAVAILABLE`
(503). See [Agency webhooks](agency-webhooks.md) for recovery and stable-retry rules.
## Company LinkedIn reshare and review errors
Company `/linkedin-page-posts` returns `LINKEDIN_INVALID_REQUEST` and
`LINKEDIN_COMPANY_PAGE_REQUIRED` (400), `LINKEDIN_TOKEN_EXPIRED` and
`LINKEDIN_RECONNECT_REQUIRED` (401), `AGENCY_CORE_ACCESS_DENIED` (403),
`AGENCY_CORE_CONNECTION_NOT_FOUND` (404), `LINKEDIN_RATE_LIMITED` (429),
`LINKEDIN_INVALID_RESPONSE` (502) and `COMPANY_LINKEDIN_UNAVAILABLE` (503). Timed
client reviews add `COMPANY_APPROVAL_SCHEDULING_FAILED` (409) and
`COMPANY_APPROVAL_SCHEDULING_UNAVAILABLE` (503); approval reads without the v2
`Accept` header can return `COMPANY_APPROVAL_CLIENT_UPDATE_REQUIRED` (409). See
[Agency LinkedIn Page reshares](agency-linkedin-reshares.md).
## Company LinkedIn Page read errors
Company `/linkedin-page-posts/batch`, `/linkedin-page-posts/comments` and
`/linkedin-page-posts/reactions` return the codes of the Page post list above,
plus:
| Code | HTTP | Meaning | Recovery |
|---|---:|---|---|
| `LINKEDIN_BATCH_UNAVAILABLE` | 403 | Batch only: the Page connection was authorized through an older LinkedIn app | Follow the steps in `message`: reconnect the Page, or have the Workspace manager contact Publora support |
| `LINKEDIN_INSUFFICIENT_SCOPE` | 403 | The Page connection lacks a required LinkedIn read permission | Follow the reconnect steps in `message`, then retry |
| `LINKEDIN_ACCESS_DENIED` | 403 | LinkedIn refused access to the resource | Check the Page connection's access, then retry |
| `LINKEDIN_NOT_FOUND` | 404 | Comments/reactions: the post is missing, unpublished or not authored by this Page | Use a `postedId` from the Page's post list |
| `LINKEDIN_TEMPORARILY_UNAVAILABLE` | 5xx | The LinkedIn read failed | Retry later |
| `LINKEDIN_REQUEST_TIMEOUT` | 504 | The LinkedIn read deadline elapsed | Retry with backoff |
A batch response with HTTP 200 lists per-post failures in `data.errors[].code`:
`LINKEDIN_TOKEN_EXPIRED`, `LINKEDIN_ACCESS_DENIED`, `LINKEDIN_NOT_FOUND`,
`LINKEDIN_RATE_LIMITED` or `LINKEDIN_ITEM_UNAVAILABLE`. See
[Agency LinkedIn Page reads](agency-linkedin-page-reads.md#errors).
---
> Source: https://docs.publora.com/guides/rate-limits
# Rate Limits and Optimal Posting Times
This guide covers platform-specific rate limits, Publora API rate limits, and strategies for scheduling posts at optimal engagement times.
## Quick Start: High-Volume Multi-Platform Scheduling
For scheduling hundreds of posts across all 10 platforms simultaneously, use this production-ready approach:
### Installation
```bash
# JavaScript/Node.js
npm install axios
# Python
pip install requests
```
### Environment Setup
```bash
# Set your API key (get it from publora.com → API in sidebar)
export PUBLORA_API_KEY="sk_YOUR_API_KEY"
```
### Minimal Working Example
**JavaScript (Node.js):**
```javascript
// high-volume-scheduler.js
// Run: PUBLORA_API_KEY=sk_YOUR_API_KEY node high-volume-scheduler.js
const axios = require('axios');
const API_KEY = process.env.PUBLORA_API_KEY;
const BASE_URL = 'https://api.publora.com/api/v1';
// Optional user-supplied throttles. Publora defines no per-platform quotas.
const PLATFORM_LIMITS = {};
async function schedulePost(content, platforms, scheduledTime) {
const response = await axios.post(`${BASE_URL}/create-post`, {
content,
platforms,
scheduledTime
}, {
headers: {
'x-publora-key': API_KEY,
'Content-Type': 'application/json'
}
});
return response.data;
}
async function main() {
// Your platform connection IDs (from /platform-connections endpoint)
const platforms = ['twitter-123456', 'linkedin-ABC123', 'threads-789012'];
// Schedule 10 posts, 1 hour apart
const now = new Date();
for (let i = 0; i < 10; i++) {
const scheduledTime = new Date(now.getTime() + (i + 1) * 3600000);
const result = await schedulePost(
`Post ${i + 1}: Your content here`,
platforms,
scheduledTime.toISOString()
);
console.log(`Scheduled post ${i + 1}: ${result.postGroupId}`);
}
}
main().catch(console.error);
```
**Python:**
```python
#!/usr/bin/env python3
# high_volume_scheduler.py
# Run: PUBLORA_API_KEY=sk_YOUR_API_KEY python high_volume_scheduler.py
import os
import requests
from datetime import datetime, timedelta, timezone
API_KEY = os.environ['PUBLORA_API_KEY']
BASE_URL = 'https://api.publora.com/api/v1'
# Optional user-supplied throttles. Publora defines no per-platform quotas.
PLATFORM_LIMITS = {}
def schedule_post(content: str, platforms: list, scheduled_time: str) -> dict:
response = requests.post(
f'{BASE_URL}/create-post',
json={
'content': content,
'platforms': platforms,
'scheduledTime': scheduled_time
},
headers={
'x-publora-key': API_KEY,
'Content-Type': 'application/json'
}
)
response.raise_for_status()
return response.json()
def main():
# Your platform connection IDs (from /platform-connections endpoint)
platforms = ['twitter-123456', 'linkedin-ABC123', 'threads-789012']
# Schedule 10 posts, 1 hour apart
now = datetime.now(timezone.utc)
for i in range(10):
scheduled_time = now + timedelta(hours=i + 1)
result = schedule_post(
f'Post {i + 1}: Your content here',
platforms,
scheduled_time.isoformat()
)
print(f"Scheduled post {i + 1}: {result['postGroupId']}")
if __name__ == '__main__':
main()
```
---
## Publora Plan Limits
Each Publora plan enforces limits on monthly posts, scheduled (pending) posts, and how far in advance you can schedule.
| Plan | Monthly Posts | Connections | Post Limit Scope | Scheduled Posts | Schedule Horizon | API/MCP Access | Platforms |
|------|-------------|-------------|------------------|-----------------|------------------|----------------|-----------|
| **Starter (Free)** | 15 | 3 | Account-wide | 3 pending | 7 days | Yes | All platforms, except X |
| **Pro Monthly (graduated, from $5.99/account)** | 5,000 (fair use) | Per purchased quantity* | Per connection | Unlimited | Unlimited | Yes | All |
| **Pro Yearly (graduated, from $3.99/account)** | 5,000 (fair use) | Per purchased quantity* | Per connection | Unlimited | Unlimited | Yes | All |
| **Pro Monthly — legacy ($5.99/mo)** | 100 | Per seat* | Per connection | 100 pending | Unlimited | Yes | All |
| **Pro Yearly — legacy ($2.99/mo)** | 100 | Per seat* | Per connection | 100 pending | Unlimited | Yes | All |
| **Premium Monthly — legacy ($9.99/mo)** | 500 | Per seat* | Per connection | 500 pending | Unlimited | Yes | All |
| **Premium Yearly — legacy ($5.99/mo)** | 500 | Per seat* | Per connection | 500 pending | Unlimited | Yes | All |
*\*Paid plan connection limits are based on subscription quantity (seat count), not truly unlimited. Each seat in your subscription adds to your total allowed connections.*
**Key details:**
- **Monthly-post scope:** Starter's 15 monthly posts are account-wide; paid-plan `monthlyPosts` are counted per connection (for example, 100 for one LinkedIn connection and 100 for one Twitter connection). The active `scheduledPosts` queue limit is account-wide on every plan, not per connection. Connection count and schedule horizon are separate plan limits.
- **Starter plan includes API and MCP access** (`apiAccess: true`, `mcpAccess: true`) — the free tier can use the REST API and MCP server (3 connected accounts, 15 posts/month account-wide).
- **Starter plan can post to every platform except X/Twitter.** Publishing to X requires Pro: a new Starter account that targets X gets `403 PLATFORM_NOT_AVAILABLE`. Starter accounts that already used X before the restriction keep it. `allowedPlatforms` in [`GET /account-context`](../endpoints/account-context.md) lists the platforms of your plan.
> **Note:** Per-request API rate limiting (requests/minute) is **planned but not currently enforced**. The limits above (monthly posts, scheduled posts, schedule horizon) are the enforced plan-based limits. Future API rate limiting will be documented here when implemented.
## Platform-Specific Rate Limits (Advisory)
Platform-side posting limits are advisory, account-dependent, and may change without notice. Publora does not treat unsourced posts-per-hour/day figures as an API contract; consult the destination platform for current quotas.
### What Publora enforces
- Plan entitlements shown above (monthly posts, pending posts, connections, and scheduling horizon).
- Media-URL ingestion: 60 URLs per fixed one-hour window; `429 MEDIA_URL_RATE_LIMITED` includes `Retry-After`.
- MCP session limits documented by the MCP endpoint.
Platform-side rate-limit failures are reported on the post. Do not assume Publora automatically retries or redistributes a failed platform publication.
## API Reference for Scheduling
The scheduler examples use these Publora API endpoints:
### Create Post
```http
POST https://api.publora.com/api/v1/create-post
Content-Type: application/json
x-publora-key: sk_YOUR_API_KEY
{
"content": "Your post content",
"platforms": ["twitter-123456", "linkedin-ABC123"],
"scheduledTime": ""
}
```
**Response:**
```json
{
"success": true,
"postGroupId": "67a1b2c3d4e5f6a7b8c9d0e1",
"scheduledTime": ""
}
```
### Get Post Status
```http
GET https://api.publora.com/api/v1/get-post/{postGroupId}
x-publora-key: sk_YOUR_API_KEY
```
**Response:**
```json
{
"success": true,
"postGroupId": "67a1b2c3d4e5f6a7b8c9d0e1",
"status": "published",
"scheduledTime": "2026-03-15T14:00:00.000Z",
"platformSettings": {},
"platforms": ["twitter-123456", "linkedin-ABC123"],
"posts": [
{
"platform": "twitter",
"platformId": "123456",
"status": "published",
"postedId": "1234567890123456789",
"permalink": "https://twitter.com/user/status/123456"
},
{
"platform": "linkedin",
"platformId": "ABC123",
"status": "published",
"postedId": "urn:li:share:7000000000000000000",
"permalink": "https://linkedin.com/posts/..."
}
],
"media": []
}
```
> **Note:** The `get-post` endpoint returns the **raw** `platformId` (e.g., `"123456"`), not the composite format (e.g., `"twitter-123456"`). The composite `platform-platformId` format is only returned by the `list-posts` and `platform-connections` endpoints.
### Get Platform Connections
```http
GET https://api.publora.com/api/v1/platform-connections
x-publora-key: sk_YOUR_API_KEY
```
**Response:**
```json
{
"success": true,
"connections": [
{ "platformId": "twitter-123456789", "username": "myaccount", "displayName": "My Account", "tokenStatus": "valid" },
{ "platformId": "linkedin-ABC123", "username": "My Company", "displayName": "My Company", "tokenStatus": "valid" },
{ "platformId": "threads-789012", "username": "mythreads", "displayName": "My Threads", "tokenStatus": "valid" }
]
}
```
Use the `platformId` field from connections as the platform identifier when creating posts.
## Examples
### JavaScript - Publora API Client
```javascript
class PubloraClient {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://api.publora.com/api/v1';
}
async request(endpoint, options = {}) {
const response = await fetch(`${this.baseUrl}${endpoint}`, {
...options,
headers: {
'x-publora-key': this.apiKey,
'Content-Type': 'application/json',
...options.headers
}
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error || `HTTP ${response.status}`);
}
return response.json();
}
async createPost(content, platforms, scheduledTime) {
return this.request('/create-post', {
method: 'POST',
body: JSON.stringify({ content, platforms, scheduledTime })
});
}
async listPosts(params = {}) {
const query = new URLSearchParams(params).toString();
return this.request(`/list-posts?${query}`);
}
}
// Usage
const client = new PubloraClient('YOUR_API_KEY');
for (let i = 0; i < 100; i++) {
await client.createPost(
`Post ${i + 1}`,
['twitter-123'],
new Date(Date.now() + i * 3600000).toISOString()
);
}
```
### Python - Publora API Client with Retry
```python
import requests
import time
from typing import Dict, Any, Optional
class PubloraClient:
def __init__(self, api_key: str):
self.api_key = api_key
self.base_url = 'https://api.publora.com/api/v1'
def _request(
self,
method: str,
endpoint: str,
data: Optional[Dict] = None,
params: Optional[Dict] = None,
max_retries: int = 3
) -> Dict[str, Any]:
"""Make a request with retry on failure."""
headers = {
'x-publora-key': self.api_key,
'Content-Type': 'application/json'
}
for attempt in range(max_retries):
response = requests.request(
method,
f'{self.base_url}{endpoint}',
headers=headers,
json=data,
params=params
)
if response.status_code >= 500:
backoff = 2 ** attempt
print(f"Server error. Retrying in {backoff}s (attempt {attempt + 1})")
time.sleep(backoff)
continue
response.raise_for_status()
return response.json()
raise Exception("Max retries exceeded")
def create_post(
self,
content: str,
platforms: list,
scheduled_time: Optional[str] = None
) -> Dict[str, Any]:
data = {'content': content, 'platforms': platforms}
if scheduled_time:
data['scheduledTime'] = scheduled_time
return self._request('POST', '/create-post', data=data)
def list_posts(self, **params) -> Dict[str, Any]:
return self._request('GET', '/list-posts', params=params)
# Usage
client = PubloraClient('YOUR_API_KEY')
# Bulk create
from datetime import datetime, timedelta, timezone
base_time = datetime.now(timezone.utc) + timedelta(hours=1)
for i in range(100):
scheduled = (base_time + timedelta(hours=i)).isoformat()
result = client.create_post(
f"Scheduled post {i + 1}",
['twitter-123', 'linkedin-ABC'],
scheduled
)
print(f"Created post {i + 1}: {result['postGroupId']}")
```
## Peak Engagement Times
Optimal posting times vary by platform and audience. Use these guidelines as a starting point, then analyze your own analytics.
### Platform-Specific Best Times (UTC)
| Platform | Best Days | Best Hours (UTC) | Peak Engagement |
|----------|-----------|------------------|-----------------|
| **X/Twitter** | Tue-Thu | 13:00-16:00 | Wednesday 12:00 |
| **LinkedIn** | Tue-Thu | 10:00-12:00 | Tuesday 10:00 |
| **Instagram** | Mon, Wed | 11:00-14:00, 19:00-21:00 | Wednesday 11:00 |
| **Threads** | Tue-Thu | 12:00-15:00 | Wednesday 13:00 |
| **TikTok** | Tue-Thu | 15:00-21:00 | Thursday 19:00 |
| **YouTube** | Thu-Sat | 14:00-18:00 | Friday 15:00 |
| **Facebook** | Wed-Fri | 13:00-16:00 | Wednesday 13:00 |
| **Bluesky** | Mon-Fri | 14:00-17:00 | Tuesday 15:00 |
### JavaScript - Optimal Time Scheduler
```javascript
const OPTIMAL_TIMES = {
twitter: {
bestDays: [2, 3, 4], // Tue, Wed, Thu (0 = Sunday)
bestHours: [13, 14, 15, 16],
peakDay: 3,
peakHour: 12
},
linkedin: {
bestDays: [2, 3, 4],
bestHours: [10, 11, 12],
peakDay: 2,
peakHour: 10
},
instagram: {
bestDays: [1, 3], // Mon, Wed
bestHours: [11, 12, 13, 14, 19, 20, 21],
peakDay: 3,
peakHour: 11
},
threads: {
bestDays: [2, 3, 4],
bestHours: [12, 13, 14, 15],
peakDay: 3,
peakHour: 13
},
tiktok: {
bestDays: [2, 3, 4],
bestHours: [15, 16, 17, 18, 19, 20, 21],
peakDay: 4,
peakHour: 19
},
facebook: {
bestDays: [3, 4, 5], // Wed, Thu, Fri
bestHours: [13, 14, 15, 16],
peakDay: 3,
peakHour: 13
}
};
function getNextOptimalTime(platform, fromDate = new Date()) {
const config = OPTIMAL_TIMES[platform];
if (!config) throw new Error(`Unknown platform: ${platform}`);
const result = new Date(fromDate);
result.setUTCMinutes(0, 0, 0);
// Find next best day
let daysToAdd = 0;
while (!config.bestDays.includes(result.getUTCDay()) || daysToAdd === 0) {
result.setUTCDate(result.getUTCDate() + 1);
daysToAdd++;
if (daysToAdd > 7) break;
}
// Set to best hour
result.setUTCHours(config.bestHours[0]);
return result;
}
function getPeakTime(platform, weekStart = new Date()) {
const config = OPTIMAL_TIMES[platform];
if (!config) throw new Error(`Unknown platform: ${platform}`);
const result = new Date(weekStart);
result.setUTCHours(0, 0, 0, 0);
// Move to peak day
const currentDay = result.getUTCDay();
const daysUntilPeak = (config.peakDay - currentDay + 7) % 7;
result.setUTCDate(result.getUTCDate() + daysUntilPeak);
// Set peak hour
result.setUTCHours(config.peakHour);
return result;
}
function distributePostsOptimally(platforms, count, startDate = new Date()) {
const schedule = [];
const date = new Date(startDate);
for (let i = 0; i < count; i++) {
const platform = platforms[i % platforms.length];
const optimalTime = getNextOptimalTime(platform, date);
schedule.push({
index: i,
platform,
scheduledTime: optimalTime.toISOString()
});
// Move forward for next post
date.setTime(optimalTime.getTime() + 3600000); // +1 hour minimum gap
}
return schedule;
}
// Usage
const schedule = distributePostsOptimally(
['twitter', 'linkedin', 'instagram'],
9, // 3 posts per platform
new Date()
);
console.log('Optimal posting schedule:');
schedule.forEach(item => {
console.log(`${item.platform}: ${item.scheduledTime}`);
});
```
### Python - Queue-Based Scheduler with Rate Limits
```python
from datetime import datetime, timedelta, timezone
from typing import List, Dict, Optional
from dataclasses import dataclass
from collections import defaultdict
import heapq
@dataclass
class PlatformConfig:
posts_per_hour: int
posts_per_day: int
best_hours: List[int] # UTC hours
best_days: List[int] # 0=Monday, 6=Sunday
PLATFORM_LIMITS = {
'twitter': PlatformConfig(
posts_per_hour=10,
posts_per_day=50,
best_hours=[13, 14, 15, 16],
best_days=[1, 2, 3] # Tue, Wed, Thu
),
'linkedin': PlatformConfig(
posts_per_hour=5,
posts_per_day=20,
best_hours=[10, 11, 12],
best_days=[1, 2, 3]
),
'instagram': PlatformConfig(
posts_per_hour=3,
posts_per_day=10,
best_hours=[11, 12, 13, 14, 19, 20, 21],
best_days=[0, 2] # Mon, Wed
),
'tiktok': PlatformConfig(
posts_per_hour=2,
posts_per_day=10,
best_hours=[15, 16, 17, 18, 19, 20, 21],
best_days=[1, 2, 3]
),
}
class OptimalScheduler:
"""
Schedule posts optimally across platforms considering:
- Platform-specific rate limits
- Peak engagement times
- Even distribution across time slots
"""
def __init__(self):
self.platform_queues: Dict[str, List] = defaultdict(list)
self.posts_per_hour: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int))
self.posts_per_day: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int))
def get_next_optimal_slot(
self,
platform: str,
after: datetime
) -> datetime:
"""Find the next available optimal time slot for a platform."""
config = PLATFORM_LIMITS.get(platform)
if not config:
# Unknown platform - just space by 1 hour
return after + timedelta(hours=1)
candidate = after.replace(minute=0, second=0, microsecond=0)
for _ in range(168): # Check up to 1 week ahead
candidate += timedelta(hours=1)
day_key = candidate.strftime('%Y-%m-%d')
hour_key = candidate.strftime('%Y-%m-%d-%H')
# Check rate limits
if self.posts_per_day[platform][day_key] >= config.posts_per_day:
# Skip to next day
candidate = candidate.replace(hour=0) + timedelta(days=1)
continue
if self.posts_per_hour[platform][hour_key] >= config.posts_per_hour:
continue
# Check if this is an optimal time
if (candidate.weekday() in config.best_days and
candidate.hour in config.best_hours):
return candidate
# If no optimal slot found, return next available
return after + timedelta(hours=1)
def schedule_post(
self,
platform: str,
after: datetime = None
) -> datetime:
"""Schedule a single post and return its time."""
if after is None:
after = datetime.now(timezone.utc)
scheduled_time = self.get_next_optimal_slot(platform, after)
# Update counters
day_key = scheduled_time.strftime('%Y-%m-%d')
hour_key = scheduled_time.strftime('%Y-%m-%d-%H')
self.posts_per_day[platform][day_key] += 1
self.posts_per_hour[platform][hour_key] += 1
return scheduled_time
def schedule_batch(
self,
posts: List[Dict],
start_after: datetime = None
) -> List[Dict]:
"""
Schedule multiple posts across platforms optimally.
Args:
posts: List of {'content': str, 'platforms': List[str]}
start_after: Earliest scheduling time
Returns:
List of posts with scheduledTime added
"""
if start_after is None:
start_after = datetime.now(timezone.utc)
scheduled_posts = []
platform_last_time: Dict[str, datetime] = {}
for post in posts:
platforms = post['platforms']
# Find the latest "next optimal time" across all platforms
scheduled_time = start_after
for platform in platforms:
platform_name = platform.split('-')[0]
after = platform_last_time.get(platform_name, start_after)
optimal_time = self.schedule_post(platform_name, after)
if optimal_time > scheduled_time:
scheduled_time = optimal_time
platform_last_time[platform_name] = scheduled_time
scheduled_posts.append({
**post,
'scheduledTime': scheduled_time.isoformat()
})
return scheduled_posts
# Usage example
scheduler = OptimalScheduler()
# Posts to schedule
posts = [
{'content': 'Morning motivation!', 'platforms': ['twitter-123', 'linkedin-ABC']},
{'content': 'Product update announcement', 'platforms': ['twitter-123', 'linkedin-ABC', 'instagram-456']},
{'content': 'Behind the scenes', 'platforms': ['instagram-456', 'tiktok-789']},
{'content': 'Weekly tips thread', 'platforms': ['twitter-123']},
{'content': 'Customer success story', 'platforms': ['linkedin-ABC']},
]
scheduled = scheduler.schedule_batch(posts)
print("Optimally scheduled posts:")
for post in scheduled:
print(f" {post['scheduledTime']}: {post['content'][:30]}...")
print(f" Platforms: {post['platforms']}")
```
### Node.js - Complete Rate-Limited Queue System
```javascript
const axios = require('axios');
class PubloraQueueScheduler {
constructor(apiKey, platformLimits = {}) {
this.apiKey = apiKey;
this.api = axios.create({
baseURL: 'https://api.publora.com/api/v1',
headers: { 'x-publora-key': apiKey }
});
// User-supplied throttles. Publora does not define per-platform posting quotas.
this.platformLimits = platformLimits;
this.peakHours = {
twitter: [13, 14, 15, 16],
linkedin: [10, 11, 12],
instagram: [11, 12, 13, 14, 19, 20, 21],
tiktok: [15, 16, 17, 18, 19, 20, 21],
facebook: [13, 14, 15, 16],
};
this.postCounts = { hourly: {}, daily: {} };
}
getPlatformName(platformId) {
return platformId.split('-')[0];
}
getHourKey(date) {
return date.toISOString().slice(0, 13);
}
getDayKey(date) {
return date.toISOString().slice(0, 10);
}
canPostAt(platform, date) {
const limits = this.platformLimits[platform];
if (!limits) return true;
const hourKey = `${platform}-${this.getHourKey(date)}`;
const dayKey = `${platform}-${this.getDayKey(date)}`;
const hourlyCount = this.postCounts.hourly[hourKey] || 0;
const dailyCount = this.postCounts.daily[dayKey] || 0;
return hourlyCount < limits.perHour && dailyCount < limits.perDay;
}
recordPost(platform, date) {
const hourKey = `${platform}-${this.getHourKey(date)}`;
const dayKey = `${platform}-${this.getDayKey(date)}`;
this.postCounts.hourly[hourKey] = (this.postCounts.hourly[hourKey] || 0) + 1;
this.postCounts.daily[dayKey] = (this.postCounts.daily[dayKey] || 0) + 1;
}
isPeakTime(platform, date) {
const hours = this.peakHours[platform];
return hours ? hours.includes(date.getUTCHours()) : true;
}
findNextOptimalSlot(platforms, after) {
let candidate = new Date(after);
candidate.setUTCMinutes(0, 0, 0);
for (let i = 0; i < 168; i++) { // Check up to 1 week
candidate = new Date(candidate.getTime() + 3600000); // +1 hour
const allCanPost = platforms.every(p =>
this.canPostAt(this.getPlatformName(p), candidate)
);
if (!allCanPost) continue;
const anyPeak = platforms.some(p =>
this.isPeakTime(this.getPlatformName(p), candidate)
);
if (anyPeak) {
return candidate;
}
}
// Fallback: return next hour
return new Date(after.getTime() + 3600000);
}
async scheduleOptimally(posts) {
const results = [];
let lastTime = new Date();
for (const post of posts) {
const scheduledTime = this.findNextOptimalSlot(post.platforms, lastTime);
// Record for rate limiting
post.platforms.forEach(p => {
this.recordPost(this.getPlatformName(p), scheduledTime);
});
try {
const { data } = await this.api.post('/create-post', {
content: post.content,
platforms: post.platforms,
scheduledTime: scheduledTime.toISOString()
});
results.push({
success: true,
postGroupId: data.postGroupId,
scheduledTime: scheduledTime.toISOString(),
content: post.content.slice(0, 50)
});
console.log(`Scheduled: ${post.content.slice(0, 30)}... at ${scheduledTime.toISOString()}`);
} catch (error) {
results.push({
success: false,
error: error.response?.data?.message || error.message,
content: post.content.slice(0, 50)
});
}
lastTime = scheduledTime;
// Small delay between API calls
await new Promise(r => setTimeout(r, 100));
}
return results;
}
}
// Usage
const scheduler = new PubloraQueueScheduler('YOUR_API_KEY');
const posts = [
{ content: 'Morning motivation!', platforms: ['twitter-123', 'linkedin-ABC'] },
{ content: 'Product update', platforms: ['twitter-123', 'linkedin-ABC', 'instagram-456'] },
{ content: 'Behind the scenes', platforms: ['instagram-456', 'tiktok-789'] },
];
const results = await scheduler.scheduleOptimally(posts);
console.log(`Scheduled ${results.filter(r => r.success).length} of ${results.length} posts`);
```
## Complete Queue-Based Scheduling System
This section provides a production-ready implementation that combines all the concepts: rate limiting, optimal scheduling, error handling, retry logic, and failed post recovery.
### Architecture Overview
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Content Queue │───►│ Rate Limiter │───►│ Publora API │
│ (your posts) │ │ + Scheduler │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
▼ ▼
┌──────────────────┐ ┌─────────────────┐
│ Retry Queue │ │ Status Checker │
│ (failed posts) │ │ (polling) │
└──────────────────┘ └─────────────────┘
```
### JavaScript - Production Queue Scheduler
```javascript
const axios = require('axios');
/**
* Production-ready queue-based scheduler for Publora API
* Features:
* - Platform-specific rate limiting
* - Peak engagement time optimization
* - Exponential backoff retry logic
* - Failed post recovery
* - Comprehensive error handling
*/
class PubloraQueueScheduler {
constructor(apiKey, options = {}) {
this.apiKey = apiKey;
this.baseUrl = options.baseUrl || 'https://api.publora.com/api/v1';
this.maxRetries = options.maxRetries || 3;
this.retryDelay = options.retryDelay || 1000;
// API rate limit tracking
this.rateLimitRemaining = Infinity;
this.rateLimitReset = 0;
// Optional user-supplied throttles; Publora defines no per-platform quotas.
this.platformLimits = options.platformLimits || {};
// Peak engagement hours (UTC) - all 10 platforms
this.peakHours = {
twitter: [13, 14, 15, 16],
linkedin: [10, 11, 12],
instagram: [11, 12, 13, 14, 19, 20, 21],
threads: [12, 13, 14, 15],
tiktok: [15, 16, 17, 18, 19, 20, 21],
facebook: [13, 14, 15, 16],
youtube: [14, 15, 16, 17, 18],
bluesky: [14, 15, 16, 17],
mastodon: [14, 15, 16, 17],
telegram: [9, 10, 11, 12, 18, 19, 20],
};
// Track scheduled posts per platform
this.postCounts = { hourly: {}, daily: {} };
// Failed posts queue for retry
this.failedQueue = [];
// Results tracking
this.results = [];
}
// ... (rest of the implementation)
}
```
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) -- the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/platform-limits
# Platform Limits Reference
This comprehensive guide documents the limits for all 10 social media platforms supported by Publora. Understanding these limits is essential for building reliable integrations with the Publora API.
**Last Updated:** March 2026
> **Fetch these live:** the same limits are available as JSON from [`GET /platform-limits`](../endpoints/platform-limits.md) — call it to drive validation instead of hard-coding the tables below.
## Overview
When building applications with the Publora API, it is critical to understand that **API limits often differ from native app limits**. Social media platforms impose different restrictions depending on whether content is posted through their official apps, web interfaces, or third-party APIs.
> **Note:** Publora defines 11 platform keys internally (including Pinterest), but only **10 platforms are actively supported**. Pinterest is listed for reference and is planned for a future release.
Publora validates your content against these API-specific limits before scheduling. This guide covers:
- Character limits for captions and descriptions
- Image formats, sizes, and counts
- Video duration, file size, and format requirements
- Platform-specific requirements (which platforms require media)
- Rate limits for posting frequency
- Common API error messages and validation codes
**Key Principle:** Always design your integration around the API limits documented here, not the limits you observe when posting manually through native apps.
---
## Critical API vs Native App Differences
The following table highlights the most significant differences between API and native app limits. These are the restrictions most likely to cause unexpected failures if you assume native app behavior.
| Platform | API Restriction | Native App Allows | Impact |
|----------|-----------------|-------------------|--------|
| **Twitter/X** | 2:20 (140s) video max | 2:20 (140s) video | Videos over 140s fail validation |
| **Instagram** | 15 min Reels, 10 carousel items, no animated GIF/BMP/TIFF | Platform UI may differ | Animated GIF/BMP/TIFF rejected; use JPEG, PNG, or WebP |
| **TikTok** | 10 min video, 2,200 char captions | 60 min video, 4,000 chars | Long captions truncated or rejected |
| **Facebook** | 45 min video, 2 GB files | 240 min video, 4 GB files | Large files will fail |
| **LinkedIn** | 500 MB video | 5 GB video | Videos over 500 MB will fail |
| **Telegram** | 50 MB files (Bot API) | 4 GB (user clients) | Large media uploads will fail |
---
## Character Limits
All platforms have character limits for text content. Some platforms have different limits for premium accounts or specific content types.
| Platform | Standard Limit | Premium/Special | Notes |
|----------|---------------|-----------------|-------|
| **Twitter/X** | 280 characters | 25,000 (Premium) | Threading supported for long content |
| **Instagram** | 2,200 characters | - | First 125 chars visible before "more" |
| **Threads** | 500 characters | 10,000 (text attachment) | Threading supported (500 per part); max 5 links per post |
| **TikTok** | 2,200 characters (API) | 4,000 (native app) | API enforces stricter limit |
| **LinkedIn** | 3,000 characters | - | First 210 chars visible before "see more" |
| **YouTube** | 100 (title) / 5,000 (description) | - | First 150 chars of description visible |
| **Facebook** | 63,206 characters | - | Posts under 80 chars get 66% more engagement |
| **Mastodon** | 500 characters | Instance-configurable | Some instances allow 5,000+ |
| **Bluesky** | 300 characters | - | Links count toward the limit in Publora |
| **Telegram** | 4,096 characters | 1,024 (bot caption) | Bots limited to 1,024 for media captions |
| **Pinterest** | 100 (title) / 800 (description) | 500 (ads) | **Not currently supported** -- planned for a future release |
### Character Limit Best Practices
1. **Design for the lowest common denominator** when cross-posting. If posting to Twitter and Threads, keep content under 280 characters.
2. **Use threading** for long-form content on Twitter/X and Meta Threads. Both split over-limit content into a chain instead of rejecting it.
3. **Front-load important information** since most platforms truncate visible content with a "see more" link.
---
## Image Limits
Image requirements vary significantly across platforms. Pay particular attention to each platform's format and size rules; Instagram accepts JPEG, PNG, and WebP images, with WebP auto-converted before publishing.
| Platform | Max Size | Max Count | Supported Formats |
|----------|----------|-----------|-------------------|
| **Twitter/X** | 5 MB | 4 | JPEG, PNG, GIF, WebP |
| **Instagram** | 8 MB | 10 (API carousel) | **JPEG, PNG, WebP** (WebP auto-converted) |
| **Threads** | 8 MB | 20 | JPEG, PNG, WebP |
| **TikTok** | 20 MB | 35 | JPEG, PNG, WebP |
| **LinkedIn** | 36,152,320 pixels primary gate; 50 MB ceiling | 10 (multi-image) | JPEG, PNG, GIF, WebP |
| **YouTube** | - | 0 | Video only for uploads |
| **Facebook** | 10 MB | 10 | JPEG, PNG, GIF, BMP, TIFF, WebP, AVIF, HEIF, HEIC |
| **Mastodon** | 16 MB | 4 | JPEG, PNG, GIF, WebP, HEIF, HEIC, AVIF (instance-configurable) |
| **Bluesky** | exactly 2,000,000 bytes | 4 | JPEG, PNG, WebP |
| **Telegram** | 10 MB | 10 | JPEG, PNG, GIF, WebP, BMP |
| **Pinterest** | 20 MB | 1 | JPEG, PNG — connect-only; not publishable |
### Critical Image Notes
| Issue | Platform | Details |
|-------|----------|---------|
| **Image formats** | Instagram | JPEG, PNG, and WebP are accepted (WebP is auto-converted to JPEG before publishing). Animated GIF, BMP, and TIFF are not supported. |
| **Carousel Limit** | Instagram | API carousels are limited to 10 items (native app allows 20). |
| **No Mixed Media** | Instagram | Cannot mix images and videos in the same carousel via API. |
| **Strict Size Limit** | Bluesky | Hard 2,000,000-byte decimal limit. |
| **No Organic Carousels** | LinkedIn | Organic swipeable carousels are NOT supported via API (only sponsored content). |
### Server-Side Upload Limits
The dashboard-only `/media/process-video` multipart endpoint accepts one `video` file per request and caps it at 512 MB.
Presigned API uploads do not share that dashboard multipart cap; platform limits still apply.
### Image Processing in Publora
Publora automatically handles some image conversions:
- **WebP images** are automatically converted to JPEG for platforms that do not support WebP natively.
- **Oversized images** are validated and rejected with a clear error message.
---
## Video Limits
Video restrictions through APIs are often significantly more restrictive than native apps. This is one of the most common sources of failed posts.
| Platform | Max Duration | Max Size | Supported Formats |
|----------|--------------|----------|-------------------|
| **Twitter/X (API)** | 2 min 20s (140s) | 512 MB | MP4, MOV |
| **Instagram Reels (API)** | 15 minutes (900s) | 300 MB | MP4, MOV |
| **Instagram Carousel** | 60s per video | 300 MB | MP4, MOV |
| **Threads** | 5 min | 1 GB | MP4, MOV |
| **TikTok (API)** | 10 min | 4 GB | MP4, MOV, WebM |
| **LinkedIn (API)** | 30 min | 500 MB | MP4 |
| **YouTube** | 12 hours | 256 GB | MP4, MOV, AVI, WebM |
| **Facebook (API)** | 45 min | 2 GB | MP4, MOV |
| **Mastodon** | 24 hours | ~99 MB | MP4, MOV, WebM |
| **Bluesky** | 3 min | 100 MB | MP4 |
| **Telegram (Bot API)** | 24 hours | 50 MB | MP4, MOV, AVI, MKV, WebM |
| **Pinterest** | 15 min | 2 GB | MP4, MOV — connect-only; not publishable |
*Mastodon video has a 24-hour package cap and an instance-configurable file-size limit (~99 MB default).
### Platform-Specific Video Restrictions
#### Instagram API
| Restriction | API Limit | Native App Limit |
|-------------|-----------|------------------|
| Reels duration | 15 minutes (900s) | Platform UI may differ |
| Image format | JPEG, PNG, WebP | GIF, BMP, TIFF also supported |
| Carousel items | 10 | 20 |
| Account type | Publora connects Instagram accounts through Instagram Login for Business and requests `instagram_business_basic` plus `instagram_business_content_publish`; personal accounts are unsupported. Whether Meta accepts a particular Creator account is determined by Meta, not Publora's code. | Platform UI eligibility is controlled by Meta |
| Features | No shopping tags, branded content, filters, or music | Full feature set |
#### TikTok API
| Restriction | API Limit | Native App Limit |
|-------------|-----------|------------------|
| Video duration | 10 minutes | 60 minutes |
| Caption length | 2,200 characters | 4,000 characters |
#### Facebook API
| Restriction | API Limit | Native App Limit |
|-------------|-----------|------------------|
| Video duration | 45 minutes | 240 minutes |
| File size | 2 GB | 4 GB |
| Reels posting | Pages only (not personal profiles) | Both supported |
#### LinkedIn API
| Restriction | API Limit | Native App Limit |
|-------------|-----------|------------------|
| Video file size | 500 MB | 5 GB |
| Video duration | 30 minutes | 15 minutes (API allows more) |
| Carousels | No organic carousels (sponsored only) | Supported |
| Media mixing | Cannot mix images with videos or documents | Supported |
#### Telegram Bot API
| Restriction | Standard Bot API | Local Bot API Server |
|-------------|------------------|----------------------|
| File size limit | 50 MB | 2 GB |
| Caption length | 1,024 characters | 1,024 characters |
| Premium features | Not available to bots | Not available to bots |
#### Bluesky API
| Restriction | Details |
|-------------|---------|
| Daily limit | 25 videos per day (sourced from `@publora/platform-limits`) |
| Prerequisites | Email verification required before video uploads |
---
## Platform Requirements
Different platforms have different requirements for media. Some platforms are text-only capable, while others require media for every post.
| Platform | Requires Media | Requires Video | Supports Text-Only | Supports Threading |
|----------|----------------|----------------|--------------------|--------------------|
| **Twitter/X** | No | No | Yes | Yes |
| **Instagram** | Yes | No | No | No |
| **Threads** | No | No | Yes | Yes |
| **TikTok** | Yes | No | No | No |
| **LinkedIn** | No | No | Yes | No |
| **YouTube** | Yes | Yes | No | No |
| **Facebook** | No | No | Yes | No |
| **Mastodon** | No | No | Yes | No |
| **Bluesky** | No | No | Yes | No |
| **Telegram** | No | No | Yes | No |
| **Pinterest** | Yes | No | No | No — not currently supported |
### Media Requirement Notes
- **TikTok** requires media and supports image carousels or video; **YouTube** requires video. Neither supports text-only publication.
- **Instagram** requires at least one image or video with every post.
- **Pinterest** is listed for reference but is **not currently supported** in Publora. Support is planned for a future release.
- **Threading** is available for Twitter/X and Meta Threads.
---
## Rate Limits
Platform-side posting quotas are advisory, account-dependent, and may change without notice; they are not a Publora contract. Unsourced and conflicting posts-per-hour/day numbers are intentionally omitted.
Publora itself enforces plan entitlements and the media-URL ingestion limit (60 URLs per fixed one-hour window, returned as `429 MEDIA_URL_RATE_LIMITED` with `Retry-After`).
### Rate Limit Best Practices
1. **Space out posts** rather than bulk-posting at the same time.
2. **Implement exponential backoff** when you receive rate limit errors.
3. **Track your posting frequency** per platform to stay within limits.
4. **Treat platform failures explicitly**; do not assume automatic retry or redistribution.
---
## Common API Error Messages
When posts fail, the platform returns specific error messages. Understanding these errors helps you diagnose and fix issues quickly.
### Instagram Errors
| Error | Meaning | Resolution |
|-------|---------|------------|
| `(#10) The user is not an Instagram Business` | Meta rejected the connected account for this operation | Reconnect an eligible professional account through Instagram Login for Business |
| `Error 2207010` | Caption limit exceeded | Reduce caption to under 2,200 characters |
| `Error 2207004` | Image exceeds 8 MB | Compress image to under 8 MB |
| `Error 9, Subcode 2207042` | Publishing rate limit reached | Wait before posting again |
### TikTok Errors
| Error | Meaning | Resolution |
|-------|---------|------------|
| `spam_risk_too_many_posts` | Daily post limit reached | Wait 24 hours before posting again |
| `duration_check_failed` | Video must be 3s-10min | Adjust video duration |
### Twitter/X Errors
| Error | Meaning | Resolution |
|-------|---------|------------|
| `This user is not allowed to post a video longer than 2 minutes` | X rejected the upload for its own duration/account rules; Publora's package limit is 140 seconds (2:20) | Keep the video at or below 140 seconds; if X still rejects it, surface the platform error without assuming an account tier |
### Facebook Errors
| Error | Meaning | Resolution |
|-------|---------|------------|
| `Error 1363026` | Video exceeds 40 min duration | Trim video to under 45 minutes |
| `Error 1363023` | File size exceeds 2 GB | Compress video to under 2 GB |
| `Error 1363128` | Reels duration outside 3-90 second range | Adjust Reel to 3-90 seconds |
### LinkedIn Errors
| Error | Meaning | Resolution |
|-------|---------|------------|
| `MEDIA_ASSET_PROCESSING_FAILED` | File too large or unsupported format | Check file size (<500 MB) and format (MP4) |
| `Error 429` | Rate limit exceeded | Wait and retry with backoff |
### Telegram Errors
| Error | Meaning | Resolution |
|-------|---------|------------|
| `MEDIA_CAPTION_TOO_LONG` | Caption exceeds 1024 chars (bots) | Reduce caption length |
| `Bad Request: file is too big` | File exceeds 50 MB | Compress file to under 50 MB |
### Bluesky Errors
| Error | Meaning | Resolution |
|-------|---------|------------|
| `429 Too Many Requests` | Rate limit exceeded | Wait and retry |
| Video job state `JOB_STATE_FAILED` | Video processing failed | Check video format and size |
---
## Validation Error Codes
The Publora validation system returns standardized error codes when content does not meet platform requirements. Use these codes to provide clear feedback to users.
### Content Errors
| Error Code | Description |
|------------|-------------|
| `CONTENT_TOO_LONG` | Content exceeds the platform's character limit |
| `CONTENT_TOO_SHORT` | Content is below the minimum required length |
| `CONTENT_REQUIRED` | Text content is required for this platform |
| `CONTENT_OR_MEDIA_REQUIRED` | Either text content or media is required |
### Media Errors
| Error Code | Description |
|------------|-------------|
| `MEDIA_REQUIRED` | Platform requires at least one media file |
| `MEDIA_SIZE_EXCEEDED` | File size exceeds the platform limit |
| `MEDIA_COUNT_EXCEEDED` | Too many media files attached |
| `MEDIA_TYPE_NOT_SUPPORTED` | File format is not supported by the platform |
| `MEDIA_DIMENSIONS_INVALID` | Image dimensions are outside the allowed range |
### Video Errors
| Error Code | Description |
|------------|-------------|
| `VIDEO_REQUIRED` | Platform requires a video (YouTube) |
| `VIDEO_DURATION_EXCEEDED` | Video duration exceeds the platform limit |
| `VIDEO_DURATION_TOO_SHORT` | Video is shorter than the minimum required duration |
| `VIDEO_NOT_SUPPORTED` | Platform does not support video content |
| `IMAGES_NOT_SUPPORTED` | Platform does not accept images (for example, YouTube) |
### Platform Errors
| Error Code | Description |
|------------|-------------|
| `PLATFORM_NOT_SUPPORTED` | Unknown or unsupported platform identifier |
| `PLATFORM_SETTING_REQUIRED` | A required platform-specific setting is missing |
| `PLATFORM_SETTING_INVALID` | A platform-specific setting has an invalid value |
---
---
## Sources
Official platform documentation used to compile these limits:
- [Twitter/X Developer Community](https://devcommunity.x.com/t/unable-to-post-videos-longer-than-2-minutes-via-post-2-tweets/248440)
- [Instagram Graph API - Content Publishing](https://developers.facebook.com/docs/instagram-platform/content-publishing/)
- [TikTok Content Posting API](https://developers.tiktok.com/doc/content-posting-api-reference-direct-post)
- [LinkedIn Videos API](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/videos-api)
- [Facebook Graph API](https://developers.facebook.com/docs/graph-api/)
- [Threads API](https://developers.facebook.com/docs/threads/)
- [Bluesky AT Protocol Docs](https://docs.bsky.app/)
- [Telegram Bot API](https://core.telegram.org/bots/api)
- [Mastodon API Documentation](https://docs.joinmastodon.org/api/)
- [Pinterest API v5](https://developers.pinterest.com/docs/api/v5/)
- [YouTube Data API v3](https://developers.google.com/youtube/v3/)
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) -- the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/validation
# Post Validation
This guide covers how Publora validates posts before scheduling to prevent publish failures, including what gets validated, the validation response format, error codes, and best practices for avoiding validation errors.
## Overview
Posts are validated before scheduling to catch issues that would cause publishing failures on target platforms. Each social media platform has unique requirements for content length, media types, file sizes, and video durations. Publora validates your posts against these platform-specific limits and returns detailed error information so you can fix issues before scheduling.
Full validation runs at the scheduling gate. A REST `create-post` request is fully validated when it creates a scheduled post; a draft is validated when `update-post` changes it to `scheduled`.
## When Validation Occurs
Validation runs automatically on these API calls:
| Endpoint | Trigger |
|---|---|
| Dashboard update to `scheduled` status | When changing a post's status to `scheduled` in the dashboard |
| `POST /api/v1/create-post` | When `scheduledTime` makes the new post scheduled |
| `PUT /api/v1/update-post/:id` | When scheduling the post; media URLs are finalized before validation |
> **Note:** `PUT /api/v1/update-post/:id` accepts `content`, `platforms`, `status`, `scheduledTime`, `platformSettings`, and `mediaUrls`; it also supports the `Idempotency-Key` header. Scheduling re-runs validation and media finalization, and adding a target to a scheduled post re-runs scheduling limits plus full content/media validation.
If validation fails with blocking errors, the API returns a `400` status code with details about what needs to be fixed. Warnings are returned but do not block the operation.
## What Gets Validated
### Content Length
Each platform has a maximum character limit. Some platforms also have minimum requirements.
| Platform | Max Characters | Notes |
|---|---|---|
| **Twitter/X** | 280 (standard) / 25,000 (Premium) | Threading supported for long content |
| **Instagram** | 2,200 | First 125 chars visible before "more" |
| **Threads** | 500 (10,000 with text attachment) | Threading supported: 500 per part. Max 5 links per post |
| **TikTok** | 2,200 (API) | Native app allows 4,000 |
| **LinkedIn** | 3,000 | First 210 chars visible before "see more" |
| **YouTube** | 100 (title) / 5,000 (description) | First 150 chars of description visible |
| **Facebook** | 63,206 | Posts under 80 chars get higher engagement |
| **Mastodon** | 500 | Instance-configurable (some allow 5,000+) |
| **Bluesky** | 300 | Links count toward the limit in Publora |
| **Telegram** | 4,096 (users) / 1,024 (bot captions) | Bots limited to 1,024 for captions |
| **Pinterest** | 100 (title) / 800 (description) | Optimal description: 220-232 chars. *Pinterest is in the platform registry but publishing support is not yet fully available/tested.* |
### Media Requirements
Some platforms require media, while others support text-only posts.
| Platform | Requires Media | Requires Video | Supports Text-Only |
|---|---|---|---|
| **Twitter/X** | No | No | Yes |
| **Instagram** | Yes | No | No |
| **Threads** | No | No | Yes |
| **TikTok** | Yes | No | No |
| **LinkedIn** | No | No | Yes |
| **YouTube** | Yes | Yes | No |
| **Facebook** | No | No | Yes |
| **Mastodon** | No | No | Yes |
| **Bluesky** | No | No | Yes |
| **Telegram** | No | No | Yes |
| **Pinterest** | Yes | No | No |
### Media File Sizes
| Platform | Max Image Size | Max Video Size | Max Media Count |
|---|---|---|---|
| **Twitter/X** | 5 MB | 512 MB | 4 images OR 1 video |
| **Instagram** | 8 MB | 300 MB | 10 (API carousel) |
| **Threads** | 8 MB | 1 GB | 20 images OR 1 video |
| **TikTok** | 20 MB | 4 GB | 35 images OR 1 video |
| **LinkedIn** | 36,152,320 pixels primary gate; 50 MB ceiling | 500 MB | 10 images OR 1 video |
| **YouTube** | - | 256 GB | 1 video only |
| **Facebook** | 10 MB | 2 GB (API) | 10 images OR 1 video |
| **Mastodon** | 16 MB | ~99 MB | 4 |
| **Bluesky** | exactly 2,000,000 bytes | 100 MB | 4 |
| **Telegram** | 10 MB | 50 MB (Bot API) | 10 |
| **Pinterest** | 20 MB | 2 GB | 1 image OR 1 video (connect-only; not publishable) |
### Media Formats
| Platform | Supported Image Formats | Supported Video Formats |
|---|---|---|
| **Twitter/X** | JPEG, PNG, GIF, WebP | MP4, MOV |
| **Instagram** | JPEG, PNG, WebP (WebP auto-converted) | MP4, MOV |
| **Threads** | JPEG, PNG, WebP | MP4, MOV |
| **TikTok** | JPEG, PNG, WebP | MP4, MOV, WebM |
| **LinkedIn** | JPEG, PNG, GIF, WebP | MP4 |
| **YouTube** | - | MP4, MOV, AVI, WebM |
| **Facebook** | JPEG, PNG, GIF, BMP, TIFF, WebP, AVIF, HEIF, HEIC | MP4, MOV |
| **Mastodon** | JPEG, PNG, GIF, WebP, HEIF, HEIC, AVIF | MP4, MOV, WebM |
| **Bluesky** | JPEG, PNG, WebP | MP4 |
| **Telegram** | JPEG, PNG, GIF, WebP, BMP | MP4, MOV, AVI, MKV, WebM |
| **Pinterest** | JPEG, PNG | MP4, MOV |
> **Note:** Instagram accepts JPEG, PNG, and WebP images (WebP is auto-converted to JPEG before publishing). Animated GIF, BMP, and TIFF will fail validation.
### Video Duration Limits
| Platform | Min Duration | Max Duration (API) | Notes |
|---|---|---|---|
| **Twitter/X** | 0.5s | 2 min 20s (140s) | Package-enforced API limit |
| **Instagram Reels** | 3s | 15 min (900s) | Feed video: 60 min; carousel: 60s |
| **Instagram Carousel** | 3s | 60s per video | - |
| **Threads** | - | 5 min | - |
| **TikTok** | 3 seconds | 10 min | Native allows 60 min |
| **LinkedIn** | 3s | 30 min | - |
| **YouTube** | - | 12 hours | - |
| **Facebook** | - | 45 min | Native allows 240 min |
| **Mastodon** | - | 24 hours | Package limit: 86,400 seconds |
| **Bluesky** | - | 3 min | Package-sourced daily limit: 25 videos |
| **Telegram** | - | 24 hours | Limited by 50 MB file size |
| **Pinterest** | 4s | 15 min | - |
## Validation Response Format
> **Note:** Scheduled `create-post` and scheduling `update-post` requests run the validation service and may return the structured response below. Draft creation does not pass through the scheduling gate.
When validation errors occur, the API returns a `400` status code with a structured response:
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "instagram",
"code": "MEDIA_REQUIRED",
"message": "Instagram posts require media",
"field": "media",
"severity": "error"
},
{
"platform": "tiktok",
"code": "MEDIA_REQUIRED",
"message": "TikTok posts require media",
"field": "media",
"severity": "error"
}
],
"warnings": [
{
"platform": "twitter",
"code": "CONTENT_TOO_LONG",
"message": "Content exceeds Twitter/X's 280 character limit (currently 450)",
"field": "content",
"severity": "warning",
"constraint": "maxLength",
"currentValue": 450
}
],
"summary": {
"affectedPlatforms": ["instagram", "tiktok", "twitter"],
"errorCount": 2,
"warningCount": 1
}
}
}
```
### Response Fields
| Field | Type | Description |
|---|---|---|
| `valid` | boolean | `true` if all platforms pass validation, `false` otherwise |
| `errors` | array | Blocking errors that must be fixed before scheduling |
| `warnings` | array | Non-blocking issues that may affect publishing |
| `summary.affectedPlatforms` | array | List of platform names with errors or warnings |
| `summary.errorCount` | number | Total number of errors |
| `summary.warningCount` | number | Total number of warnings |
### Error/Warning Object Fields
| Field | Type | Description |
|---|---|---|
| `platform` | string | Platform name (e.g., "twitter", "instagram") |
| `code` | string | Machine-readable error code |
| `message` | string | Human-readable error description |
| `field` | string | The field that caused the error (e.g., "content", "imageSize", "videoSize", "imageFormat", "videoDuration", "video", "settings") |
| `severity` | string | Either `"error"` (blocking) or `"warning"` (non-blocking) |
| `constraint` | string | (optional) String descriptor of the violated constraint (e.g., `"maxLength"`, `"maxCount"`, `"maxSize"`, `"maxDuration"`, `"requiredType"`) |
| `currentValue` | number/string | (optional) The current value that exceeded the constraint |
| `maxValue` | number/string | (optional) The maximum allowed value |
| `minValue` | number/string | (optional) The minimum required value |
| `suggestions` | string[] | (optional) Suggested fixes or alternative actions |
## Error Codes Reference
### Content Errors
| Code | Description | Resolution |
|---|---|---|
| `CONTENT_TOO_LONG` | Content exceeds the platform's character limit | Shorten the content or use threading where supported. **Note:** on Twitter/X and Meta Threads over-limit content is not an error at all — it is accepted and split into a chain. A successful response carries no `validation` object, so there is nothing to inspect; the split simply happens. On platforms without threading this stays a blocking **error**. |
| `CONTENT_TOO_SHORT` | Content is below the minimum required length | Add more content |
| `CONTENT_REQUIRED` *(reserved — not currently emitted)* | Text content is required but missing | Add text content to the post |
| `CONTENT_OR_MEDIA_REQUIRED` | Either text or media is needed | Add content or attach media |
| `THREAD_PART_TOO_LONG` | A single thread part exceeds the platform's per-part character limit (500 on Threads) | Shorten that part; `field` identifies its index. Only parts authored in the web app can trigger this — parts the API splits automatically are within the limit by construction |
| `INVALID_PLATFORM_CONTENT` | Content contains elements not supported by the platform | Remove unsupported content elements. (This error code is defined in the codebase but not currently emitted by the validation service.) |
### Media Errors
| Code | Description | Resolution |
|---|---|---|
| `MEDIA_REQUIRED` | Platform requires at least one media file | Attach an image or video |
| `MEDIA_SIZE_EXCEEDED` | File exceeds the platform's size limit | Compress or resize the file |
| `MEDIA_COUNT_EXCEEDED` | Too many media files attached | Reduce the number of files |
| `MEDIA_TYPE_NOT_SUPPORTED` | File format not supported by the platform | Convert to a supported format |
| `MEDIA_DIMENSIONS_INVALID` | Image dimensions outside allowed range | Resize the image |
| `MEDIA_ASPECT_RATIO_INVALID` | Media aspect ratio is outside a platform's hard range | Crop or re-encode within the documented range |
| `IMAGES_NOT_SUPPORTED` | Platform does not accept attached images (for example, YouTube) | Use a video instead |
| `DOCUMENTS_NOT_SUPPORTED` | Target does not support an attached PDF/document | Remove the document or target LinkedIn |
### Video Errors
| Code | Description | Resolution |
|---|---|---|
| `VIDEO_REQUIRED` | Platform requires a video (YouTube) | Attach a video file |
| `VIDEO_DURATION_EXCEEDED` | Video is longer than the platform allows | Trim the video to meet the limit |
| `VIDEO_DURATION_TOO_SHORT` | Video is shorter than the minimum required | Use a longer video (min 3s for TikTok/FB Reels) |
| `VIDEO_NOT_SUPPORTED` *(reserved — not currently emitted)* | Platform does not support video | Remove the video or change target platforms |
### Platform Errors
| Code | Description | Resolution |
|---|---|---|
| `PLATFORM_NOT_SUPPORTED` | Unknown or unsupported platform | Check the platform ID format |
| `PLATFORM_SETTING_REQUIRED` | A required platform-specific setting is missing | Provide the required setting |
| `PLATFORM_SETTING_INVALID` | A platform-specific setting has an invalid value | Correct the setting value |
### System Errors
| Code | Description | Resolution |
|---|---|---|
| `VALIDATION_SYSTEM_ERROR` | An internal error occurred during validation | Retry the request; if persistent, contact support |
## Examples
### Validation Error: Missing Media for Instagram
When posting to Instagram without media:
**Request:**
```json
{
"content": "Check out our latest update!",
"platforms": ["twitter-123", "instagram-456"]
}
```
**Response (400):**
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "instagram",
"code": "MEDIA_REQUIRED",
"message": "Instagram posts require media",
"field": "media",
"severity": "error"
}
],
"warnings": [],
"summary": {
"affectedPlatforms": ["instagram"],
"errorCount": 1,
"warningCount": 0
}
}
}
```
### Validation Error: Video Required for YouTube
When scheduling YouTube with an image instead of a required video:
**Request:**
```json
{
"content": "New product announcement!",
"platforms": ["youtube-789"],
"mediaUrls": ["https://example.com/photo.jpg"],
"scheduledTime": ""
}
```
**Response (400):**
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "youtube",
"code": "VIDEO_REQUIRED",
"message": "YouTube requires a video",
"field": "video",
"severity": "error"
},
{
"platform": "youtube",
"code": "IMAGES_NOT_SUPPORTED",
"message": "YouTube does not support image posts",
"field": "media",
"severity": "error"
}
],
"warnings": [],
"summary": {
"affectedPlatforms": ["youtube"],
"errorCount": 2,
"warningCount": 0
}
}
}
```
### Validation Error: Content Too Long
When content exceeds Twitter's 280 character limit:
> **Threading note:** Twitter/X and Meta Threads do not raise this error — over-limit content is accepted and split into a chain. The example below is a platform without threading.
**Response (400):**
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "twitter",
"code": "CONTENT_TOO_LONG",
"message": "Content exceeds Twitter/X's 280 character limit (currently 450)",
"field": "content",
"severity": "error"
}
],
"warnings": [],
"summary": {
"affectedPlatforms": ["twitter"],
"errorCount": 1,
"warningCount": 0
}
}
}
```
### Validation Error: Image Format Not Supported
When uploading an animated GIF to Instagram (only JPEG, PNG, and WebP are supported):
**Response (400):**
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "instagram",
"code": "MEDIA_TYPE_NOT_SUPPORTED",
"message": "Image format \"image/gif\" is not supported on Instagram",
"field": "imageFormat",
"severity": "error"
}
],
"warnings": [],
"summary": {
"affectedPlatforms": ["instagram"],
"errorCount": 1,
"warningCount": 0
}
}
}
```
### Validation Error: Video Duration Exceeded
When a video exceeds platform limits:
**Response (400):**
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "instagram",
"code": "VIDEO_DURATION_EXCEEDED",
"message": "Video duration (3m 0s) exceeds Instagram's 60s carousel limit",
"field": "videoDuration",
"severity": "error"
},
{
"platform": "twitter",
"code": "VIDEO_DURATION_EXCEEDED",
"message": "Video duration (3m 0s) exceeds Twitter/X's 2m 20s limit",
"field": "videoDuration",
"severity": "error"
}
],
"warnings": [],
"summary": {
"affectedPlatforms": ["instagram", "twitter"],
"errorCount": 2,
"warningCount": 0
}
}
}
```
### Validation Error: File Size Exceeded
When an image exceeds Bluesky's strict 2,000,000-byte limit:
**Response (400):**
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "bluesky",
"code": "MEDIA_SIZE_EXCEEDED",
"message": "Image (2.5MB) exceeds Bluesky's 1.9MB limit",
"field": "imageSize",
"severity": "error"
}
],
"warnings": [],
"summary": {
"affectedPlatforms": ["bluesky"],
"errorCount": 1,
"warningCount": 0
}
}
}
```
### Multiple Platform Errors
When a single post has issues on multiple platforms:
**Response (400):**
```json
{
"error": "Validation failed",
"validation": {
"valid": false,
"errors": [
{
"platform": "instagram",
"code": "MEDIA_TYPE_NOT_SUPPORTED",
"message": "Image format \"image/gif\" is not supported on Instagram",
"field": "imageFormat",
"severity": "error"
},
{
"platform": "bluesky",
"code": "MEDIA_SIZE_EXCEEDED",
"message": "Image (2.5MB) exceeds Bluesky's 1.9MB limit",
"field": "imageSize",
"severity": "error"
},
{
"platform": "tiktok",
"code": "MEDIA_REQUIRED",
"message": "TikTok posts require media",
"field": "media",
"severity": "error"
}
],
"warnings": [],
"summary": {
"affectedPlatforms": ["instagram", "bluesky", "tiktok"],
"errorCount": 3,
"warningCount": 0
}
}
}
```
## Best Practices
1. **Validate content length client-side.** Check character counts before sending the API request. Different platforms have different limits (Twitter: 280, LinkedIn: 3,000, Bluesky: 300).
2. **Use supported Instagram image formats.** Instagram accepts JPEG, PNG, and WebP images; WebP is auto-converted before publishing. GIF is not supported for Instagram image posts.
3. **Compress images for Bluesky.** Bluesky has a strict 2,000,000-byte decimal limit.
4. **Check video durations before uploading.** Instagram Reels max out at 15 minutes (900s), feed videos at 60 minutes, carousel videos at 60 seconds, Twitter at 140 seconds, and TikTok at 10 minutes.
5. **Use separate media for different platform groups.** If posting to both image and video platforms, consider creating separate posts:
- Image posts for Instagram, Twitter, LinkedIn
- Video posts for TikTok, YouTube
6. **Handle validation errors gracefully in your UI.** Display platform-specific error messages so users know exactly what to fix.
7. **Consider platform requirements when designing content.** TikTok accepts a JPEG/PNG/WebP photo carousel of up to 35 images or one video. Instagram requires supported image or video media.
8. **For Telegram bots, keep captions under 1,024 characters.** Bots cannot exceed this limit even though users can send 4,096 characters.
9. **Test video FPS for TikTok.** TikTok has minimum FPS requirements. Videos with very low frame rates will fail at publish time.
## Common Issues
| Problem | Cause | Solution |
|---|---|---|
| Instagram post fails with `MEDIA_TYPE_NOT_SUPPORTED` | Using an unsupported image format, such as GIF | Use JPEG, PNG, or WebP images |
| TikTok post fails with `MEDIA_REQUIRED` | No image carousel or video attached | Attach supported image or video media |
| Bluesky post fails with `MEDIA_SIZE_EXCEEDED` | Image over 2,000,000 bytes | Compress below the decimal byte limit |
| Twitter post fails with `CONTENT_TOO_LONG` | Content exceeds the connected account's applicable limit | Shorten content or use threading |
| Instagram Reels fails with `VIDEO_DURATION_EXCEEDED` | Video over 15 minutes | Trim video to 900 seconds or less |
| Multiple platforms fail with different errors | Content not optimized for all targets | Create platform-specific posts or fix each error |
| Validation passes but publish fails | Platform-side issues (rate limits, account restrictions) | Check platform-specific error messages in the post status |
---
*[Publora](https://publora.com) is built by [Creative Content Crafts, Inc.](https://cccrafts.ai) Need AI-powered content creation for LinkedIn, Threads, and X? Try [Co.Actor](https://co.actor) -- the best AI service for authentic thought leadership at scale.*
---
> Source: https://docs.publora.com/guides/threading
# Threading Guide - Post Multi-Part Threads via API
Learn how to post connected threads to Twitter/X and Meta Threads. Both platforms accept one `content` field and publish it as a chain of connected posts.
> **Threads needs one permission.** A Threads chain requires `threads_manage_replies` on the connection. Publora checks the grant when you schedule (from a per-connection cache up to five minutes old) and re-checks it against Meta immediately before publishing, so a missing permission fails the post outright rather than half-publishing it. Reconnect the account in Publora **Channels** to grant it. Single Threads posts are unaffected.
## What is a Thread?
A thread is a series of connected posts that appear as a single conversation. On X/Twitter, these are called "tweet threads" or "tweetstorms." On Threads (by Meta), they appear as connected replies to your own posts. Publora publishes both from a single `content` field.
### Keywords: post thread API, Twitter thread API, Threads multi-post API, tweet thread programmatically, create thread API, multi-tweet API, thread posting automation, social media thread API
## Quick Start
Post a thread by simply providing content that exceeds the platform's character limit:
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `This is a long post that will be automatically split into multiple parts.
When X/Twitter content exceeds the applicable account limit, Publora can automatically create a thread.
Each part is posted as a reply to the previous one, creating a connected conversation that your followers can read through.`,
platforms: ['twitter-123']
})
});
```
Publora will:
1. Detect content exceeds the limit
2. Split at natural break points (paragraphs, sentences)
3. Post each part as a reply to the previous
4. Return the head post ID
## How Threading Works
### Automatic Thread Creation
When your content exceeds platform limits, Publora automatically:
1. **Splits content intelligently:**
- First tries paragraph breaks (`\n\n`)
- Falls back to sentence endings (`. `, `! `, `? `)
- Falls back to word boundaries
- Hard splits only as last resort
2. **Posts sequentially:**
- First post published normally
- Each subsequent post replies to the previous
- Uses `in_reply_to_tweet_id` on X and `reply_to_id` on Threads
3. **Adds numbering to automatic splits:**
- Appends ` (1/N)`, ` (2/N)`, etc. to each part, on X and on Threads
- Reserves 10 characters of the per-part budget for the marker
- Applies **only** when Publora did the splitting. Parts you separate yourself with `---` or `[n/m]` are published exactly as written
### Platform Limits
| Platform | Character Limit | Thread Numbering |
|----------|----------------|------------------|
| X/Twitter (Standard) | 280 | Yes `(1/N)` on automatic splits |
| X/Twitter (Premium) | 25,000 | Yes `(1/N)` on automatic splits |
| Threads | 500 per part | Yes `(1/N)` on automatic splits |
Emoji and other astral characters count as **2** toward these limits.
## Manual Thread Control
### Method 1: Triple Dash Separator
Use `---` to explicitly define where thread breaks should occur:
```javascript
const content = `First part of my thread - the hook that grabs attention.
---
Second part with the main content and details.
---
Final part with the call to action!`;
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content,
platforms: ['twitter-123']
})
});
```
### Method 2: Explicit Markers
Use `[n/m]` markers to define parts:
```javascript
const content = `The hook that grabs attention [1/3]
The main content with all the details you want to share [2/3]
The conclusion with a call to action! [3/3]`;
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content,
platforms: ['twitter-123']
})
});
```
When explicit markers are detected:
- Publora preserves them exactly as written
- Content is split at marker positions
- No additional numbering is added
> **Note:** The `[n/m]` explicit marker and `---` separator behavior is handled by the content splitting service and cannot be independently verified from the core backend source. Thread numbering reserves approximately 10 characters for the `(n/m)` marker when calculating available space per part.
## Media in Threads
Media (images, videos) are attached to the **first post only**. Use the standard upload workflow: create draft, upload media, then schedule.
```javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.publora.com/api/v1';
// Step 1: Create draft post (no scheduledTime)
const postResponse = await fetch(`${BASE_URL}/create-post`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
content: `Check out these results from our latest experiment!
---
The methodology was straightforward but the results surprised us.
---
What do you think? Drop your thoughts below!`,
platforms: ['twitter-123']
// No scheduledTime = draft
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Get pre-signed upload URL
const urlResponse = await fetch(`${BASE_URL}/get-upload-url`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
fileName: 'experiment-results.jpg',
contentType: 'image/jpeg',
type: 'image',
postGroupId
})
});
const { uploadUrl, fileUrl } = await urlResponse.json();
// Step 3: Upload file to S3
const fileBuffer = await fs.promises.readFile('./experiment-results.jpg');
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: fileBuffer
});
console.log(`Uploaded: ${fileUrl}`);
// Step 4: Schedule the thread
await fetch(`${BASE_URL}/update-post/${postGroupId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-publora-key': API_KEY
},
body: JSON.stringify({
status: 'scheduled',
scheduledTime: '2026-03-01T14:00:00.000Z'
})
});
```
### Media Limits per Platform
| Platform | Images | Video | Notes |
|----------|--------|-------|-------|
| X/Twitter | Up to 4 | 1 | Cannot mix images and video |
| Threads | Up to 20 images | 1 | WebP auto-converted. A chain's first part keeps each carousel item's own type, so a mixed image/video carousel is possible there |
## Cross-Platform Threading
Post the same thread to multiple platforms simultaneously:
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `A long piece of content that will become a thread...`,
platforms: ['twitter-123']
})
});
```
Publora handles platform differences:
- X/Twitter: 280 char limit, adds `(1/N)` markers to automatic splits
- Threads: 500 characters per part, same `(1/N)` markers on automatic splits, and the chain needs `threads_manage_replies`
## Scheduling Threads
Schedule a thread for future publication:
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `Your long-form thread content here...`,
platforms: ['twitter-123'],
scheduledTime: '2026-03-15T14:30:00.000Z'
})
});
```
## Error Handling
### Partial Thread Failures
Publora stores one `ScheduledPost` per platform target, not one row per thread part — but `get-post` does report per-part progress in `threadParts[]`. If a platform publishes some parts and then fails, the target is marked failed with `THREAD_PARTIALLY_PUBLISHED`, `postedId` preserves the first part's ID, and each part carries its own `status` and `publishedId`. A group containing only that target is therefore `failed`; a multi-target group can be `partially_published` when another target succeeds.
```json
{
"success": true,
"postGroupId": "664f1a2b3c4d5e6f7a8b9c0d",
"status": "failed",
"scheduledTime": "2026-03-15T14:30:00.000Z",
"platformSettings": {},
"platforms": ["twitter-123"],
"posts": [
{
"platform": "twitter",
"platformId": "123",
"content": "Original long thread content",
"status": "failed",
"postedId": "1234567890",
"permalink": null,
"isThread": true,
"threadParts": [
{ "index": 0, "content": "Part one (1/3)", "status": "published", "publishedId": "1234567890" },
{ "index": 1, "content": "Part two (2/3)", "status": "published", "publishedId": "1234567891" },
{ "index": 2, "content": "Part three (3/3)", "status": "failed", "publishedId": null }
],
"error": { "code": "THREAD_PARTIALLY_PUBLISHED", "message": "Twitter thread partially published (2/3): Rate limit exceeded", "failedAt": "2026-03-15T14:01:12.000Z", "retryable": false }
}
],
"media": []
}
```
Already-published parts **are** live. Read `threadParts[]` to see exactly which ones: an entry with `status: "published"` and a `publishedId` exists on the platform. A partially published chain is terminal and non-retryable, so Publora does not re-run it; on Threads a re-entry guard additionally refuses any chain that already has published parts. Publish only the missing parts yourself — recreating the whole post duplicates the ones that already landed.
A third outcome is `PUBLISH_OUTCOME_UNKNOWN`: the platform accepted a publish request but returned no ID, so Publora cannot tell whether that part went out. Automatic retry is disabled for this case by design. Check the live account before sending anything else.
### Rate Limits
Platform-side quotas and pricing change independently and are not a Publora numeric contract. Publora imposes no cap on the number of parts in a chain.
## Best Practices
1. **Keep threads focused** - Each thread should have one main topic
2. **Hook in first post** - The first post should grab attention
3. **Natural breaks** - Use paragraphs to help automatic splitting
4. **Preview before posting** - Long threads are hard to edit once live
5. **Consider your audience** - Some followers prefer single posts over threads
## API Response
The `create-post` endpoint returns the post group reference and effective schedule time, not individual thread parts:
```json
{
"success": true,
"postGroupId": "664f1a2b3c4d5e6f7a8b9c0d",
"scheduledTime": null
}
```
`GET /api/v1/get-post/:postGroupId` returns one entry per connection target, with the stored original content, the target status, and the per-part breakdown:
```json
{
"success": true,
"postGroupId": "664f1a2b3c4d5e6f7a8b9c0d",
"status": "published",
"scheduledTime": "2026-03-15T14:30:00.000Z",
"platformSettings": {},
"platforms": ["twitter-123"],
"posts": [
{
"platform": "twitter",
"platformId": "123",
"content": "Original long thread content",
"status": "published",
"postedId": "1234567890",
"permalink": null,
"isThread": true,
"threadParts": [
{ "index": 0, "content": "Part one (1/2)", "status": "published", "publishedId": "1234567890" },
{ "index": 1, "content": "Part two (2/2)", "status": "published", "publishedId": "1234567891" }
]
}
],
"media": []
}
```
`postedId` is the **first** part's platform ID, identical to `threadParts[0].publishedId`; the remaining IDs are in `threadParts[]`. No single ID addresses the whole chain. `list-posts` omits `threadParts`, so fetch the group to read chain progress.
## Related Guides
- [X/Twitter Platform Guide](../platforms/x-twitter.md)
- [Threads Platform Guide](../platforms/threads.md)
- [Scheduling Posts](./scheduling.md)
- [Media Uploads](./media-uploads.md)
---
*[Publora](https://publora.com) - Post threads to X/Twitter and Meta Threads via a simple REST API.*
---
> Source: https://docs.publora.com/guides/twitter-threads
# Post Twitter Threads via API - Tweet Thread Automation
Post tweet threads (tweetstorms) to X/Twitter programmatically using the Publora REST API. A simpler alternative to manually chaining tweets with the Twitter API v2.
## Twitter Thread API Overview
Creating a Twitter thread traditionally requires:
1. Posting the first tweet
2. Capturing the tweet ID
3. Posting each subsequent tweet as a reply using `in_reply_to_tweet_id`
4. Handling errors and partial failures
Publora handles all of this automatically with a single API call.
### Keywords: Twitter thread API, tweet thread API, post tweetstorm API, Twitter API thread, X API thread, multi-tweet API, tweet chain API, create Twitter thread programmatically, automate tweet threads, Twitter thread automation, post multiple tweets API
## Quick Example
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `I've been building in public for 6 months. Here's everything I learned.
First, consistency beats intensity. Posting daily, even small updates, builds more momentum than sporadic big announcements.
Second, share your failures. People connect more with struggles than successes. My most engaging posts were about things that went wrong.
Third, engage genuinely. Reply to comments, ask questions, be curious about others' work. The algorithm rewards conversations.
Finally, don't chase vanity metrics. Focus on connecting with the right people, not the most people.`,
platforms: ['twitter-123456']
})
});
const data = await response.json();
console.log('Thread posted:', data);
```
This will automatically:
- Split into 4+ tweets at sentence boundaries
- Add `(1/N)` numbering to each tweet
- Post each as a reply to the previous
- Return the Publora post-group ID; per-part tweet IDs are then readable from `get-post`
## How Twitter Threads Work
### The Official Twitter API v2 Way
With the official Twitter API, creating a thread requires multiple sequential requests:
```javascript
// Step 1: Post first tweet
const tweet1 = await client.v2.tweet({ text: "First tweet (1/3)" });
// Step 2: Post reply to first tweet
const tweet2 = await client.v2.tweet({
text: "Second tweet (2/3)",
reply: { in_reply_to_tweet_id: tweet1.data.id }
});
// Step 3: Post reply to second tweet
const tweet3 = await client.v2.tweet({
text: "Third tweet (3/3)",
reply: { in_reply_to_tweet_id: tweet2.data.id }
});
```
### The Publora Way
```javascript
// Single request - Publora handles everything
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: "First tweet\n\n---\n\nSecond tweet\n\n---\n\nThird tweet",
platforms: ['twitter-123456']
})
});
```
## Thread Formatting Options
### Automatic Splitting
Content over the connected account's applicable limit (280 standard / 25,000 Premium or PremiumPlus) is automatically split:
- At paragraph breaks (`\n\n`) first
- At sentence endings (`. `, `! `, `? `) second
- At word boundaries as fallback
- `(1/N)` markers added automatically
### Manual Thread Parts with `---`
```javascript
const content = `Hook: Why most developers fail at Twitter.
---
Mistake #1: They only share finished work. Share the process, the bugs, the learning moments.
---
Mistake #2: They don't engage. Twitter is social. Reply to others, join conversations.
---
Mistake #3: Inconsistency. Tweet daily, even if it's just a quick update.
---
The fix? Treat it like a dev log, not a highlight reel. Your journey IS the content.`;
```
### Manual Thread Parts with Markers
```javascript
const content = `Hook: Why most developers fail at Twitter. (1/5)
Mistake #1: They only share finished work. (2/5)
Mistake #2: They don't engage with others. (3/5)
Mistake #3: Inconsistency in posting schedule. (4/5)
The fix? Treat Twitter like a dev log, not a highlight reel. (5/5)`;
```
## Character Limits
| Account Type | Per-Tweet Limit | Thread Marker Space |
|-------------|-----------------|---------------------|
| Standard | 280 characters | 10 characters reserved for `(X/N)` |
| X Premium | 25,000 characters | 10 characters reserved for `(X/N)` |
Publora automatically reserves space for thread markers.
### Emoji Counting
Emojis count as 2 characters on X/Twitter. Publora accounts for this:
```javascript
// This tweet is 282 "display" characters but 284 Twitter characters
const content = "Hello! 👋 This is a test tweet with emojis 🚀";
// Publora correctly calculates: 280 + 4 (2 emojis × 2) = 284
```
## Adding Media to Threads
Images and videos attach to the **first tweet** only:
```javascript
// Step 1: Create thread
const postResponse = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `Check out this new feature! 🎉
---
Here's how it works: [technical explanation]
---
Try it out and let me know what you think!`,
platforms: ['twitter-123']
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Get upload URL for image (goes to first tweet)
const urlRes = await fetch('https://api.publora.com/api/v1/get-upload-url', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
fileName: 'screenshot.jpg',
contentType: 'image/jpeg',
type: 'image',
postGroupId
})
});
const { uploadUrl } = await urlRes.json();
// Step 3: Upload file directly to S3
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: screenshotFile
});
```
### Media Limits
- **Images:** Up to 4 per tweet (first tweet only)
- **Video:** 1 per tweet (first tweet only)
- **Format:** All images are auto-converted to PNG (1000px max width) before upload to Twitter
- **Note:** Cannot mix images and video in the same tweet
## Scheduling Twitter Threads
> **Note:** `scheduledTime` is optional in both REST and MCP; omitting it creates a draft.
Schedule a thread for optimal posting time:
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `Your thread content here...`,
platforms: ['twitter-123'],
scheduledTime: '2026-03-15T14:00:00.000Z' // 2 PM UTC
})
});
```
## Threads That Reply or Quote
`platformSettings.twitter.replyTo` makes the **head** tweet a reply to an existing post; the remaining parts chain under the head exactly as in a standalone thread. `platformSettings.twitter.quoteTweet` is likewise applied to the head part only, and `platformSettings.twitter.aiGenerated` marks the head part's media as AI-generated (`made_with_ai`) — it is sent only when that part attaches media.
```json
{
"content": "Thanks for the mention — long answer follows.\n\n---\n\nPart two of the answer.",
"platforms": ["twitter-123"],
"scheduledTime": "2026-03-15T14:00:00.000Z",
"platformSettings": {
"twitter": { "replyTo": "https://x.com/customer/status/1234567890123456789" }
}
}
```
Both fields accept a full `x.com`/`twitter.com` status URL or a bare 1–19 digit post ID, and an empty string clears either. On self-serve X API tiers the target's author must have mentioned this account in that post, quoted one of its posts, or this account must have written the target — otherwise the whole thread fails before its first part is published. See [X Reply and Quote Settings](../endpoints/create-post.md#x-reply-and-quote-settings).
## Rate Limits
X-side pricing and posting quotas change independently and are not a Publora numeric contract. Consult X's current developer documentation; each tweet in a thread is a separate platform publication.
## Error Handling
### Partial Thread Failure
Publora stores one platform target for the X connection, and `get-post` reports the chain's progress on it. On a partial thread failure that target is failed with `THREAD_PARTIALLY_PUBLISHED`, `postedId` holds the head tweet ID, and `threadParts[]` says exactly which tweets went out. A group with only this X target has group status `failed`.
```json
{
"platform": "twitter",
"platformId": "123456",
"status": "failed",
"postedId": "1234567890",
"permalink": null,
"isThread": true,
"threadParts": [
{ "index": 0, "content": "Part one (1/3)", "status": "published", "publishedId": "1234567890" },
{ "index": 1, "content": "Part two (2/3)", "status": "published", "publishedId": "1234567891" },
{ "index": 2, "content": "Part three (3/3)", "status": "failed", "publishedId": null }
],
"error": { "code": "THREAD_PARTIALLY_PUBLISHED", "message": "Twitter thread partially published (2/3): Rate limit exceeded", "retryable": false }
}
```
Already-published tweets stay live. Read `threadParts[]` to see which ones, then post only the missing parts yourself — a partially published chain is terminal and not retried, so recreating the post would duplicate what already landed. `list-posts` omits `threadParts`; fetch the group with [get-post](../endpoints/get-post.md#thread-parts).
### Common Errors
| Error | Cause | Solution |
|-------|-------|----------|
| Rate limit exceeded | Too many requests | Wait 15 min or upgrade tier |
| Character limit exceeded | Tweet too long | Check emoji counting, reduce content |
| Duplicate content | Same tweet posted recently | Vary your content |
| `X_REPLY_NOT_AUTHORIZED` | The `replyTo`/`quoteTweet` target is not one X lets this account reply to or quote on a self-serve tier | Reply only where you were mentioned, or quote your own post; do not retry the same target |
| `X_TARGET_REJECTED` | The reply/quote target is deleted, protected, or its author blocked this account | Choose a reachable target; do not retry unchanged |
## Python Example
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': '''Thread: 5 Python tips I wish I knew earlier.
---
1. Use enumerate() instead of range(len()). Cleaner and more Pythonic.
---
2. F-strings are faster than .format() and way more readable.
---
3. List comprehensions aren't just shorter—they're actually faster.
---
4. Use `if __name__ == "__main__":` in every script. Future you will thank you.
---
5. The walrus operator `:=` is underrated. Assign and use in one line.''',
'platforms': ['twitter-123']
}
)
print(response.json())
```
## cURL Example
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "First tweet of my thread\n\n---\n\nSecond tweet continues the story\n\n---\n\nFinal tweet with the conclusion!",
"platforms": ["twitter-123456"]
}'
```
## Why Use Publora for Twitter Threads?
| Feature | Publora | Twitter API v2 Direct |
|---------|---------|----------------------|
| Thread creation | Single API call | Multiple sequential calls |
| Content splitting | Automatic | Manual implementation |
| Error recovery | Built-in partial save | Manual handling |
| Rate limit handling | Automatic errors | Manual tracking |
| Multi-platform | Yes (+ Threads, LinkedIn, etc.) | Twitter only |
## Related
- [Threading Guide](./threading.md) - Complete threading documentation
- [X/Twitter Platform Reference](../platforms/x-twitter.md) - Full platform details
- [Scheduling Posts](./scheduling.md) - Schedule threads for later
- [Media Uploads](./media-uploads.md) - Add images to threads
---
*Post Twitter threads with a single API call using [Publora](https://publora.com).*
---
> Source: https://docs.publora.com/guides/threads-multi-post
# Threads Multi-Post Workflow
Publish a connected chain of Meta Threads posts from one API call. Publora creates each container, publishes it, and links it as a reply to the previous part.
> **One permission is required.** The connection must have granted `threads_manage_replies`. Publora checks the grant when you schedule a chain — from a per-connection cache up to five minutes old — and re-checks it against Meta immediately before publishing, so a missing permission is rejected with `THREADS_PERMISSION_REQUIRED` **before anything is published** — reconnect that account in Publora **Channels** and approve all requested permissions. Single Threads posts never trigger this check.
## Threads Multi-Post API Overview
On Threads (by Meta), you can create connected posts that appear as a conversation thread. This requires:
1. Creating a media container for the first post
2. Publishing it
3. Creating subsequent posts with `reply_to_id` pointing to the previous post
4. Publishing each in sequence
Publora does all four steps for you from a single `create-post` call.
### Keywords: Threads API, Threads multi-post API, Meta Threads API, post to Threads API, Threads thread API, Threads reply chain API, Threads automation API, create Threads post programmatically, Threads bot API, Instagram Threads API, publish multiple Threads posts
## Quick Example
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `I spent 3 months rebuilding our entire backend. Here's what I learned about technical debt.
When we started, our codebase had grown organically over 4 years. What began as a simple MVP had become a tangled mess of shortcuts, deprecated patterns, and "temporary" fixes that became permanent.
The first step was painful: mapping every dependency. We discovered circular imports, dead code paths, and services that nobody remembered building. This audit alone took 3 weeks.
The rebuild itself taught us that incremental migration beats big-bang rewrites. We ran old and new systems in parallel, comparing outputs in real-time. When something broke, we could instantly rollback.
Key lesson: Technical debt isn't just slow code. It's the cognitive load on every engineer who touches your codebase. The rebuild cut our onboarding time from 2 weeks to 3 days.`,
platforms: ['threads-789']
})
});
```
Content that exceeds 500 characters is split into a chain automatically, and each automatically derived part gets a ` (1/N)` suffix. Ten characters of every part's 500 are reserved for that suffix, so about 490 characters of your own text fit per part. Emoji count as 2.
## How Threads Threading Works
### The Official Threads API Way
Using Meta's Graph API directly requires multiple steps:
```javascript
// Step 1: Create first post container
const container1 = await fetch(
`https://graph.threads.net/me/threads?media_type=TEXT&text=First+post&access_token=${token}`,
{ method: 'POST' }
);
const { id: containerId1 } = await container1.json();
// Step 2: Publish first post
const post1 = await fetch(
`https://graph.threads.net/me/threads_publish?creation_id=${containerId1}&access_token=${token}`,
{ method: 'POST' }
);
const { id: postId1 } = await post1.json();
// Step 3: Create second post with reply_to_id
const container2 = await fetch(
`https://graph.threads.net/me/threads?media_type=TEXT&text=Second+post&reply_to_id=${postId1}&access_token=${token}`,
{ method: 'POST' }
);
// ... and so on
```
### The Publora way
```javascript
// Single request - everything handled automatically
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: "First post\n\n---\n\nSecond post\n\n---\n\nThird post",
platforms: ['threads-789']
})
});
```
## Thread Formatting Options
### Automatic Splitting
Content over 500 characters is split for you. Publora prefers paragraph breaks, then line breaks, then sentence endings, then word boundaries, and cuts mid-word only when nothing better is available. Automatically derived parts are numbered ` (1/N)`.
### Manual Thread Parts with `---`
A `---` break must sit on its own line with a newline before and after it. A `---` at the very start or very end of `content`, or `----`, is not recognised. Parts you separate this way are published exactly as written — **no numbering is added**. If one of them still exceeds 500 characters, Publora splits that part further (again without numbering).
```javascript
const content = `Hot take: Most "productivity" advice is just procrastination in disguise.
---
We spend hours optimizing our Notion setup instead of doing the actual work. We read about how successful people structure their days instead of structuring our own.
---
The most productive people I know have embarrassingly simple systems. A paper notebook. A basic to-do list. Maybe a calendar.
---
The tool doesn't matter. The work does. Stop optimizing, start shipping.`;
```
### Manual Thread Parts with Markers
`[n/m]` markers also split the post, and are kept verbatim. They must form a complete, consistent set — `[1/4]` through `[4/4]`, all sharing the same total; an incomplete or mismatched set is ignored and the text is treated as ordinary content. Marker parts are **not** re-split, so a marker part over 500 characters is rejected when you schedule, with `400` and `THREAD_PART_TOO_LONG`.
The numbers below are written into the text itself rather than as `[n/m]` markers, so they are simply part of the content:
```javascript
const content = `Hot take: Most "productivity" advice is procrastination in disguise. (1/4)
We spend hours optimizing systems instead of doing actual work. (2/4)
The most productive people have embarrassingly simple systems. (3/4)
The tool doesn't matter. The work does. Start shipping. (4/4)`;
```
## Character Limits
| Element | Limit |
|---------|-------|
| Post body | 500 characters |
| Hashtags | 1 per post (platform limit) |
## Adding Media to Threads
Media attaches to the **first post** only:
```javascript
// Step 1: Create thread
const postResponse = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `Just launched our new product! Here's a quick walkthrough.
---
The main feature is the dashboard. It shows all your metrics in real-time with zero configuration.
---
We're offering 50% off for early adopters. Link in bio!`,
platforms: ['threads-789']
})
});
const { postGroupId } = await postResponse.json();
// Step 2: Get upload URL for image
const urlRes = await fetch('https://api.publora.com/api/v1/get-upload-url', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
fileName: 'screenshot.jpg',
contentType: 'image/jpeg',
type: 'image',
postGroupId
})
});
const { uploadUrl } = await urlRes.json();
// Step 3: Upload file directly to S3
await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': 'image/jpeg' },
body: screenshotBuffer
});
```
### Media Options
| Type | Limit | Notes |
|------|-------|-------|
| Images | Up to 10 (carousel) | WebP auto-converted to JPEG |
| Video | 1 | MP4 or MOV format |
| Carousel | Up to 10 items | Images only |
## Scheduling Threads Posts
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: `Your long thread content...`,
platforms: ['threads-789'],
scheduledTime: '2026-03-15T09:00:00.000Z'
})
});
```
## Rate Limits
Threads-side quotas are advisory, account-dependent, and not a Publora numeric contract. Publora imposes no cap on the number of parts in a chain; parts are published sequentially with a short pause between them.
## Error Handling
### Partial Thread Failure
If a part fails after earlier parts published, the target ends `failed` with `THREAD_PARTIALLY_PUBLISHED`. **Publora does not republish a chain from the beginning** — that would duplicate the messages already live.
`GET /get-post/:postGroupId` shows exactly where it stopped: the target carries `isThread: true` and one `threadParts[]` entry per part, each with `index` (zero-based), `content`, `status` (`pending`, `published`, `failed`) and `publishedId` (`null` until confirmed). The target's `postedId` is the first part's ID.
```json
{
"platform": "threads",
"platformId": "17841412345678",
"status": "failed",
"postedId": "17900000000000001",
"isThread": true,
"threadParts": [
{ "index": 0, "content": "First message.", "status": "published", "publishedId": "17900000000000001" },
{ "index": 1, "content": "Second message.", "status": "failed", "publishedId": null }
],
"error": { "code": "THREAD_PARTIALLY_PUBLISHED", "message": "Threads thread partially published (1/2): …", "retryable": false }
}
```
Read the parts, check the live account, then publish only what is missing. A separate outcome, `PUBLISH_OUTCOME_UNKNOWN`, means Threads accepted a publish request without returning an ID — the outcome is genuinely unknown and automatic retry is deliberately disabled.
### Common Errors
| Error | Cause | Solution |
|-------|-------|----------|
| `THREADS_PERMISSION_REQUIRED` | Connection has not granted `threads_manage_replies` | Reconnect the account in Channels; nothing was published |
| `THREADS_PERMISSIONS_UNAVAILABLE` (503) | Publora's permission lookup failed — not an account problem | Retry scheduling shortly; do not ask the user to reconnect |
| `THREADS_INVALID_THREAD_PART` | A part is empty, not text, or over 500 characters including numbering | Fix the content and create a new post |
| `THREAD_PARTIALLY_PUBLISHED` | A part failed after earlier parts published | Read `threadParts`, publish only the missing parts |
| Rate limit | Too many posts | Wait and retry |
| Media processing | Video still encoding | Retry after delay |
| Invalid media | Unsupported format | Use JPEG/PNG/MP4 |
## Python Example
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': '''Unpopular opinion: You don't need a personal brand.
---
What you need is to be genuinely helpful and share what you're learning. That's it.
---
The "build your personal brand" industry has convinced us that we need logos, color palettes, and "content pillars."
---
But the creators I actually follow? They just share interesting stuff consistently. No strategy deck required.
---
Be useful. Be consistent. Be yourself. That's the whole playbook.''',
'platforms': ['threads-789']
}
)
print(response.json())
```
## cURL Example
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "First post of my thread\n\n---\n\nSecond post continues the thought\n\n---\n\nFinal post wraps it up!",
"platforms": ["threads-789"]
}'
```
## Why Use Publora for Threads?
| Feature | Publora | Threads API Direct |
|---------|---------|-------------------|
| Thread creation | One API call | Multiple sequential calls |
| OAuth handling | Not required | Complex Meta OAuth flow |
| Content splitting | Automatic, with numbering | Manual implementation |
| API access | Instant | Requires Meta app review |
| Multi-platform | Yes (+ Twitter, LinkedIn, etc.) | Threads only |
## Platform Quirks
- **Single hashtag limit:** Threads allows maximum 1 hashtag per post
- **WebP auto-conversion:** Publora converts WebP images automatically
- **No edit support:** Posted content cannot be edited via API
- **Video processing:** Videos may take time to process before publishing
- **Media on the first part only:** replies in a chain are text-only
- **Reply control applies to the first part only:** `platformSettings.threads.replyControl` is sent with the head post
- **No public `parts` input:** `content` with `---` or `[n/m]` is the whole interface; there is no numbering or threading switch in REST or MCP
## Related
- [Threading Guide](./threading.md) - Complete threading documentation
- [Threads Platform Reference](../platforms/threads.md) - Full platform details
- [Scheduling Posts](./scheduling.md) - Schedule threads for later
- [Media Uploads](./media-uploads.md) - Add images and carousels
---
*[Publora](https://publora.com) — publish a Meta Threads chain from a single REST or MCP call.*
---
> Source: https://docs.publora.com/guides/linkedin-comments
# How to Post Comments on LinkedIn with Publora
Post comments on LinkedIn posts programmatically using the Publora API. Engage with your network automatically without manual interaction.
## Overview
Publora allows you to create and delete comments on any LinkedIn post visible to your connected account. You can also reply to existing comments (nested replies).
## Prerequisites
- Publora API key
- LinkedIn account connected via Publora dashboard
- The `postedId` (LinkedIn URN) of the post you want to comment on
## Create a Comment
**Endpoint:** `POST https://api.publora.com/api/v1/linkedin-comments`
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN (e.g., `urn:li:share:123` or `urn:li:ugcPost:123`) |
| `message` | string | Yes | May be `""` with `imageUrl`; otherwise non-whitespace text is required. Raw input up to 10,000 characters; after mention processing, the text sent to LinkedIn must be at most 1,250 characters. Supports `@{urn:li:person:ID\|Name}` mention syntax. |
| `platformId` | string | Yes | Your LinkedIn platform ID (e.g., `linkedin-ABC123`) |
| `parentComment` | string | No | Comment URN for nested replies |
| `imageUrl` | string | No | Public HTTPS URL of one JPEG, PNG or GIF image, up to 10 MB. |
### JavaScript Example
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:ugcPost:7429953213384187904',
message: 'Great insights! Thanks for sharing.',
platformId: 'linkedin-ABC123'
})
});
const data = await response.json();
console.log(data);
// {
// success: true,
// comment: {
// id: "7434695495614312448",
// commentUrn: "urn:li:comment:(urn:li:ugcPost:xxx,7434695495614312448)",
// message: "Great insights! Thanks for sharing."
// }
// }
```
### Python Example
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-comments',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:ugcPost:7429953213384187904',
'message': 'Great insights! Thanks for sharing.',
'platformId': 'linkedin-ABC123'
}
)
print(response.json())
```
### cURL Example
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-comments \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:ugcPost:7429953213384187904",
"message": "Great insights! Thanks for sharing.",
"platformId": "linkedin-ABC123"
}'
```
## Send an Image Without Text
Include both `message: ""` and `imageUrl` in the request body:
```json
{
"postedId": "urn:li:share:7123456789012345678",
"platformId": "linkedin-ABC123",
"message": "",
"imageUrl": "https://cdn.example.com/reaction.png"
}
```
The message field is still required. Empty or whitespace-only text without an image returns HTTP 400, and failed image validation or upload prevents publication. Publora does not insert spaces or placeholder text. This applies to connected personal profiles and organization pages. See the [endpoint reference](../endpoints/linkedin-comments.md) for image limits and response fields.
## Reply to a Comment
To reply to an existing comment, include the `parentComment` parameter:
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:ugcPost:7429953213384187904',
message: 'I completely agree with your point!',
platformId: 'linkedin-ABC123',
parentComment: 'urn:li:comment:(urn:li:ugcPost:xxx,7434695495614312448)'
})
});
```
## Delete a Comment
**Endpoint:** `DELETE https://api.publora.com/api/v1/linkedin-comments`
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN the comment belongs to |
| `commentId` | string | Yes | Comment URN or numeric comment ID (both formats accepted via the REST API) |
| `platformId` | string | Yes | Your LinkedIn platform ID |
### JavaScript Example
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:ugcPost:7429953213384187904',
commentId: 'urn:li:comment:(urn:li:ugcPost:xxx,7434695495614312448)',
platformId: 'linkedin-ABC123'
})
});
const data = await response.json();
// { success: true, deleted: "urn:li:comment:(...)" }
```
## Getting the postedId
For posts created via Publora, get the `postedId` from the get-post endpoint:
```javascript
const response = await fetch('https://api.publora.com/api/v1/get-post/YOUR_POST_GROUP_ID', {
headers: { 'x-publora-key': 'YOUR_API_KEY' }
});
const data = await response.json();
const postedId = data.posts[0].postedId; // e.g., "urn:li:share:7434685316856377344"
```
## Mentions in Comments
You can @mention people and organizations in comments using the same syntax as posts:
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-comments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:ugcPost:7429953213384187904',
message: 'Excellent analysis @{urn:li:person:Dk968RHxiO|Jane Smith}!',
platformId: 'linkedin-ABC123'
})
});
```
**Result on LinkedIn:** `Excellent analysis @Jane Smith!` — with "Jane Smith" as a clickable profile link.
You can also mention organizations:
```
@{urn:li:organization:98765432|Acme Corp Inc}
```
> **Important:** Person mentions must use LinkedIn's **native member id** (short form, e.g. `Dk968RHxiO` — the same value as a connection's `platformId` without the `linkedin-` prefix). The long `ACoAA…` web-profile ids from linkedin.com URLs do not work — Publora rejects them with a `400` error: *"LinkedIn cannot render mentions that use web-profile ids (urn:li:person:ACoAA…). Use the native member id LinkedIn returns to Publora…"* (previously these failed with an opaque `403` from LinkedIn).
For details on finding native member ids and name matching requirements, see the [LinkedIn Mentions Guide](linkedin-mentions.md).
## Important Notes
- **Character limit:** Comments are limited to 1,250 characters (counted after mention syntax is converted to display names)
- **Mentions:** Use `@{urn:li:person:ID|Name}` or `@{urn:li:organization:ID|Company}` syntax. Person IDs must be native member ids — web-profile `ACoAA…` ids are rejected with a `400` error at intake
- **Network visibility:** You can only comment on posts visible to your LinkedIn account
- **URN format:** Use `urn:li:share:xxx` or `urn:li:ugcPost:xxx` format — **not** `urn:li:activity:xxx` from URLs. Using `urn:li:activity:` may work for plain text comments but will return **403 Forbidden** when mentions are included. To convert: replace `urn:li:activity:` with `urn:li:share:` (the numeric ID is usually the same)
- **MCP tool note:** When using the Publora MCP tool for deleting comments, the tool description only mentions URN format for `commentId`. The REST API accepts both URN and numeric ID formats.
## Related Guides
- [LinkedIn Reactions](linkedin-reactions.md) - Like and react to posts
- [LinkedIn Mentions](linkedin-mentions.md) - Mention users and companies
- [LinkedIn Platform Guide](../platforms/linkedin.md) - Complete LinkedIn API reference
---
> Source: https://docs.publora.com/guides/linkedin-mentions
# How to Mention Users and Companies on LinkedIn with Publora
Create LinkedIn posts that @mention people and organizations using the Publora API. Mentions become clickable links and trigger notifications.
## Overview
Publora supports @mentioning both LinkedIn members (people) and organizations (companies) in your posts. When published, mentions render as clickable profile links. The same syntax works in [comments](linkedin-comments.md) and in [reshare commentary](../endpoints/linkedin-reshare.md).
## Prerequisites
- Publora API key
- LinkedIn account connected via Publora dashboard
- LinkedIn URN of the person or company to mention (see [Finding LinkedIn URNs](#finding-linkedin-urns))
> **Important:** Person mentions must use LinkedIn's **native member id** — the short id LinkedIn returns to Publora (e.g. `Dk968RHxiO`). The long `ACoAA…` ids you see in linkedin.com profile URLs and page source are **web-profile ids and do not work**: Publora rejects them with a `400` error. See [Finding LinkedIn URNs](#finding-linkedin-urns) and [Troubleshooting](#troubleshooting).
## Mention Syntax
Use this format in your post content:
```
@{urn:li:person:MEMBER_ID|Display Name} # Mention a person
@{urn:li:organization:ORG_ID|Company Name} # Mention an organization
```
## Mention a Person
### JavaScript Example
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Great insights from @{urn:li:person:Dk968RHxiO|Serge Bulaev} on building APIs!',
platforms: ['linkedin-ABC123']
})
});
```
**Result on LinkedIn:** `Great insights from @Serge Bulaev on building APIs!`
The mention becomes a clickable link to Serge's profile, and he receives a notification.
### Python Example
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Learned so much from @{urn:li:person:Dk968RHxiO|Serge Bulaev} today!',
'platforms': ['linkedin-ABC123']
}
)
```
### cURL Example
```bash
curl -X POST https://api.publora.com/api/v1/create-post \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"content": "Thanks @{urn:li:person:Dk968RHxiO|Serge Bulaev} for the collaboration!",
"platforms": ["linkedin-ABC123"]
}'
```
## Mention a Company
### JavaScript Example
```javascript
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content: 'Excited to partner with @{urn:li:organization:107107343|Creative Content Crafts Inc}!',
platforms: ['linkedin-ABC123']
})
});
```
**Result on LinkedIn:** `Excited to partner with @Creative Content Crafts Inc!`
### Python Example
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/create-post',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'content': 'Proud to work with @{urn:li:organization:107107343|Creative Content Crafts Inc}!',
'platforms': ['linkedin-ABC123']
}
)
```
## Multiple Mentions
You can mention multiple people and companies in the same post:
```javascript
const content = `
Thrilled to announce our partnership!
Thanks to @{urn:li:person:Dk968RHxiO|Serge Bulaev} and the team at
@{urn:li:organization:107107343|Creative Content Crafts Inc} for making this happen.
Looking forward to building great things together!
`;
const response = await fetch('https://api.publora.com/api/v1/create-post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
content,
platforms: ['linkedin-ABC123']
})
});
```
## Who Can I Mention?
In practice, the people you can mention fall into two groups:
1. **Your own connected accounts** — every LinkedIn connection's native id is in its `platformId` (see [Finding LinkedIn URNs](#finding-linkedin-urns) below).
2. **People who engaged with your connected company pages** — when comments or reactions are read on a company-page post (in the Publora app or via the API), Publora automatically captures each engaging member's native id into a per-user **mentionable-people directory**. No manual step is needed, and no extra LinkedIn calls are made. Engagement on personal-profile posts is not capturable (LinkedIn restricts the required scope).
The recommended way to discover mentionable people is the [`GET /linkedin-mentionables`](../endpoints/linkedin-mentionables.md) endpoint (or the `linkedin_list_mentionables` MCP tool — both paid-plan only). It supports name search and returns a ready-to-paste `mention` token for each person:
```bash
curl "https://api.publora.com/api/v1/linkedin-mentionables?q=daria" \
-H "x-publora-key: YOUR_API_KEY"
```
Anyone outside these two groups — e.g. a person you only know from a linkedin.com profile URL — cannot be mentioned, because their native id is not obtainable (see the honest limitation under [Finding LinkedIn URNs](#finding-linkedin-urns)).
## Finding LinkedIn URNs
### Person URN
Format: `urn:li:person:{member_id}`
LinkedIn has **two different id systems** for members, and only one of them works in mentions:
| Id form | Example | Works in mentions? |
|---------|---------|--------------------|
| **Native member id** (app-scoped, returned by LinkedIn's API to Publora) | `Dk968RHxiO` | Yes |
| Web-profile id (from linkedin.com URLs / page source) | `ACoAABcD1234EfG` | **No — rejected with 400** |
Where to get native member ids:
- **Your own connected accounts:** the [platform-connections](../endpoints/platform-connections.md) endpoint returns each LinkedIn connection's `platformId` (e.g. `linkedin-Dk968RHxiO`). Strip the `linkedin-` prefix — the remainder is that member's native id.
- **Actor ids returned by Publora's LinkedIn APIs:** endpoints such as [comments](../endpoints/linkedin-comments.md), [reactions](../endpoints/linkedin-reactions.md), and [feed retrieval](../endpoints/linkedin-feed-retrieval.md) return `urn:li:person:…` actor URNs in their responses. The id inside those URNs is the native form and can be used directly.
- **The mentionable-people directory:** [`GET /linkedin-mentionables`](../endpoints/linkedin-mentionables.md) lists every native id Publora has captured for you, searchable by name and with a ready-to-paste `mention` token per person (see [Who Can I Mention?](#who-can-i-mention)).
> **Honest limitation:** There is **no public API to look up an arbitrary member's native id.** You can reliably mention people whose ids you obtained through Publora or LinkedIn API surfaces (your connections, actors on posts/comments you retrieved) — **not** people you found via a linkedin.com profile URL. The `ACoAA…` id visible in profile URLs and page source cannot be converted to a native id.
### Organization URN
Found in the company page URL or via LinkedIn's API. Format: `urn:li:organization:{numeric_id}`. Organization IDs are numeric (e.g. `107107343`). The numeric admin id shown in your company page URL (`linkedin.com/company/107107343/admin/`) is the correct id.
## Critical: Name Matching Requirements
The display name is matched **case-sensitively** against the profile or page name. The rules differ for people and companies:
**For people:** the display text may be the **first name, last name, or full name** — exactly as it appears on the profile. Any **extra text breaks the mention**: it silently degrades to plain text, with no link and no notification.
| Status | Example |
|--------|---------|
| Correct | `@{urn:li:person:Dk968RHxiO\|Daria Bulaeva}` (full name) |
| Correct | `@{urn:li:person:Dk968RHxiO\|Daria}` (first name only) |
| Wrong | `@{urn:li:person:Dk968RHxiO\|Daria Bulaeva, Ph.D.}` (extra text — plain text, no link) |
| Wrong | `@{urn:li:person:Dk968RHxiO\|daria bulaeva}` (wrong case) |
Never append degrees, suffixes, emojis, or punctuation to a person's name.
**For companies:** use the **exact registered page name** including suffixes like "Inc", "LLC", "Ltd", etc.
| Status | Example |
|--------|---------|
| Correct | `@{urn:li:organization:98765432\|Acme Corp Inc}` |
| Wrong | `@{urn:li:organization:98765432\|Acme Corp}` (missing "Inc") |
**If the name doesn't match:** the mention appears as plain text instead of a clickable link. LinkedIn does not return an error for this — verify the published post.
## Common Mistakes
1. **Web-profile id:** `ACoAABcD1234EfG` instead of the native id `Dk968RHxiO` — rejected with a `400` error
2. **Extra text after a person's name:** `Daria Bulaeva, Ph.D.` instead of `Daria Bulaeva` — silently degrades to plain text
3. **Wrong name case:** `john smith` instead of `John Smith`
4. **Missing company suffix:** `Acme Corp` instead of `Acme Corp Inc`
5. **Extra spaces:** `John Smith` (double space)
6. **Wrong URN type:** Using `urn:li:member:` instead of `urn:li:person:`
## Troubleshooting
### 400: "LinkedIn cannot render mentions that use web-profile ids"
```
LinkedIn cannot render mentions that use web-profile ids (urn:li:person:ACoAA…).
Use the native member id LinkedIn returns to Publora. External connection identifiers
are namespaced (for example linkedin-Dk968RHxiO), so remove the leading linkedin-
before building the person URN; actor ids from Publora's LinkedIn APIs are already
raw. IDs copied from linkedin.com profile URLs will not work.
```
Publora returns this `400` at intake (create-post, update-post, linkedin-comments, linkedin-reshare) when a person mention uses an `ACoAA…` web-profile id. Replace it with the native member id (see [Finding LinkedIn URNs](#finding-linkedin-urns)). Before this validation existed, LinkedIn itself rejected such posts with `400 INVALID_CONTENT` ("Person URN ID in commentary field is invalid"), and comments failed with an opaque `403`.
### Post published, but the whole text shows literal `@{...}` markup with backslashes
LinkedIn sometimes accepts a post containing a web-profile (`ACoAA…`) person id but fails to parse the mention — the entire commentary then renders as escaped literal text (visible `@{urn:li:person:…|Name}` and backslashes). This is another symptom of the same root cause: switch to the native member id.
### Mention shows as plain text (no link, no notification)
The id was valid but the display name didn't match. Check the [name matching rules](#critical-name-matching-requirements): case must match, and for people the text must be exactly the first name, last name, or full name — nothing more.
## Verifying Mentions Work
After posting, check your LinkedIn post to ensure:
1. The mention appears as a clickable blue link
2. Clicking it navigates to the correct profile/company page
3. The mentioned person/company received a notification
## Related Guides
- [LinkedIn Mentionables](../endpoints/linkedin-mentionables.md) - List the people you can mention
- [LinkedIn Comments](linkedin-comments.md) - Comment on posts
- [LinkedIn Reshare](../endpoints/linkedin-reshare.md) - Reshare posts with mention-capable commentary
- [LinkedIn Reactions](linkedin-reactions.md) - Like and react to posts
- [LinkedIn Platform Guide](../platforms/linkedin.md) - Complete LinkedIn API reference
---
> Source: https://docs.publora.com/guides/linkedin-reactions
# How to Like and React to LinkedIn Posts with Publora
Add reactions (like, insightful, love, etc.) to LinkedIn posts programmatically using the Publora API.
## Overview
LinkedIn supports 6 different reaction types. Publora allows you to add or remove any of these reactions on posts visible to your connected account.
## Available Reaction Types
| Reaction | Description | Icon |
|----------|-------------|------|
| `LIKE` | Standard like | Thumbs up |
| `PRAISE` | Applause / celebration | Clapping hands |
| `EMPATHY` | Love / support | Heart |
| `INTEREST` | Insightful / thought-provoking | Lightbulb |
| `APPRECIATION` | Supportive | Hands together |
| `ENTERTAINMENT` | Funny | Laughing face |
## Prerequisites
- Publora API key
- LinkedIn account connected via Publora dashboard
- The `postedId` (LinkedIn URN) of the post
## Add a Reaction
**Endpoint:** `POST https://api.publora.com/api/v1/linkedin-reactions`
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN |
| `reactionType` | string | Yes | One of: `LIKE`, `PRAISE`, `EMPATHY`, `INTEREST`, `APPRECIATION`, `ENTERTAINMENT` |
| `platformId` | string | Yes | Your LinkedIn platform ID |
### JavaScript Example - Add "Insightful" Reaction
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-reactions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:ugcPost:7429953213384187904',
reactionType: 'INTEREST', // Insightful (lightbulb)
platformId: 'linkedin-ABC123'
})
});
const data = await response.json();
console.log(data);
// {
// success: true,
// reaction: {
// id: "urn:li:reaction:(urn:li:person:xxx,urn:li:ugcPost:xxx)",
// reactionType: "INTEREST"
// },
// urnTranslated: { from: "urn:li:activity:xxx", to: "urn:li:ugcPost:xxx" } // Only present if URN was translated
// }
```
> **Note:** The `urnTranslated` field is only present when the provided `postedId` was automatically translated to a different URN format (e.g., from `urn:li:activity:xxx` to `urn:li:ugcPost:xxx`). This helps debug URN format issues.
### Python Example - Add "Like" Reaction
```python
import requests
response = requests.post(
'https://api.publora.com/api/v1/linkedin-reactions',
headers={
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
json={
'postedId': 'urn:li:ugcPost:7429953213384187904',
'reactionType': 'LIKE',
'platformId': 'linkedin-ABC123'
}
)
print(response.json())
```
### cURL Example - Add "Love" Reaction
```bash
curl -X POST https://api.publora.com/api/v1/linkedin-reactions \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:ugcPost:7429953213384187904",
"reactionType": "EMPATHY",
"platformId": "linkedin-ABC123"
}'
```
## Remove a Reaction
**Endpoint:** `DELETE https://api.publora.com/api/v1/linkedin-reactions`
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN |
| `platformId` | string | Yes | Your LinkedIn platform ID |
### JavaScript Example
```javascript
const response = await fetch('https://api.publora.com/api/v1/linkedin-reactions', {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId: 'urn:li:ugcPost:7429953213384187904',
platformId: 'linkedin-ABC123'
})
});
const data = await response.json();
// { success: true }
```
### cURL Example
```bash
curl -X DELETE https://api.publora.com/api/v1/linkedin-reactions \
-H "Content-Type: application/json" \
-H "x-publora-key: YOUR_API_KEY" \
-d '{
"postedId": "urn:li:ugcPost:7429953213384187904",
"platformId": "linkedin-ABC123"
}'
```
## Common Use Cases
### Auto-engage with industry content
```javascript
// React to multiple posts with "Insightful"
const postIds = [
'urn:li:ugcPost:123456789',
'urn:li:ugcPost:987654321',
'urn:li:ugcPost:456789123'
];
for (const postedId of postIds) {
await fetch('https://api.publora.com/api/v1/linkedin-reactions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-publora-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
postedId,
reactionType: 'INTEREST',
platformId: 'linkedin-ABC123'
})
});
// Add delay to avoid rate limits
await new Promise(r => setTimeout(r, 1000));
}
```
## Important Notes
- **Network visibility:** You can only react to posts visible in your LinkedIn network
- **One reaction per post:** LinkedIn allows only one reaction type per post per user
- **URN format matters:** Use `urn:li:share:xxx` or `urn:li:ugcPost:xxx`, NOT `urn:li:activity:xxx` from LinkedIn URLs
- **Change reaction:** To change your reaction, delete the existing one first, then add the new one
## Getting the Correct URN
LinkedIn URLs use `urn:li:activity:xxx` but the API requires `urn:li:share:xxx` or `urn:li:ugcPost:xxx`.
For posts created via Publora:
```javascript
const response = await fetch('https://api.publora.com/api/v1/get-post/YOUR_POST_GROUP_ID', {
headers: { 'x-publora-key': 'YOUR_API_KEY' }
});
const postedId = (await response.json()).posts[0].postedId;
```
## Related Guides
- [LinkedIn Comments](linkedin-comments.md) - Comment on posts
- [LinkedIn Mentions](linkedin-mentions.md) - Mention users and companies
- [LinkedIn Platform Guide](../platforms/linkedin.md) - Complete LinkedIn API reference
---
> Source: https://docs.publora.com/guides/linkedin-analytics
# How to Retrieve LinkedIn Analytics with Publora
Get engagement metrics (impressions, reactions, comments, shares) for your LinkedIn posts using the Publora API.
## Overview
Publora provides analytics for LinkedIn posts through a single endpoint. You can retrieve individual metrics or all metrics at once.
## API Reference
**Endpoint:**
```
POST https://api.publora.com/api/v1/linkedin-post-statistics
```
**Headers:**
```
Content-Type: application/json
x-publora-key: YOUR_API_KEY
```
**Request Body:**
```json
{
"postedId": "urn:li:share:7434685316856377344",
"platformId": "linkedin-ABC123",
"queryTypes": ["ALL"]
}
```
## Available Metrics
| Metric | Description |
|--------|-------------|
| `IMPRESSION` | Number of times the post was displayed |
| `MEMBERS_REACHED` | Unique LinkedIn members who saw the post |
| `REACTION` | Total reactions (likes, celebrates, etc.) |
| `COMMENT` | Number of comments on the post |
| `RESHARE` | Number of times the post was shared |
## Request Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `postedId` | string | Yes | LinkedIn post URN (from get-post endpoint) |
| `platformId` | string | Yes | Your LinkedIn platform ID (e.g., `linkedin-ABC123`) |
| `queryType` | string | No | Single metric: `IMPRESSION`, `REACTION`, etc. |
| `queryTypes` | array | No | Multiple metrics: `["IMPRESSION", "REACTION"]` or `["ALL"]` |
*Use either `queryType` (single) or `queryTypes` (multiple), not both.*
## Response Format
**Single metric response:**
```json
{
"success": true,
"count": 4521,
"cached": false
}
```
**Multiple metrics response:**
```json
{
"success": true,
"metrics": {
"IMPRESSION": 4521,
"MEMBERS_REACHED": 3200,
"REACTION": 89,
"COMMENT": 15,
"RESHARE": 12
},
"cached": false,
"cachedMetrics": []
}
```
## Complete JavaScript Implementation
```javascript
const PUBLORA_API_KEY = process.env.PUBLORA_API_KEY;
const BASE_URL = 'https://api.publora.com/api/v1';
/**
* Retrieve LinkedIn post analytics
* @param {string} postedId - LinkedIn post URN (urn:li:share:xxx or urn:li:ugcPost:xxx)
* @param {string} platformId - LinkedIn platform ID (linkedin-xxx)
* @param {string|string[]} metrics - Single metric, array of metrics, or 'ALL'
* @returns {Promise