API docs by Redocly

UniPostAPI (1.0.0)

Download OpenAPI specification:

UniPostAPI Support: [email protected] License: Proprietary

UniPostAPI is a unified REST API for publishing content to multiple social media platforms.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_your_api_key

API keys use a prefixed format:

  • sk_live_* — Production keys that publish to real platform APIs
  • sk_test_* — Test keys that validate content but return mock publish results

The key prefix determines the mode. Test and live data are fully isolated — posts created with a test key are only visible to test keys, and vice versa. Test-mode publishing runs content validation but skips real API calls, returning mock platform post IDs and URLs.

Rate Limits

Rate limits depend on your plan tier. Every response includes rate limit headers:

Header Description
X-RateLimit-Limit Maximum requests per minute
X-RateLimit-Remaining Requests remaining in the current window
X-RateLimit-Reset Unix timestamp when the window resets

Async Processing

Content publishing is asynchronous. When you create a post, it returns immediately with a pending status. Track progress by polling the post endpoint or registering a webhook for real-time notifications.

Errors

All errors follow a consistent format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable description",
  "statusCode": 400
}

Posts

Create and manage social media posts across platforms

Create a post

Create a new post targeting one or more connected accounts. The post is processed asynchronously — the response returns immediately with a pending status.

Use the idempotencyKey field to safely retry requests without creating duplicate posts.

Authorizations:
bearerAuth
Request Body schema: application/json
required
accountIds
required
Array of strings non-empty

IDs of connected accounts to publish to

required
object
scheduledAt
string <date-time>

Schedule publishing for a future time (ISO 8601)

object
object

Platform-specific content overrides

idempotencyKey
string <uuid>

Unique key to prevent duplicate submissions on retry

Responses

Request samples

Content type
application/json
{
  • "accountIds": [
    ],
  • "content": {},
  • "disclosure": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List posts

List posts with optional filtering by status, platform, or account. Uses cursor-based pagination.

Authorizations:
bearerAuth
query Parameters
status
string (PostStatus)
Enum: "pending" "scheduled" "publishing" "published" "failed" "cancelled"

Post lifecycle status:

  • pending — Queued for processing
  • scheduled — Waiting for scheduled publish time
  • publishing — Currently being submitted to platform(s)
  • published — Successfully published to all targets
  • failed — One or more targets failed permanently
  • cancelled — Cancelled before publishing
platform
string (Platform)
Enum: "tiktok" "instagram" "youtube"

Social media platform identifier

accountId
string

Filter by target account ID

cursor
string

Pagination cursor from a previous response

limit
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get a post

Retrieve the current status and details of a post, including per-target status.

Authorizations:
bearerAuth
path Parameters
postId
required
string
Example: post_abc123

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Cancel a post

Cancel a scheduled or pending post before it is published. Posts that have already been published or are currently publishing cannot be cancelled.

Authorizations:
bearerAuth
path Parameters
postId
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Accounts

View and manage connected social media accounts

List connected accounts

List all social media accounts connected to your organization.

Authorizations:
bearerAuth
query Parameters
platform
string (Platform)
Enum: "tiktok" "instagram" "youtube"

Social media platform identifier

status
string (AccountStatus)
Enum: "active" "token_expiring" "token_expired" "rate_limited" "suspended" "error"

Current health status of a connected account

cursor
string
limit
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get account details

Retrieve details of a connected social media account, including token status and profile information.

Authorizations:
bearerAuth
path Parameters
accountId
required
string
Example: acc_tiktok_abc123

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Disconnect an account

Disconnect a social media account. This revokes stored OAuth tokens and removes the account from your organization. Pending posts targeting this account will be cancelled.

Authorizations:
bearerAuth
path Parameters
accountId
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

OAuth

Connect social media accounts via OAuth

Start OAuth flow

Generate an authorization URL for a social media platform. Redirect the user to this URL to start the OAuth consent flow. The user will be redirected back to your redirectUri after granting (or denying) access.

Authorizations:
bearerAuth
path Parameters
platform
required
string (Platform)
Enum: "tiktok" "instagram" "youtube"

Social media platform identifier

Request Body schema: application/json
required
redirectUri
required
string <uri>

URL to redirect the user to after authorization

scopes
Array of strings

Optional additional scopes to request

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

OAuth callback

OAuth redirect target. After the user authorizes on the social media platform, they are redirected here with an authorization code. UniPostAPI exchanges it for tokens and redirects back to your redirectUri with the new account ID.

Note: This endpoint is called by the browser during the OAuth redirect flow, not directly by your API client.

Authorizations:
bearerAuth
path Parameters
platform
required
string (Platform)
Enum: "tiktok" "instagram" "youtube"

Social media platform identifier

query Parameters
code
required
string

Authorization code from the platform

state
required
string

CSRF state parameter for verification

Responses

Response samples

Content type
application/json
{
  • "error": "validation_failed",
  • "message": "accountIds must contain at least 1 item",
  • "statusCode": 400
}

Webhooks

Configure real-time event notifications

Register a webhook

Register a URL to receive event notifications. You can filter which events, platforms, and accounts trigger the webhook.

The response includes a signingSecret which you should store securely. Use it to verify webhook signatures via the X-UniPostAPI-Signature header.

Authorizations:
bearerAuth
Request Body schema: application/json
required
url
required
string <uri>

HTTPS URL to receive webhook payloads

events
required
Array of strings (WebhookEvent) non-empty
Items Enum: "post.pending" "post.processing" "post.scheduled" "post.publishing" "post.published" "post.failed" "post.cancelled" "account.connected" "account.token_expiring" "account.token_expired" "account.error"

Event types to subscribe to

filterPlatforms
Array of strings (Platform)
Items Enum: "tiktok" "instagram" "youtube"

Only trigger for events from these platforms

filterAccountIds
Array of strings

Only trigger for events from these accounts

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "events": [
    ],
  • "filterPlatforms": [
    ],
  • "filterAccountIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List webhooks

List all registered webhook endpoints for your organization.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get webhook details

Authorizations:
bearerAuth
path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a webhook

Update the URL, events, or filters for an existing webhook.

Authorizations:
bearerAuth
path Parameters
webhookId
required
string
Request Body schema: application/json
required
url
string <uri>
events
Array of strings (WebhookEvent)
Items Enum: "post.pending" "post.processing" "post.scheduled" "post.publishing" "post.published" "post.failed" "post.cancelled" "account.connected" "account.token_expiring" "account.token_expired" "account.error"
filterPlatforms
Array of strings (Platform)
Items Enum: "tiktok" "instagram" "youtube"
filterAccountIds
Array of strings
isActive
boolean

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "events": [
    ],
  • "filterPlatforms": [
    ],
  • "filterAccountIds": [
    ],
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a webhook

Deactivate and remove a webhook endpoint.

Authorizations:
bearerAuth
path Parameters
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Usage

Plan usage and quota information

Get plan usage

Returns the current billing period's usage counts and plan limits for your organization. Includes post and account counts relative to plan limits, and which features are enabled.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "period": "2026-02",
  • "plan": "starter",
  • "usage": {
    },
  • "features": {
    }
}

Platforms

Platform capabilities and requirements

Get platform requirements

Returns the video, content, and capability requirements for a specific platform. Use this to validate content before creating a post. Does not require authentication.

path Parameters
platform
required
string (Platform)
Enum: "tiktok" "instagram" "youtube"

Social media platform to get requirements for

Responses

Response samples

Content type
application/json
{
  • "platform": "tiktok",
  • "video": {
    },
  • "content": {
    },
  • "capabilities": {
    }
}

Health

Service health checks

Health check

Returns service health status. Does not require authentication.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "timestamp": "2019-08-24T14:15:22Z"
}