Quickstart

Postproxy is a unified API for social media platforms, with built-in scheduling, error handling, and retry management. This quickstart covers publishing posts, but the API also handles engagement: managing comments on your posts, sending and receiving 1:1 direct messages, and reading and replying to Google Business reviews. You’ll find guides and examples for each platform on the platform pages.

This guide gets you from zero to your first published post. Grab an API key, connect an account, then pick how you want to publish — the REST API, the MCP server for AI agents, or a no-code tool like Zapier or n8n.

Get your API key

1. Sign up or log in to your Postproxy dashboard.
2. Open the API keys settings and create a key.
3. Copy the key — you’ll pass it as a Bearer token on every request.

API keys are either full access (your whole account) or scoped to a single profile group. See Authentication for details.

Connect a social account

In the dashboard, open Profiles and authorize the social platforms you want to publish to (Facebook, Instagram, TikTok, LinkedIn, X, YouTube, Threads, Pinterest, Bluesky, Telegram, or Google Business).

Postproxy creates your first profile group automatically when you sign up, and each account you connect becomes a profile in that group. Once at least one account is connected, you’re ready to publish.

Prefer to onboard accounts programmatically? Call initialize_connection on a profile group to generate an OAuth URL, then redirect your user to it to authorize the account.

cURL

curl -X POST "https://api.postproxy.dev/api/profile_groups/grp456xyz/initialize_connection" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "platform": "instagram",
       "redirect_url": "https://myapp.com/oauth/callback"
     }'

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const connection = await client.profileGroups.initializeConnection(
  "grp456xyz",
  "instagram",
  "https://myapp.com/oauth/callback",
);
// Redirect the user to connection.url
console.log(connection.url);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
connection = await client.profile_groups.initialize_connection(
    "grp456xyz", "instagram", "https://myapp.com/oauth/callback"
)
# Redirect the user to connection.url
print(connection.url)

Go

package main

import (
  "context"
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  connection, _ := client.ProfileGroups.InitializeConnection(context.Background(), "grp456xyz", "instagram", "https://myapp.com/oauth/callback")
  // Redirect the user to connection.URL
  fmt.Println(connection.URL)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
connection = client.profile_groups.initialize_connection(
  "grp456xyz",
  platform: "instagram",
  redirect_url: "https://myapp.com/oauth/callback"
)
# Redirect the user to connection.url
puts connection.url

PHP

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");
$connection = $client->profileGroups()->initializeConnection("grp456xyz", "instagram", "https://myapp.com/oauth/callback");
// Redirect the user to $connection->url
echo $connection->url;

Java

import dev.postproxy.sdk.PostProxy;

var client = PostProxy.builder("YOUR_API_KEY").build();
var connection = client.profileGroups().initializeConnection("grp456xyz", "instagram", "https://myapp.com/oauth/callback");
// Redirect the user to connection.url()
System.out.println(connection.url());

.NET

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
var connection = await client.ProfileGroups.InitializeConnectionAsync("grp456xyz", Platform.Instagram, "https://myapp.com/oauth/callback");
// Redirect the user to connection.Url
Console.WriteLine(connection.Url);

Response:

{
  "url": "https://app.postproxy.dev/partner_connect/inv789xyz",
  "success": true
}

Redirect the user to the returned url to complete the OAuth flow. Once they authorize, the account appears as a profile in the group.

Publish with the API

Step 1: Get your profiles

First, retrieve your connected profiles to get their IDs.

cURL

curl -X GET "https://api.postproxy.dev/api/profiles" \
     -H "Authorization: Bearer YOUR_API_KEY"

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const profiles = await client.profiles.list();
console.log(profiles);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
profiles = await client.profiles.list()
print(profiles)

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  profiles, _ := client.Profiles.List()
  fmt.Println(profiles)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
profiles = client.profiles.list
puts profiles

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$profiles = $client->profiles->list();
print_r($profiles);

Java

import dev.postproxy.PostProxy;

PostProxy client = new PostProxy("YOUR_API_KEY");
var profiles = client.profiles().list();
System.out.println(profiles);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var profiles = await client.Profiles.ListAsync();
Console.WriteLine(profiles);

Response:

{
  "data": [
    {
      "id": "prof123abc",
      "name": "My Company Page",
      "platform": "facebook",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 42
    },
    {
      "id": "prof789def",
      "name": "@mycompany",
      "platform": "instagram",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 38
    }
  ]
}

Note the profile IDs and platform types - you’ll use these when creating posts.

Step 2: Create a post

Post content to one or more profiles. You can specify profiles by their ID or by platform name (uses the first profile for that platform).

cURL

curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {
         "body": "Hello World!",
         "draft": true
       },
       "profiles": ["facebook", "instagram"],
       "media": ["https://example.com/image.jpg"]
     }'

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const post = await client.posts.create("Hello World!", ["facebook", "instagram"], {
  media: ["https://example.com/image.jpg"],
  draft: true,
});
console.log(post);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
post = await client.posts.create(
    "Hello World!",
    ["facebook", "instagram"],
    media=["https://example.com/image.jpg"],
    draft=True,
)
print(post)

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  post, _ := client.Posts.Create("Hello World!", []string{"facebook", "instagram"}, &postproxy.CreatePostOptions{
    Media: []string{"https://example.com/image.jpg"},
    Draft: true,
  })
  fmt.Println(post)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
post = client.posts.create(
  "Hello World!",
  profiles: ["facebook", "instagram"],
  media: ["https://example.com/image.jpg"],
  draft: true
)
puts post

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$post = $client->posts->create("Hello World!", ["facebook", "instagram"], [
    "media" => ["https://example.com/image.jpg"],
    "draft" => true,
]);
print_r($post);

Java

import dev.postproxy.PostProxy;
import java.util.List;

PostProxy client = new PostProxy("YOUR_API_KEY");
var post = client.posts().create(
    "Hello World!",
    List.of("facebook", "instagram"),
    new CreatePostOptions()
        .media(List.of("https://example.com/image.jpg"))
        .draft(true)
);
System.out.println(post);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var post = await client.Posts.CreateAsync("Hello World!", ["facebook", "instagram"], new CreatePostOptions
{
    Media = ["https://example.com/image.jpg"],
    Draft = true,
});
Console.WriteLine(post);

Response:

{
  "id": "xyz789abc",
  "body": "Hello World!",
  "status": "draft",
  "scheduled_at": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "platforms": [
    {
      "platform": "facebook",
      "status": "published",
      "error": null,
      "params": null,
      "attempted_at": "2024-01-15T10:30:01.000Z"
    },
    {
      "platform": "instagram",
      "status": "published",
      "error": null,
      "params": {
        "format": "post"
      },
      "attempted_at": "2024-01-15T10:30:02.000Z"
    }
  ]
}

Your post will be published to the specified platforms almost immediately.

Step 3: Schedule a post (optional)

To schedule a post for later, add scheduled_at with an ISO 8601 timestamp.

cURL

curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {
         "body": "Hello World!",
         "scheduled_at": "2024-01-20T12:00:00Z"
       },
       "profiles": ["facebook", "instagram"],
       "media": ["https://example.com/image.jpg"]
     }'

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const post = await client.posts.create("Hello World!", ["facebook", "instagram"], {
  media: ["https://example.com/image.jpg"],
  scheduledAt: "2024-01-20T12:00:00Z",
});
console.log(post);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
post = await client.posts.create(
    "Hello World!",
    ["facebook", "instagram"],
    media=["https://example.com/image.jpg"],
    scheduled_at="2024-01-20T12:00:00Z",
)
print(post)

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  post, _ := client.Posts.Create("Hello World!", []string{"facebook", "instagram"}, &postproxy.CreatePostOptions{
    Media:       []string{"https://example.com/image.jpg"},
    ScheduledAt: "2024-01-20T12:00:00Z",
  })
  fmt.Println(post)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
post = client.posts.create(
  "Hello World!",
  profiles: ["facebook", "instagram"],
  media: ["https://example.com/image.jpg"],
  scheduled_at: "2024-01-20T12:00:00Z"
)
puts post

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$post = $client->posts->create("Hello World!", ["facebook", "instagram"], [
    "media" => ["https://example.com/image.jpg"],
    "scheduled_at" => "2024-01-20T12:00:00Z",
]);
print_r($post);

Java

import dev.postproxy.PostProxy;
import java.util.List;

PostProxy client = new PostProxy("YOUR_API_KEY");
var post = client.posts().create(
    "Hello World!",
    List.of("facebook", "instagram"),
    new CreatePostOptions()
        .media(List.of("https://example.com/image.jpg"))
        .scheduledAt("2024-01-20T12:00:00Z")
);
System.out.println(post);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var post = await client.Posts.CreateAsync("Hello World!", ["facebook", "instagram"], new CreatePostOptions
{
    Media = ["https://example.com/image.jpg"],
    ScheduledAt = "2024-01-20T12:00:00Z",
});
Console.WriteLine(post);

Response:

{
  "id": "xyz789abc",
  "body": "Hello World!",
  "status": "scheduled",
  "scheduled_at": "2024-01-20T12:00:00.000Z",
  "created_at": "2024-01-15T10:30:00.000Z",
  "platforms": [
    {
      "platform": "facebook",
      "status": "processing",
      "error": null,
      "params": null,
      "attempted_at": null
    },
    {
      "platform": "instagram",
      "status": "processing",
      "error": null,
      "params": {
        "format": "post"
      },
      "attempted_at": null
    }
  ]
}

Postproxy handles the scheduling - your post will be published at the specified time.

Publish with MCP

Prefer to publish from an AI agent? Point any MCP client at Postproxy’s hosted server — no install required. For Claude Code:

claude mcp add --transport http postproxy \
https://mcp.postproxy.dev/mcp?api_key=YOUR_KEY

Replace YOUR_KEY with your API key, then prompt your agent with something like “Check my Postproxy authentication status” or “Publish a post to X and LinkedIn.” See the MCP Server guide for the local npm package and full tool list.

Publish with no-code tools

If you’d rather wire Postproxy into an automation tool, it plugs into the platforms you already use:

• Zapier — trigger a Zap, then use the Create Post, Schedule Post, or Create Draft actions.
• Make — drop Postproxy into a scenario as a publishing step.
• n8n — build production publishing pipelines with the Postproxy node.
• Needle — publish from Needle workflows and collections via the official MCP connector.

Each connects with the same API key from the first step.

Publish with OpenClaw

Running OpenClaw? Install the Postproxy skill from ClawHub and it can publish, schedule, and manage content from chat:

npx clawhub@latest install postproxy

Drop your API key in ~/.openclaw/.env, then prompt OpenClaw to publish to any connected platform. See the OpenClaw guide for setup details.

Supported platforms

Each platform has its own API guide covering supported formats, media limits, and platform-specific parameters:

• Facebook
• Instagram
• TikTok
• LinkedIn
• YouTube
• X (Twitter)
• Threads
• Pinterest
• Bluesky
• Telegram
• Google Business

Media handling

When creating a post with media, provide URLs to your images or videos. Postproxy downloads and processes the media, then uploads it to each platform according to their requirements.

Each platform has specific constraints for media (file size, formats, dimensions). See Platform Parameters for details.

Rate limits and retries

Social networks have rate limits that Postproxy handles automatically. If a post hits a rate limit, Postproxy queues it and retries when possible. You don’t need to implement retry logic in your application.