Social media publishing API

One request, several networks

A post is text, media and a list of targets. Each target is a connected account, with its own text and typed options when a network needs them.

curl

curl -X POST https://trend.guru/api/v1/posts \
  -H "Authorization: Bearer $TRENDGURU_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-video-0001" \
  -d '{
    "text": "Launch day.",
    "media": [{ "url": "https://cdn.example.com/launch.mp4" }],
    "publishAt": "now",
    "targets": [
      { "accountId": "INSTAGRAM_ACCOUNT_ID" },
      { "accountId": "TIKTOK_ACCOUNT_ID", "options": { "privacy": "public" } },
      { "accountId": "YOUTUBE_ACCOUNT_ID", "options": { "title": "Launch day", "visibility": "public" } }
    ]
  }'

Response

201 Created
{
  "object": "post",
  "id": "...",
  "status": "published",
  "targets": [
    { "accountId": "INSTAGRAM_ACCOUNT_ID", "platform": "instagram", "status": "published",
      "url": "https://www.instagram.com/reel/..." },
    { "accountId": "TIKTOK_ACCOUNT_ID", "platform": "tiktok", "status": "published",
      "url": "https://www.tiktok.com/@.../video/..." },
    { "accountId": "YOUTUBE_ACCOUNT_ID", "platform": "youtube", "status": "published",
      "url": "https://www.youtube.com/watch?v=..." }
  ]
}

With publishAt "now" the call waits for the networks and returns the result for each target. Under load a target can come back as publishing; the final result then arrives by webhook or GET /v1/posts/{id}.

The same flow in Node.js and Python: list the connected accounts, then create a post.

Node.js (fetch)

const base = 'https://trend.guru/api/v1';
const headers = { Authorization: `Bearer ${process.env.TRENDGURU_KEY}`, 'Content-Type': 'application/json' };

const accounts = await fetch(`${base}/accounts`, { headers }).then((r) => r.json());
const accountId = accounts.data[0].id;

const res = await fetch(`${base}/posts`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({ text: 'Hello from the API', targets: [{ accountId }], publishAt: 'now' }),
});
const post = await res.json();
if (!res.ok) throw new Error(`${post.error.code}: ${post.error.message}`);
console.log(post.id, post.status, post.targets.map((t) => t.url));

Python (requests)

import os, uuid, requests

base = "https://trend.guru/api/v1"
headers = {"Authorization": f"Bearer {os.environ['TRENDGURU_KEY']}"}

accounts = requests.get(f"{base}/accounts", headers=headers).json()
account_id = accounts["data"][0]["id"]

res = requests.post(
    f"{base}/posts",
    headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
    json={"text": "Hello from the API", "targets": [{"accountId": account_id}], "publishAt": "now"},
)
post = res.json()
if not res.ok:
    raise SystemExit(f"{post['error']['code']}: {post['error']['message']}")
print(post["id"], post["status"], [t["url"] for t in post["targets"]])

What you get

Scheduling

publishAt is "now", an ISO 8601 time with an optional timezone, or left out for a draft. Every target reports its own status.

Typed options per network

Instagram Reel or Story, TikTok privacy, YouTube title and visibility, X threads and polls, LinkedIn documents. Options are validated strictly: an unknown key is rejected with 400 invalid_options.

Media upload

Pass a public URL or upload the file: POST /v1/media returns an upload URL you PUT the bytes to.

Webhooks with signatures

post.*, target.*, account.* and analytics.synced events, signed with HMAC-SHA256 in the TrendGuru-Signature header. Failed deliveries retry after 1m, 5m, 15m, 1h, 3h and 12h.

Idempotency

Send an Idempotency-Key with POST /v1/posts, and a retry within 24 hours returns the first result instead of posting twice.

Validation and dry run

POST /v1/posts/validate checks a post against each network's rules; dryRun: true returns the post that would be created without saving it.

Analytics

Likes, comments, shares, saves, views, impressions and reach per post, refreshed hourly for 14 days, plus followers per account.

Connecting accounts by API

POST /v1/connections returns an authorization URL for the network's own sign-in. On paid plans, headless mode lets you send your own users there and bring them back to your app.

Scoped keys and test keys

A key carries scopes, an optional profile allow-list and an optional expiry. A tg_test_ key works like a live key and is labelled test, for your staging environment.

Request logs

Every API request and publishing attempt is kept for 30 days and can be read with GET /v1/logs.

The whole public API is described in one machine-readable file for SDK generators, API clients and automation tools: OpenAPI 3.1 specification (openapi.json)

Limits

Network rules still apply: Instagram and TikTok need media, YouTube needs a video, X counts 280 characters. Validation reports this before anything is sent.

Pricing: pay per post

1 credit = $0.01 = one post to one network. A post sent to five networks costs 5 credits. The Free plan gives 50 credits every month, no card needed.

The API, webhooks and analytics are included in every plan, Free too.

Credit packs are one-time purchases on any plan and never expire: 1,000 credits for $10, 5,000 credits for $50, 25,000 credits for $250. Plan credits renew every month and the unused part expires; plan credits are spent first.

On X a tweet costs 10 credits, or 100 with a link, because X bills every write; X is open on paid plans. Credits are taken when a post is sent and come back if it finally fails.

Questions

What is the TrendGuru API?

A REST API that publishes and schedules posts to Instagram, TikTok, YouTube, Facebook Pages, LinkedIn and X (X on paid plans) from one request, with webhooks, analytics and an OpenAPI 3.1 description.

How much does a post cost?

1 credit, which is $0.01, for one post to one network. A post to five networks costs 5 credits. On X a tweet costs 10 credits, or 100 with a link.

Is there a free plan?

Yes. Free gives 50 credits every month with API keys, webhooks and analytics, and no card. X needs a paid plan.

How do I test without publishing?

Send dryRun: true or call POST /v1/posts/validate. Both check the post against every network's rules; nothing is published and no credits are taken.

Is there an SDK?

The API is plain JSON over HTTPS, so any HTTP client works. For a typed client, generate one from the OpenAPI 3.1 file at https://trend.guru/openapi.json.

Does it work with n8n, Zapier or Make?

Yes, through their HTTP request nodes. Send a fresh Idempotency-Key for each post so a retry never creates a duplicate.

What happens when a network rejects a post?

The target gets a structured error with a category. Temporary errors are retried up to three times, the final result arrives by webhook, and the credit for a target that finally fails comes back.

Do I need my own developer apps at the networks?

No. On trend.guru, accounts connect through TrendGuru's apps with each network's own sign-in.

Can an AI assistant use it?

Yes. The same actions are open to assistants through the TrendGuru MCP server at https://trend.guru/api/mcp.

Start with a free key

Sign up, create a key under API keys and connect a social account. The first 50 credits every month are free.

Get a free keyRead the API reference