API Overview

The PostProxy API allows you to programmatically create and manage social media posts across multiple platforms including Facebook, Instagram, TikTok, LinkedIn, YouTube, X (Twitter), and Threads.

Base URL

All API requests should be made to:

https://api.postproxy.dev

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer your_api_key_here

API Key Types

Type	Scope	Capabilities
Full Access	Entire account	Access all profile groups, create/delete profile groups
Profile Group Scoped	Single profile group	Access only the specified profile group, cannot create/delete profile groups

Profile Group Context

API requests operate within a profile group context. The profile group is determined by:

1. Explicit parameter: Pass ?profile_group_id=<id> as a query parameter
2. API key scope: If your API key is scoped to a profile group, that group is used automatically
3. Default: If neither is specified and the key has full access, the first profile group in your account is used

Response Format

All responses are JSON. IDs are returned as hashids (URL-safe encoded identifiers).

Successful Responses

Single resource:

{
  "id": "abc123xyz",
  "name": "My Profile Group",
  "profiles_count": 3
}

Collection with pagination:

{
  "total": 150,
  "page": 0,
  "per_page": 10,
  "data": [
    { "id": "..." },
    { "id": "..." }
  ]
}

Error Responses

Code	Response
401	{"error": "Invalid API key"}
404	{"error": "Not found"}
400	{"status": 400, "error": "Bad Request", "message": "..."}
422	{"errors": ["Validation error message"]}

HTTP Status Codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource was created successfully
400 Bad Request	Missing required parameters
401 Unauthorized	Invalid, missing, or insufficient API key permissions
404 Not Found	Resource does not exist or is not accessible
422 Unprocessable Entity	Validation failed

Pagination

List endpoints support pagination with the following query parameters:

Parameter	Type	Default	Description
page	integer	0	Page number (zero-indexed)
per_page	integer	10	Number of items per page

Supported Platforms

Platform	Platform ID	Available Formats
Facebook	facebook	post, story
Instagram	instagram	post, reel, story
TikTok	tiktok	post
LinkedIn	linkedin	post
YouTube	youtube	post (channel video)
X (Twitter)	twitter	post
Threads	threads	post