Social Media

Social is the distribution primitive. Naive wraps a social media service behind a consistent API so agents can connect social media accounts, create and publish posts across multiple platforms, schedule content, and retrieve analytics — all without custom OAuth flows or frontend components.

CLI First

# Activate and connect a platform
naive social activate
naive social connect --platform twitter --redirect-url https://your-app.com/callback

# Create and publish a post
naive social post "Launching our new product today" --platforms twitter,linkedin --publish

Tools

Tool	Type	Description	Cost
`social_activate`	Setup	Activate social media for the company	Free
`social_connect`	Setup	Get OAuth URL for a single platform	Free
`social_portal`	Setup	Get portal URL for multi-platform connect	Free
`social_status`	Info	Check activation + connected accounts	Free
`social_accounts`	Info	List connected accounts	Free
`social_sync`	Info	Sync connected accounts	Free
`social_create_post`	Core	Create and optionally publish a post	1 credit (if publishing)
`social_publish_post`	Core	Publish a draft	1 credit
`social_upload`	Core	Upload media from URL	Free
`social_list_posts`	Info	List posts with status filter	Free
`social_get_post`	Info	Get post details	Free
`social_edit_post`	Core	Edit a draft post	Free
`social_delete_post`	Core	Delete a post	Free
`social_post_analytics`	Info	Get post performance metrics	Free
`social_post_comments`	Info	Get post comments	Free
`social_account_analytics`	Info	Get account-level analytics	Free
`social_disconnect`	Setup	Disconnect an account	Free

Activation

Before posting, social media must be activated for the company.

curl -X POST https://api.usenaive.ai/v1/social/activate \
  -H "Authorization: Bearer nv_sk_your_key"

Response:

{
  "activated": true,
  "team_count": 1,
  "bundle_team_id": "team-uuid"
}

Connecting Accounts

The API returns an OAuth URL. The user or agent opens this URL in a browser to authorize the social account. No custom frontend is needed.

Single Platform

curl -X POST https://api.usenaive.ai/v1/social/connect \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"platform": "TWITTER", "redirect_url": "https://your-app.com/callback"}'

Response:

{
  "url": "https://social.usenaive.ai/connect/twitter?..."
}

Multi-Platform Portal

For connecting several platforms at once, use the portal endpoint:

curl -X POST https://api.usenaive.ai/v1/social/portal \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"redirect_url": "https://your-app.com/callback"}'

After the user connects accounts, call POST /v1/social/sync to refresh the local account list.

Creating Posts

curl -X POST https://api.usenaive.ai/v1/social/posts \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out our latest product update!",
    "platforms": ["TWITTER", "LINKEDIN"],
    "publish_now": true
  }'

Response (202):

{
  "id": "post-uuid",
  "bundle_post_id": "bundle-uuid",
  "status": "publishing",
  "platforms": ["TWITTER", "LINKEDIN"],
  "scheduled_at": null,
  "hint": "Post queued for immediate publishing. Check status with GET /v1/social/posts/post-uuid"
}

Parameters

Param	Type	Required	Default	Description
`content`	string	Yes	—	Post text content
`title`	string	No	Auto from content	Post title (auto-generated if omitted)
`platforms`	string[]	Yes	—	Platforms to post to
`platform_data`	object	No	Auto-generated	Per-platform overrides (see Platform Defaults below)
`media_urls`	string[]	No	—	Media URLs — auto-uploaded and attached to video/image platforms
`youtube_type`	string	No	`"SHORT"`	YouTube type: `"SHORT"` (vertical, under 3min) or `"VIDEO"` (landscape)
`publish_now`	boolean	No	`false`	Publish immediately
`scheduled_at`	string	No	—	ISO 8601 datetime to schedule
`account_ids`	string[]	No	All active	Specific account UUIDs to post from

If neither publish_now nor scheduled_at is set, the post is created as a draft. Drafts can be edited and published later with POST /v1/social/posts/:id/publish.

Video Post Example (YouTube + TikTok)

curl -X POST https://api.usenaive.ai/v1/social/posts \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Our product demo",
    "platforms": ["YOUTUBE", "TIKTOK", "INSTAGRAM"],
    "media_urls": ["https://example.com/demo-video.mp4"],
    "youtube_type": "SHORT",
    "publish_now": true
  }'

Platform Defaults

When you omit platform_data, the API applies sensible defaults per platform. You can override any field by passing platform_data.

Platform	Auto-applied defaults	Notes
TWITTER	`text` truncated to 280 chars	Text-only platform
BLUESKY	`text` truncated to 300 chars	Text-only platform
YOUTUBE	`text` (100 char title), `type` (SHORT/VIDEO), `privacy: "PUBLIC"`, `madeForKids: false`	Requires media. `youtube_type` controls SHORT vs VIDEO
TIKTOK	`text`, `privacy: "PUBLIC_TO_EVERYONE"`	Requires media for video posts
INSTAGRAM	`text`, `type: "REEL"`	Defaults to Reel for video
REDDIT	`text`, `title` (100 char limit)	Pass `"sr"` in platform_data for subreddit
PINTEREST	`title` (100 char limit), `text`	Media recommended
LINKEDIN	`text` (full content)	No truncation
FACEBOOK	`text` (full content)	No truncation
THREADS	`text` (full content)	No truncation
MASTODON	`text` (full content)	No truncation

Overriding Defaults

Pass platform_data to customize per-platform behavior:

{
  "content": "Check out our launch",
  "platforms": ["TWITTER", "REDDIT", "YOUTUBE"],
  "platform_data": {
    "REDDIT": { "sr": "startups", "title": "We just launched!" },
    "YOUTUBE": { "text": "Product Launch Demo", "type": "VIDEO", "privacy": "PUBLIC" }
  },
  "media_urls": ["https://example.com/launch.mp4"],
  "publish_now": true
}

Overrides are merged on top of defaults — you only need to specify the fields you want to change.

Media Handling

When media_urls are provided, the server:

Uploads each URL to the social media service (handles format conversion for unsupported types)
Attaches uploadIds to all media-capable platforms: YouTube, Instagram, TikTok, Facebook, Pinterest
Text-only platforms (Twitter, LinkedIn, Bluesky, Threads) are unaffected

No separate upload step is needed — just pass the public URLs.

Scheduling & Drafts

Draft
Publish Now
Schedule

Omit both publish_now and scheduled_at to create a draft:

{
  "content": "Working on this post...",
  "platforms": ["TWITTER"]
}

Edit with PATCH /v1/social/posts/:id, then publish with POST /v1/social/posts/:id/publish.

Set publish_now: true to post immediately:

{
  "content": "Live now!",
  "platforms": ["TWITTER", "LINKEDIN"],
  "publish_now": true
}

Set scheduled_at to an ISO 8601 datetime:

{
  "content": "Launching tomorrow!",
  "platforms": ["TWITTER"],
  "scheduled_at": "2026-05-10T14:00:00Z"
}

Analytics

Retrieve performance metrics for published posts:

curl https://api.usenaive.ai/v1/social/posts/post-uuid/analytics \
  -H "Authorization: Bearer nv_sk_your_key"

Response:

{
  "post_id": "post-uuid",
  "analytics": { ... }
}

Analytics data varies by platform. The shape depends on which platforms the post was published to.

Account-level analytics:

curl https://api.usenaive.ai/v1/social/accounts/account-uuid/analytics \
  -H "Authorization: Bearer nv_sk_your_key"

Supported Platforms

Platform	Key	Type	Character Limit
Twitter/X	`TWITTER`	Text + media	280
LinkedIn	`LINKEDIN`	Text + media	—
Instagram	`INSTAGRAM`	Media (Reel default)	—
Facebook	`FACEBOOK`	Text + media	—
TikTok	`TIKTOK`	Video	—
YouTube	`YOUTUBE`	Video (SHORT/VIDEO)	100 (title)
Threads	`THREADS`	Text	—
Pinterest	`PINTEREST`	Media + title	100 (title)
Reddit	`REDDIT`	Text + title	100 (title)
Bluesky	`BLUESKY`	Text	300
Mastodon	`MASTODON`	Text	—

Error Handling

Error	Cause	Recovery
`feature_not_configured`	BUNDLE_SOCIAL_API_KEY not set	Configure the API key
`invalid_input`	Social not activated	Call `POST /v1/social/activate`
`invalid_input`	Missing required fields	Check content, platforms params
`resource_not_found`	Post or account not found	Verify UUID
`insufficient_credits`	Not enough credits to publish	Top up with `POST /v1/billing/topup`
`provider_error`	Social media service error	Retry or check platform requirements

Typical Workflow

Agent receives task: "Post about our product launch on Twitter and LinkedIn"
    │
    ├─ GET /v1/social/status                     → Check activation
    │   → activated: true, 3 accounts
    │
    ├─ GET /v1/social/accounts                   → List connected accounts
    │   → Twitter, LinkedIn, Instagram connected
    │
    ├─ POST /v1/social/posts                     → Create + publish
    │   { content: "We just launched...",
    │     platforms: ["TWITTER", "LINKEDIN"],
    │     publish_now: true }
    │   → id: post-uuid, status: scheduled
    │
    ├─ GET /v1/social/posts/post-uuid            → Check status
    │   → status: publishing → published (via webhook)
    │
    └─ GET /v1/social/posts/post-uuid/analytics  → Track performance
        → { impressions: 1200, likes: 45, ... }

Getting Started

Primitives

CLI First

Tools

Activation

Connecting Accounts

Single Platform

Multi-Platform Portal

Creating Posts

Parameters

Video Post Example (YouTube + TikTok)

Platform Defaults

Overriding Defaults

Media Handling

Scheduling & Drafts

Analytics

Supported Platforms

Error Handling

Typical Workflow

Getting Started

Primitives

Documentation Index

​CLI First

​Tools

​Activation

​Connecting Accounts

​Single Platform

​Multi-Platform Portal

​Creating Posts

​Parameters

​Video Post Example (YouTube + TikTok)

​Platform Defaults

​Overriding Defaults

​Media Handling

​Scheduling & Drafts

​Analytics

​Supported Platforms

​Error Handling

​Typical Workflow

CLI First

Tools

Activation

Connecting Accounts

Single Platform

Multi-Platform Portal

Creating Posts

Parameters

Video Post Example (YouTube + TikTok)

Platform Defaults

Overriding Defaults

Media Handling

Scheduling & Drafts

Analytics

Supported Platforms

Error Handling

Typical Workflow