postproxy-dev Placements API
Account-wide placements and the profile serving each one
Account-wide placements and the profile serving each one
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/postproxy-dev:postproxy-dev-placements-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Postproxy Social Media Placements API
version: '2026-09-21'
summary: Unified social media API for publishing, comments, direct messages, and reviews.
description: 'The Postproxy API lets you programmatically create and manage social media posts across Facebook, Instagram, TikTok, LinkedIn, YouTube, X (Twitter), Threads, Pinterest, Bluesky, Telegram, and Google Business. Beyond publishing you can read and reply to comments, read and send direct messages, and reply to Google Business reviews and Facebook Page recommendations.
Send one payload; Postproxy maps it to each platform''s rules and returns a per-platform outcome. Sandbox mode is included on all plans for development without real accounts.
Human-readable reference: https://postproxy.dev/reference/overview/
## Versioning and deprecation
The API has a single stable version served at https://api.postproxy.dev/api. Releases are identified by this document''s date-based `info.version`. Changes are additive: new endpoints, new optional parameters, and new response fields may appear, and clients should ignore fields they do not recognize. Existing fields, parameters, and status codes are not changed or removed without a deprecation cycle.
When an endpoint or field is deprecated it is marked `deprecated: true` in this specification and announced in the changelog (https://postproxy.dev/getting-started/changelog/) at least 90 days before removal.'
termsOfService: https://postproxy.dev/terms-conditions/
contact:
name: Postproxy Support
url: https://postproxy.dev/developers/
email: support@postproxy.dev
x-versioning:
strategy: stable-single-version
spec-version-format: date (YYYY-MM-DD)
compatibility: additive-only; breaking changes go through a deprecation cycle
deprecation-signal: 'deprecated: true in this spec, plus a changelog announcement at least 90 days before removal'
changelog: https://postproxy.dev/getting-started/changelog/
servers:
- url: https://api.postproxy.dev
description: Production
security:
- bearerAuth: []
tags:
- name: Placements
description: Account-wide placements and the profile serving each one
externalDocs:
url: https://postproxy.dev/reference/placements/
paths:
/api/placements:
get:
operationId: placements_list
summary: List placements (account-wide)
description: Retrieves every placement on the account, across all platforms and profile groups, including which connected profile actively serves each one. Requires an account-wide API key (one not scoped to a profile group); a group-scoped key returns 422. Sandbox API keys list sandbox placements; live keys list live placements. Default per_page is 25 (maximum 100).
tags:
- Placements
externalDocs:
url: https://postproxy.dev/reference/placements/
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: Paginated list of placements
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedCollection'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Placement'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: API key is scoped to a profile group — an account-wide key is required.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/placements/{id}/set_active_profile:
patch:
operationId: placements_set_active_profile
summary: Set active profile
description: Switches which connected profile serves the placement — posting and webhook traffic route through it from then on. The profile must be listed in the placement's linked_profiles and be connected. Switching an orphaned placement to a connected profile also fires the placement.restored webhook. Requires an account-wide API key; a group-scoped key returns 422.
tags:
- Placements
externalDocs:
url: https://postproxy.dev/reference/placements/
parameters:
- name: id
in: path
required: true
description: Placement ID (the id from List placements, not the platform ID)
schema:
type: string
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- profile_id
properties:
profile_id:
type: string
description: Profile to make active. Must be listed in the placement's linked_profiles and be connected.
responses:
'200':
description: The updated placement
content:
application/json:
schema:
$ref: '#/components/schemas/Placement'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
description: Profile cannot serve the placement (not linked, not connected, or in a different live/sandbox environment), or the API key is scoped to a profile group.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
responses:
NotFound:
description: Resource does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
notFound:
value:
error: Not found
BadRequest:
description: Missing required parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
Unauthorized:
description: Invalid, missing, or insufficient API key permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidKey:
value:
error: Invalid API key
parameters:
PerPage:
name: per_page
in: query
required: false
description: Number of items per page.
schema:
type: integer
default: 10
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: 'Optional idempotency key (up to 255 characters; a UUID is ideal). Retrying a successful write with the same key replays the original response (with an Idempotent-Replay: true header) instead of executing again. Stored responses are kept for 24 hours; only 2xx responses are stored.'
schema:
type: string
maxLength: 255
Page:
name: page
in: query
required: false
description: Page number (1-based). Passing 0 returns page 1.
schema:
type: integer
default: 1
minimum: 0
schemas:
Placement:
type: object
description: Account-wide placement record (Facebook Page, LinkedIn organization, Pinterest board, Telegram channel, Google Business location). One record exists per account, platform, and platform ID, even when several connected profiles can see it; exactly one linked profile is the active profile that posting and webhooks route through.
properties:
id:
type: string
description: Placement ID. Postproxy's own ID, used in placement URLs — not the platform ID.
platform:
type: string
description: Platform the placement belongs to.
enum:
- facebook
- linkedin
- pinterest
- telegram
- google_business
external_id:
type: string
description: Platform-specific ID — the value used as page_id / chat_id when creating posts, and returned as id by the per-profile List placements endpoint.
name:
type: string
description: Placement name.
avatar_url:
type:
- string
- 'null'
description: Stable Postproxy storage URL of the placement's picture, resized to 256x256 (Facebook Pages). null until it has been mirrored and for networks without one.
status:
type: string
description: active (the active profile is connected), orphaned (the active profile is disconnected — posting is paused until you switch to a connected profile), or removed (access was revoked on the platform).
enum:
- active
- orphaned
- removed
active_profile:
$ref: '#/components/schemas/PlacementProfileRef'
description: The profile posting routes through.
linked_profiles:
type: array
description: Every profile that can see this placement — the candidates for Set active profile.
items:
$ref: '#/components/schemas/PlacementProfileRef'
Error:
type: object
properties:
error:
type: string
required:
- error
PaginatedCollection:
type: object
description: Envelope for paginated list responses.
properties:
total:
type: integer
page:
type: integer
per_page:
type: integer
data:
type: array
items: {}
required:
- total
- page
- per_page
- data
PlacementProfileRef:
type: object
description: Compact profile reference on a placement.
properties:
id:
type: string
description: Profile ID.
name:
type: string
description: Profile display name.
connected:
type: boolean
description: Whether the profile is currently connected.
BadRequestError:
type: object
properties:
status:
type: integer
const: 400
error:
type: string
message:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key sent as a Bearer token in the Authorization header. Keys are either full-access (entire account) or scoped to a single profile group. Create keys at https://app.postproxy.dev under Settings → API Keys.
externalDocs:
description: Full API reference
url: https://postproxy.dev/reference/overview/