# TrendGuru — full product description (last updated 2026-09-05)

## What TrendGuru is
TrendGuru is a social media publishing API and dashboard. A developer, agency, SaaS product or AI agent connects social accounts through OAuth once and then publishes or schedules posts to all of them with one HTTP request. TrendGuru handles each platform's upload flow, token refresh, retries, duplicate protection, webhooks and analytics. Site: https://trend.guru. API base URL: https://trend.guru/api/v1.

## Who it is for
- Developers and SaaS teams that need social publishing inside their product without integrating six platform APIs.
- Marketing agencies and content operations that run many brands and accounts.
- Automation builders (n8n, Zapier, Make) and AI-agent builders that need a plain JSON API with idempotency.
- Teams moving off a per-account-priced publishing API who want the same job done self-hosted or free during beta.

## Who it is not for
- Scraping public social data, growth hacks or automation that violates platform rules. TrendGuru only publishes to accounts that their owners connected through OAuth.
- Teams that need inbox (comments, DMs) or paid ads management today; those are not part of the beta.

## Supported platforms (wave 1)
- Instagram: feed image, carousel (up to 10), Reels, Stories; first comment, collaborators, user tags, custom cover, comments toggle, location.
- TikTok: video posts and photo carousels (up to 35); privacy level, comment/duet/stitch toggles, commercial content disclosure, inbox draft mode, AI label.
- YouTube: resumable video upload with title, description, tags, category, visibility, made-for-kids, synthetic media flag, playlist, first comment.
- Facebook Pages: feed text and links, photos, multi-photo posts, video, Reels, Stories, first comment, draft to Publishing Tools.
- X (Twitter): tweets with up to 4 images or one video/GIF, threads, polls, reply settings, replies and quote tweets. Requires the customer's own X developer app on a paid X API tier.
- LinkedIn: personal and organization posts, single and multiple images, video, PDF documents, polls, reshares, first comment, link previews.
Planned (wave 2): Threads, Telegram, Pinterest, Reddit, Bluesky.

## How it works
1. Create a profile (a brand or client). A profile holds one account per platform.
2. POST /v1/connections with platform and profileId returns an authorization URL. The user authorizes; TrendGuru stores encrypted tokens. Facebook and Instagram-via-Facebook add a Page selection step.
3. Create an API key in the dashboard (Bearer token; can be read-only and scoped to profiles).
4. POST /v1/posts with text, media (public URLs or media ids from POST /v1/media), targets[] (accountId + optional text/media/options) and publishAt ("now" or ISO 8601).
5. The publishing worker publishes at the right time, retries transient errors up to three times, records per-target status, remoteId and url, and fires webhooks.
6. Analytics are synced hourly for posts published in the last 14 days; follower counts daily.

## API surface
Profiles: GET/POST /v1/profiles, GET/PATCH/DELETE /v1/profiles/{id}.
Connections: GET /v1/platforms, POST /v1/connections, GET /v1/connections/{id}, POST /v1/connections/{id}/complete.
Accounts: GET /v1/accounts, GET /v1/accounts/health, GET/PATCH/DELETE /v1/accounts/{id}, GET /v1/accounts/{id}/health, GET /v1/accounts/{id}/followers, GET /v1/accounts/{id}/posts, POST /v1/accounts/{id}/refresh.
Posts: GET/POST /v1/posts, GET/PATCH/DELETE /v1/posts/{id}, POST /v1/posts/{id}/retry, POST /v1/posts/{id}/unpublish, POST /v1/posts/validate, POST /v1/posts/batch.
Media: POST /v1/media (+ PUT upload URL), POST /v1/media/upload, GET /v1/media, GET/DELETE /v1/media/{id}.
Webhooks: GET/POST /v1/webhooks, GET/PATCH/DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test, GET /v1/webhooks/deliveries, POST /v1/webhooks/deliveries/{id}/redeliver, GET /v1/webhooks/events.
Analytics: GET /v1/analytics/posts, GET /v1/analytics/posts/{id}/timeline, GET /v1/analytics/daily, GET /v1/analytics/overview.
Keys and logs: GET /v1/me, GET/POST/DELETE /v1/api-keys, GET /v1/logs.

## Reliability and safety
- Idempotency: an Idempotency-Key header makes retries safe for 24 hours; identical content to the same account within 24 hours is rejected with 409 DUPLICATE_CONTENT.
- Errors: one JSON shape { error: { type, code, message, status, details, requestId } }; per-target error.category (auth_expired, user_content, user_abuse, account_issue, platform_rejected, platform_error, platform_rate_limit, quota_exhausted, system_error, unknown) and errorSource (user, platform, system).
- Rate limit: 600 requests per minute per API key by default, reported in RateLimit-* headers.
- Tokens: encrypted at rest with AES-256-GCM using a server-side key; refreshed before expiry; a token the platform rejects sets needsReconnection and fires account.disconnected.
- API keys: prefix tg_live_ or tg_test_, stored as SHA-256 hashes, shown once, with granular scopes (posts, accounts, media, webhooks, analytics, logs), optional profile allow-list and expiry.
- Logs: every API request and publish attempt is logged with method, path, status, latency and message for 30 days.

## Pricing
Free during the public beta: unlimited profiles, accounts, posts, webhooks and analytics; no card required. Paid plans will be priced per connected account and announced in the dashboard before they start. X API costs are the customer's own (X developer app).

## Compatibility
The resource model is the common one for publishing APIs (profiles, accounts, posts with targets[] and typed options, media uploads, webhooks with HMAC signatures), so most integrations switch by changing the base URL and the API key.

## Hosting
Hosted at https://trend.guru. Self-hosting: one service plus a database on your own server; one process serves API, dashboard and worker, and it needs the operator's own OAuth apps at Meta, TikTok, Google, X and LinkedIn.

## Contact
Dashboard: https://trend.guru/dashboard. Documentation: https://trend.guru/docs. FAQ: https://trend.guru/faq/.