Examples

Ready-to-use examples for the most common API workflows. Each example includes code in 8 languages with full request and response samples.

List posts

Fetch a paginated list of your posts.

curl -X GET "https://api.postproxy.dev/api/posts?page=0&per_page=5" \
     -H "Authorization: Bearer YOUR_API_KEY"

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const posts = await client.posts.list({ page: 0, perPage: 5 });
console.log(posts);

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
posts = await client.posts.list(page=0, per_page=5)
print(posts)

package main

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

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  page := 0
  perPage := 5
  posts, _ := client.Posts.List(context.Background(), &postproxy.PostListOptions{
    Page:    &page,
    PerPage: &perPage,
  })
  fmt.Println(posts)
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
posts = client.posts.list(page: 0, per_page: 5)
puts posts

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");
$posts = $client->posts()->list(page: 0, perPage: 5);
print_r($posts);

import dev.postproxy.sdk.PostProxy;
import dev.postproxy.sdk.param.ListPostsParams;

var client = PostProxy.builder("YOUR_API_KEY").build();
var posts = client.posts().list(ListPostsParams.builder()
    .page(0)
    .perPage(5)
    .build());
System.out.println(posts);

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
var posts = await client.Posts.ListAsync(new ListPostsParams
{
    Page = 0,
    PerPage = 5,
});
Console.WriteLine(posts);

Response:

{
  "total": 42,
  "page": 0,
  "per_page": 5,
  "data": [
    {
      "id": "abc123xyz",
      "body": "Check out our latest update!",
      "status": "processed",
      "scheduled_at": null,
      "created_at": "2024-01-15T10:30:00.000Z",
      "platforms": [
        {
          "platform": "twitter",
          "status": "published",
          "params": null,
          "attempted_at": "2024-01-15T10:30:01.000Z",
          "insights": {
            "impressions": 1523,
            "on": "2024-01-15T18:00:00.000Z"
          }
        }
      ]
    }
  ]
}

See Posts API Reference for all query parameters including filtering by status, platform, and schedule date.

Get a single post

Retrieve full details for a post including media, platform results, and insights.

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

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const post = await client.posts.get("abc123xyz");
console.log(post);

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
post = await client.posts.get("abc123xyz")
print(post)

package main

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

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  post, _ := client.Posts.Get(context.Background(), "abc123xyz", nil)
  fmt.Println(post)
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
post = client.posts.get("abc123xyz")
puts post

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");
$post = $client->posts()->get("abc123xyz");
print_r($post);

import dev.postproxy.sdk.PostProxy;

var client = PostProxy.builder("YOUR_API_KEY").build();
var post = client.posts().get("abc123xyz");
System.out.println(post);

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
var post = await client.Posts.GetAsync("abc123xyz");
Console.WriteLine(post);

Response:

{
  "id": "abc123xyz",
  "body": "Check out our latest update!",
  "status": "processed",
  "scheduled_at": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "media": [
    {
      "id": "med123",
      "status": "processed",
      "error_message": null,
      "content_type": "image/jpeg",
      "source_url": "https://example.com/photo.jpg",
      "url": "https://cdn.postproxy.dev/uploads/photo.jpg"
    }
  ],
  "platforms": [
    {
      "platform": "twitter",
      "status": "published",
      "params": null,
      "attempted_at": "2024-01-15T10:30:01.000Z",
      "insights": {
        "impressions": 1523,
        "on": "2024-01-15T18:00:00.000Z"
      }
    },
    {
      "platform": "instagram",
      "status": "published",
      "params": {
        "format": "post"
      },
      "attempted_at": "2024-01-15T10:30:02.000Z",
      "insights": {
        "impressions": 3842,
        "on": "2024-01-15T18:00:00.000Z"
      }
    }
  ]
}

Create a post

Publish a simple post with an image to a single platform.

curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {
         "body": "Exciting news — we just launched our new feature!"
       },
       "profiles": ["twitter"],
       "media": ["https://example.com/launch.jpg"]
     }'

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const post = await client.posts.create(
  "Exciting news — we just launched our new feature!",
  ["twitter"],
  { media: ["https://example.com/launch.jpg"] },
);
console.log(post);

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
post = await client.posts.create(
    "Exciting news — we just launched our new feature!",
    ["twitter"],
    media=["https://example.com/launch.jpg"],
)
print(post)

package main

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

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  post, _ := client.Posts.Create(context.Background(), "Exciting news — we just launched our new feature!", []string{"twitter"}, &postproxy.PostCreateOptions{
    Media: []string{"https://example.com/launch.jpg"},
  })
  fmt.Println(post)
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
post = client.posts.create(
  "Exciting news — we just launched our new feature!",
  profiles: ["twitter"],
  media: ["https://example.com/launch.jpg"]
)
puts post

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");
$post = $client->posts()->create(
    "Exciting news — we just launched our new feature!",
    ["twitter"],
    media: ["https://example.com/launch.jpg"],
);
print_r($post);

import dev.postproxy.sdk.PostProxy;
import dev.postproxy.sdk.param.CreatePostParams;
import java.util.List;

var client = PostProxy.builder("YOUR_API_KEY").build();
var post = client.posts().create(CreatePostParams.builder()
    .body("Exciting news — we just launched our new feature!")
    .profiles(List.of("twitter"))
    .media(List.of("https://example.com/launch.jpg"))
    .build());
System.out.println(post);

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
var post = await client.Posts.CreateAsync(new CreatePostParams
{
    Body = "Exciting news — we just launched our new feature!",
    Profiles = ["twitter"],
    Media = ["https://example.com/launch.jpg"],
});
Console.WriteLine(post);

Response:

{
  "id": "xyz789abc",
  "body": "Exciting news — we just launched our new feature!",
  "status": "processed",
  "scheduled_at": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "platforms": [
    {
      "platform": "twitter",
      "status": "published",
      "error": null,
      "params": null,
      "attempted_at": "2024-01-15T10:30:01.000Z"
    }
  ]
}

Cross-post to multiple platforms

Post a video to YouTube, TikTok, and Instagram simultaneously with platform-specific parameters for each.

curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {
         "body": "New video is live!"
       },
       "profiles": ["youtube", "tiktok", "instagram"],
       "media": ["https://example.com/video.mp4"],
       "platforms": {
         "youtube": {
           "title": "Getting Started Tutorial",
           "privacy_status": "public"
         },
         "tiktok": {
           "format": "video",
           "privacy_status": "PUBLIC_TO_EVERYONE"
         },
         "instagram": {
           "format": "reel",
           "first_comment": "Full tutorial on our channel!"
         }
       }
     }'

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const post = await client.posts.create(
  "New video is live!",
  ["youtube", "tiktok", "instagram"],
  {
    media: ["https://example.com/video.mp4"],
    platforms: {
      youtube: { title: "Getting Started Tutorial", privacy_status: "public" },
      tiktok: { format: "video", privacy_status: "PUBLIC_TO_EVERYONE" },
      instagram: { format: "reel", first_comment: "Full tutorial on our channel!" },
    },
  },
);
console.log(post);

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
post = await client.posts.create(
    "New video is live!",
    ["youtube", "tiktok", "instagram"],
    media=["https://example.com/video.mp4"],
    platforms={
        "youtube": {"title": "Getting Started Tutorial", "privacy_status": "public"},
        "tiktok": {"format": "video", "privacy_status": "PUBLIC_TO_EVERYONE"},
        "instagram": {"format": "reel", "first_comment": "Full tutorial on our channel!"},
    },
)
print(post)

package main

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

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  title := "Getting Started Tutorial"
  ytPrivacy := postproxy.YouTubePrivacy("public")
  ttFormat := postproxy.TikTokFormat("video")
  ttPrivacy := postproxy.TikTokPrivacy("PUBLIC_TO_EVERYONE")
  igFormat := postproxy.InstagramFormat("reel")
  firstComment := "Full tutorial on our channel!"

  post, _ := client.Posts.Create(context.Background(), "New video is live!", []string{"youtube", "tiktok", "instagram"}, &postproxy.PostCreateOptions{
    Media: []string{"https://example.com/video.mp4"},
    Platforms: &postproxy.PlatformParams{
      YouTube: &postproxy.YouTubeParams{
        Title:         &title,
        PrivacyStatus: &ytPrivacy,
      },
      TikTok: &postproxy.TikTokParams{
        Format:        &ttFormat,
        PrivacyStatus: &ttPrivacy,
      },
      Instagram: &postproxy.InstagramParams{
        Format:       &igFormat,
        FirstComment: &firstComment,
      },
    },
  })
  fmt.Println(post)
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
post = client.posts.create(
  "New video is live!",
  profiles: ["youtube", "tiktok", "instagram"],
  media: ["https://example.com/video.mp4"],
  platforms: {
    youtube: { title: "Getting Started Tutorial", privacy_status: "public" },
    tiktok: { format: "video", privacy_status: "PUBLIC_TO_EVERYONE" },
    instagram: { format: "reel", first_comment: "Full tutorial on our channel!" }
  }
)
puts post

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");
$post = $client->posts()->create(
    "New video is live!",
    ["youtube", "tiktok", "instagram"],
    media: ["https://example.com/video.mp4"],
    platforms: [
        "youtube" => ["title" => "Getting Started Tutorial", "privacy_status" => "public"],
        "tiktok" => ["format" => "video", "privacy_status" => "PUBLIC_TO_EVERYONE"],
        "instagram" => ["format" => "reel", "first_comment" => "Full tutorial on our channel!"],
    ],
);
print_r($post);

import dev.postproxy.sdk.PostProxy;
import dev.postproxy.sdk.param.*;
import dev.postproxy.sdk.model.*;
import java.util.List;

var client = PostProxy.builder("YOUR_API_KEY").build();
var post = client.posts().create(CreatePostParams.builder()
    .body("New video is live!")
    .profiles(List.of("youtube", "tiktok", "instagram"))
    .media(List.of("https://example.com/video.mp4"))
    .platforms(PlatformParams.builder()
        .youtube(YouTubeParams.builder()
            .title("Getting Started Tutorial")
            .privacyStatus(YouTubePrivacy.PUBLIC)
            .build())
        .tiktok(TikTokParams.builder()
            .format(TikTokFormat.VIDEO)
            .privacyStatus(TikTokPrivacy.PUBLIC_TO_EVERYONE)
            .build())
        .instagram(InstagramParams.builder()
            .format(InstagramFormat.REEL)
            .firstComment("Full tutorial on our channel!")
            .build())
        .build())
    .build());
System.out.println(post);

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
var post = await client.Posts.CreateAsync(new CreatePostParams
{
    Body = "New video is live!",
    Profiles = ["youtube", "tiktok", "instagram"],
    Media = ["https://example.com/video.mp4"],
    Platforms = new PlatformParams
    {
        YouTube = new YouTubeParams
        {
            Title = "Getting Started Tutorial",
            PrivacyStatus = YouTubePrivacy.Public,
        },
        TikTok = new TikTokParams
        {
            Format = TikTokFormat.Video,
            PrivacyStatus = TikTokPrivacy.PublicToEveryone,
        },
        Instagram = new InstagramParams
        {
            Format = InstagramFormat.Reel,
            FirstComment = "Full tutorial on our channel!",
        },
    },
});
Console.WriteLine(post);

Response:

{
  "id": "vid456abc",
  "body": "New video is live!",
  "status": "processed",
  "scheduled_at": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "platforms": [
    {
      "platform": "youtube",
      "status": "processing",
      "params": {
        "title": "Getting Started Tutorial",
        "privacy_status": "public",
        "made_for_kids": false
      },
      "attempted_at": "2024-01-15T10:30:01.000Z"
    },
    {
      "platform": "tiktok",
      "status": "processing",
      "params": {
        "format": "video",
        "privacy_status": "PUBLIC_TO_EVERYONE"
      },
      "attempted_at": "2024-01-15T10:30:02.000Z"
    },
    {
      "platform": "instagram",
      "status": "published",
      "params": {
        "format": "reel",
        "first_comment": "Full tutorial on our channel!"
      },
      "attempted_at": "2024-01-15T10:30:03.000Z"
    }
  ]
}

Each platform gets its own params — YouTube gets a title and privacy setting, TikTok gets its privacy status, and Instagram is published as a reel with a first comment. See Platform Parameters for all available options.

Create a thread

Post a multi-part thread to X (Twitter) and Threads. Each item in the thread array becomes a reply to the previous post. Thread children can also include media.

curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {
         "body": "1/ Here is a thread about our product launch"
       },
       "profiles": ["twitter", "threads"],
       "thread": [
         { "body": "2/ First, we built the foundation..." },
         { "body": "3/ Then we added the key features...", "media": ["https://example.com/screenshot.jpg"] },
         { "body": "4/ And finally, we launched! Check it out at example.com" }
       ]
     }'

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const post = await client.posts.create(
  "1/ Here is a thread about our product launch",
  ["twitter", "threads"],
  {
    thread: [
      { body: "2/ First, we built the foundation..." },
      { body: "3/ Then we added the key features...", media: ["https://example.com/screenshot.jpg"] },
      { body: "4/ And finally, we launched! Check it out at example.com" },
    ],
  },
);
console.log(post);

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
post = await client.posts.create(
    "1/ Here is a thread about our product launch",
    ["twitter", "threads"],
    thread=[
        {"body": "2/ First, we built the foundation..."},
        {"body": "3/ Then we added the key features...", "media": ["https://example.com/screenshot.jpg"]},
        {"body": "4/ And finally, we launched! Check it out at example.com"},
    ],
)
print(post)

package main

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

func main() {
  client := postproxy.New("YOUR_API_KEY")
  post, _ := client.Posts.Create("1/ Here is a thread about our product launch", []string{"twitter", "threads"}, &postproxy.CreatePostOptions{
    Thread: []postproxy.ThreadPost{
      {Body: "2/ First, we built the foundation..."},
      {Body: "3/ Then we added the key features...", Media: []string{"https://example.com/screenshot.jpg"}},
      {Body: "4/ And finally, we launched! Check it out at example.com"},
    },
  })
  fmt.Println(post)
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
post = client.posts.create(
  "1/ Here is a thread about our product launch",
  profiles: ["twitter", "threads"],
  thread: [
    { body: "2/ First, we built the foundation..." },
    { body: "3/ Then we added the key features...", media: ["https://example.com/screenshot.jpg"] },
    { body: "4/ And finally, we launched! Check it out at example.com" }
  ]
)
puts post

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$post = $client->posts->create("1/ Here is a thread about our product launch", ["twitter", "threads"], [
    "thread" => [
        ["body" => "2/ First, we built the foundation..."],
        ["body" => "3/ Then we added the key features...", "media" => ["https://example.com/screenshot.jpg"]],
        ["body" => "4/ And finally, we launched! Check it out at example.com"],
    ],
]);
print_r($post);

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

PostProxy client = new PostProxy("YOUR_API_KEY");
var post = client.posts().create(
    "1/ Here is a thread about our product launch",
    List.of("twitter", "threads"),
    new CreatePostOptions()
        .thread(List.of(
            new ThreadPost("2/ First, we built the foundation..."),
            new ThreadPost("3/ Then we added the key features...").media(List.of("https://example.com/screenshot.jpg")),
            new ThreadPost("4/ And finally, we launched! Check it out at example.com")
        ))
);
System.out.println(post);

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var post = await client.Posts.CreateAsync("1/ Here is a thread about our product launch", ["twitter", "threads"], new CreatePostOptions
{
    Thread = [
        new ThreadPost { Body = "2/ First, we built the foundation..." },
        new ThreadPost { Body = "3/ Then we added the key features...", Media = ["https://example.com/screenshot.jpg"] },
        new ThreadPost { Body = "4/ And finally, we launched! Check it out at example.com" },
    ],
});
Console.WriteLine(post);

Response:

{
  "id": "thr123abc",
  "body": "1/ Here is a thread about our product launch",
  "status": "processed",
  "scheduled_at": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "platforms": [
    { "platform": "twitter", "status": "processing" },
    { "platform": "threads", "status": "processing" }
  ],
  "thread": [
    { "id": "def456", "body": "2/ First, we built the foundation..." },
    { "id": "ghi789", "body": "3/ Then we added the key features..." },
    { "id": "jkl012", "body": "4/ And finally, we launched! Check it out at example.com" }
  ]
}

Schedule a post

Set scheduled_at with an ISO 8601 timestamp to publish a post at a specific time. Postproxy handles the scheduling automatically.

curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {
         "body": "Big announcement coming at noon!",
         "scheduled_at": "2024-01-20T12:00:00Z"
       },
       "profiles": ["twitter", "linkedin"]
     }'

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const post = await client.posts.create(
  "Big announcement coming at noon!",
  ["twitter", "linkedin"],
  { scheduledAt: "2024-01-20T12:00:00Z" },
);
console.log(post);

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
post = await client.posts.create(
    "Big announcement coming at noon!",
    ["twitter", "linkedin"],
    scheduled_at="2024-01-20T12:00:00Z",
)
print(post)

package main

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

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  scheduledAt := "2024-01-20T12:00:00Z"
  post, _ := client.Posts.Create(context.Background(), "Big announcement coming at noon!", []string{"twitter", "linkedin"}, &postproxy.PostCreateOptions{
    ScheduledAt: &scheduledAt,
  })
  fmt.Println(post)
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
post = client.posts.create(
  "Big announcement coming at noon!",
  profiles: ["twitter", "linkedin"],
  scheduled_at: "2024-01-20T12:00:00Z"
)
puts post

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");
$post = $client->posts()->create(
    "Big announcement coming at noon!",
    ["twitter", "linkedin"],
    scheduledAt: "2024-01-20T12:00:00Z",
);
print_r($post);

import dev.postproxy.sdk.PostProxy;
import dev.postproxy.sdk.param.CreatePostParams;
import java.util.List;

var client = PostProxy.builder("YOUR_API_KEY").build();
var post = client.posts().create(CreatePostParams.builder()
    .body("Big announcement coming at noon!")
    .profiles(List.of("twitter", "linkedin"))
    .scheduledAt("2024-01-20T12:00:00Z")
    .build());
System.out.println(post);

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
var post = await client.Posts.CreateAsync(new CreatePostParams
{
    Body = "Big announcement coming at noon!",
    Profiles = ["twitter", "linkedin"],
    ScheduledAt = DateTimeOffset.Parse("2024-01-20T12:00:00Z"),
});
Console.WriteLine(post);

Response:

{
  "id": "sch789abc",
  "body": "Big announcement coming at noon!",
  "status": "scheduled",
  "scheduled_at": "2024-01-20T12:00:00.000Z",
  "created_at": "2024-01-15T10:30:00.000Z",
  "platforms": [
    {
      "platform": "twitter",
      "status": "processing",
      "error": null,
      "params": null,
      "attempted_at": null
    },
    {
      "platform": "linkedin",
      "status": "processing",
      "error": null,
      "params": null,
      "attempted_at": null
    }
  ]
}

The post status is scheduled and attempted_at is null until the scheduled time arrives.

Create a draft and publish later

Set draft: true to create a post without publishing it. Review the content, then publish it with a separate API call when ready.

Step 1: Create the draft.

curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {
         "body": "Draft content to review before posting",
         "draft": true
       },
       "profiles": ["instagram", "facebook"],
       "media": ["https://example.com/photo.jpg"]
     }'

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");

// Step 1: Create a draft
const post = await client.posts.create(
  "Draft content to review before posting",
  ["instagram", "facebook"],
  { media: ["https://example.com/photo.jpg"], draft: true },
);
console.log(post); // status: "draft"

// Step 2: Publish when ready
const published = await client.posts.publishDraft(post.id);
console.log(published); // status: "processing"

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")

# Step 1: Create a draft
post = await client.posts.create(
    "Draft content to review before posting",
    ["instagram", "facebook"],
    media=["https://example.com/photo.jpg"],
    draft=True,
)
print(post)  # status: "draft"

# Step 2: Publish when ready
published = await client.posts.publish_draft(post.id)
print(published)  # status: "processing"

package main

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

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  ctx := context.Background()

  // Step 1: Create a draft
  draft := true
  post, _ := client.Posts.Create(ctx, "Draft content to review before posting", []string{"instagram", "facebook"}, &postproxy.PostCreateOptions{
    Media: []string{"https://example.com/photo.jpg"},
    Draft: &draft,
  })
  fmt.Println(post) // status: "draft"

  // Step 2: Publish when ready
  published, _ := client.Posts.PublishDraft(ctx, post.ID, nil)
  fmt.Println(published) // status: "processing"
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")

# Step 1: Create a draft
post = client.posts.create(
  "Draft content to review before posting",
  profiles: ["instagram", "facebook"],
  media: ["https://example.com/photo.jpg"],
  draft: true
)
puts post # status: "draft"

# Step 2: Publish when ready
published = client.posts.publish_draft(post.id)
puts published # status: "processing"

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");

// Step 1: Create a draft
$post = $client->posts()->create(
    "Draft content to review before posting",
    ["instagram", "facebook"],
    media: ["https://example.com/photo.jpg"],
    draft: true,
);
print_r($post); // status: "draft"

// Step 2: Publish when ready
$published = $client->posts()->publishDraft($post->id);
print_r($published); // status: "processing"

import dev.postproxy.sdk.PostProxy;
import dev.postproxy.sdk.param.CreatePostParams;
import java.util.List;

var client = PostProxy.builder("YOUR_API_KEY").build();

// Step 1: Create a draft
var post = client.posts().create(CreatePostParams.builder()
    .body("Draft content to review before posting")
    .profiles(List.of("instagram", "facebook"))
    .media(List.of("https://example.com/photo.jpg"))
    .draft(true)
    .build());
System.out.println(post); // status: "draft"

// Step 2: Publish when ready
var published = client.posts().publishDraft(post.id());
System.out.println(published); // status: "processing"

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();

// Step 1: Create a draft
var post = await client.Posts.CreateAsync(new CreatePostParams
{
    Body = "Draft content to review before posting",
    Profiles = ["instagram", "facebook"],
    Media = ["https://example.com/photo.jpg"],
    Draft = true,
});
Console.WriteLine(post); // status: "draft"

// Step 2: Publish when ready
var published = await client.Posts.PublishDraftAsync(post.Id);
Console.WriteLine(published); // status: "processing"

Response:

{
  "id": "drf456abc",
  "body": "Draft content to review before posting",
  "status": "draft",
  "scheduled_at": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "platforms": [
    {
      "platform": "instagram",
      "status": "processing",
      "error": null,
      "params": { "format": "post" },
      "attempted_at": null
    },
    {
      "platform": "facebook",
      "status": "processing",
      "error": null,
      "params": null,
      "attempted_at": null
    }
  ]
}

Step 2: Publish when ready.

curl -X POST "https://api.postproxy.dev/api/posts/drf456abc/publish" \
     -H "Authorization: Bearer YOUR_API_KEY"

The SDK examples above show both steps. See Publish post for details.

Get post stats

Retrieve engagement metrics (impressions, likes, comments, etc.) for one or more posts. Stats are collected periodically and returned as time-series snapshots. You can filter by platform and date range.

curl -X GET "https://api.postproxy.dev/api/posts/stats?post_ids=abc123,def456&profiles=instagram,twitter" \
     -H "Authorization: Bearer YOUR_API_KEY"

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const stats = await client.posts.stats(["abc123", "def456"], {
  profiles: ["instagram", "twitter"],
});
console.log(stats);

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
stats = await client.posts.stats(
    ["abc123", "def456"],
    profiles=["instagram", "twitter"],
)
print(stats)

package main

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

func main() {
  client := postproxy.NewClient("YOUR_API_KEY")
  stats, _ := client.Posts.Stats(context.Background(), []string{"abc123", "def456"}, &postproxy.PostStatsOptions{
    Profiles: []string{"instagram", "twitter"},
  })
  fmt.Println(stats)
}

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
stats = client.posts.stats(
  ["abc123", "def456"],
  profiles: ["instagram", "twitter"]
)
puts stats

use PostProxy\Client;

$client = new Client("YOUR_API_KEY");
$stats = $client->posts()->stats(
    ['abc123', 'def456'],
    profiles: ['instagram', 'twitter'],
);
print_r($stats);

import dev.postproxy.sdk.PostProxy;
import dev.postproxy.sdk.param.GetStatsParams;
import java.util.List;

var client = PostProxy.builder("YOUR_API_KEY").build();
var stats = client.posts().stats(GetStatsParams.builder()
    .postIds(List.of("abc123", "def456"))
    .profiles(List.of("instagram", "twitter"))
    .build());
System.out.println(stats);

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
var stats = await client.Posts.StatsAsync(new PostStatsParams
{
    PostIds = ["abc123", "def456"],
    Profiles = ["instagram", "twitter"],
});
Console.WriteLine(stats);

Response:

{
  "data": {
    "abc123": {
      "platforms": [
        {
          "profile_id": "prof_abc",
          "platform": "instagram",
          "records": [
            {
              "stats": {
                "impressions": 1523,
                "likes": 102,
                "comments": 15,
                "saved": 11
              },
              "recorded_at": "2026-02-21T04:00:00Z"
            }
          ]
        }
      ]
    },
    "def456": {
      "platforms": [
        {
          "profile_id": "prof_def",
          "platform": "twitter",
          "records": [
            {
              "stats": {
                "impressions": 430,
                "likes": 22,
                "retweets": 5
              },
              "recorded_at": "2026-02-20T12:00:00Z"
            }
          ]
        }
      ]
    }
  }
}

The stats fields vary by platform. See Stats fields by platform for the full breakdown.

Get profiles

List all connected social media profiles in your account.

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

import PostProxy from "postproxy-sdk";

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

from postproxy import PostProxy

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

package main

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

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

require "postproxy"

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

use PostProxy\Client;

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

import dev.postproxy.sdk.PostProxy;

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

using PostProxy;

var client = PostProxyClient.Builder("YOUR_API_KEY").Build();
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
    },
    {
      "id": "prof456ghi",
      "name": "@mycompany",
      "platform": "twitter",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 55
    }
  ]
}

Use the id from the response when creating posts with specific profiles. You can also use platform names like "twitter" as a shorthand — Postproxy will pick the first connected profile for that platform.

Connect a new profile

Use the Initialize Connection endpoint to generate an OAuth URL for connecting a new social media account. Redirect the user to the returned URL — after they authenticate, they’ll be sent back to your redirect_url and the profile is created automatically.

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"
     }'

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);

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)

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)
}

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

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;

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());

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://postproxy.com/partner_connect/inv789xyz",
  "success": true
}

Redirect the user to the url in the response. Supported platforms: facebook, instagram, tiktok, linkedin, youtube, twitter, threads, pinterest. See Initialize Connection for full details.