social - Naive API v2

Overview

Command	Description	Cost
`naive social status`	Check activation and connected accounts	Free
`naive social activate`	Activate social media feature	Free
`naive social connect`	Get OAuth URL for a platform	Free
`naive social portal`	Get multi-platform portal URL	Free
`naive social accounts`	List connected accounts	Free
`naive social label <account-id>`	Set a label on an account	Free
`naive social disconnect <account-id>`	Disconnect an account	Free
`naive social sync`	Sync connected accounts	Free
`naive social upload`	Upload media for posts	Free
`naive social posts`	List posts	Free
`naive social post <content>`	Create a new post (draft by default)	1 credit if publishing
`naive social get <post-id>`	Get post details	Free
`naive social edit <post-id>`	Edit a draft post	Free
`naive social delete <post-id>`	Delete a post	Free
`naive social publish <post-id>`	Publish a draft post	1 credit
`naive social analytics <post-id>`	Get post analytics	Free
`naive social comments <post-id>`	Get post comments	Free
`naive social account-analytics <account-id>`	Get account-level analytics	Free

Check Status

Check whether social media is activated and see connected accounts at a glance.

naive social status

Output

{
  "success": true,
  "action": "social.status",
  "result": {
    "activated": true,
    "team_count": 1,
    "accounts": [
      {
        "id": "acc-uuid-001",
        "platform": "TWITTER",
        "username": "myhandle",
        "display_name": "My Handle",
        "avatar_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
        "label": null,
        "status": "active"
      }
    ]
  },
  "next_steps": [
    { "command": "naive social accounts", "description": "List connected accounts" }
  ],
  "hints": ["Social media is active"]
}

Activate

Activate the social media feature for your company. One-time setup step.

naive social activate

Output

{
  "success": true,
  "action": "social.activate",
  "result": {
    "activated": true,
    "team_count": 1,
    "team_id": "team-uuid-123"
  },
  "next_steps": [
    { "command": "naive social connect --platform twitter --redirect-url https://example.com", "description": "Connect a social account" },
    { "command": "naive social portal --redirect-url https://example.com", "description": "Open multi-platform connect portal" }
  ],
  "hints": ["Social media activated. Connect accounts to start posting."]
}

Connect

Get an OAuth URL to connect a specific social media platform.

naive social connect --platform twitter
naive social connect --platform youtube --redirect-url https://myapp.com/callback

Options

Flag	Required	Description
`--platform <platform>`	Yes	Platform: TWITTER, LINKEDIN, INSTAGRAM, FACEBOOK, TIKTOK, YOUTUBE, THREADS, PINTEREST, REDDIT, BLUESKY
`--redirect-url <url>`	No	URL to redirect after connection (default: `https://usenaive.ai/developers`)

Output

{
  "success": true,
  "action": "social.connect",
  "result": {
    "url": "https://social.usenaive.ai/oauth/twitter?token=abc123"
  },
  "next_steps": [
    { "command": "naive social sync", "description": "Sync accounts after connecting" },
    { "command": "naive social accounts", "description": "List connected accounts" }
  ],
  "hints": [
    "Open this URL to connect your TWITTER account:",
    "https://social.usenaive.ai/oauth/twitter?token=abc123",
    "After connecting, run 'naive social sync' to refresh accounts."
  ]
}

Portal

Get a portal URL to connect multiple social media platforms at once.

naive social portal
naive social portal --platforms twitter,youtube,tiktok
naive social portal --redirect-url https://myapp.com/callback

Options

Flag	Required	Description
`--redirect-url <url>`	No	URL to redirect after connection (default: `https://usenaive.ai/developers`)
`--platforms <list>`	No	Comma-separated platform list to show

Output

{
  "success": true,
  "action": "social.portal",
  "result": {
    "url": "https://social.usenaive.ai/portal?token=xyz789"
  },
  "next_steps": [
    { "command": "naive social sync", "description": "Sync accounts after connecting" }
  ],
  "hints": [
    "Open this URL to connect multiple social accounts:",
    "https://social.usenaive.ai/portal?token=xyz789"
  ]
}

List Accounts

List all connected social media accounts.

naive social accounts

Output

{
  "success": true,
  "action": "social.accounts",
  "result": {
    "accounts": [
      {
        "id": "acc-uuid-001",
        "platform": "TWITTER",
        "username": "myhandle",
        "display_name": "My Handle",
        "avatar_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
        "external_id": "ext-123",
        "label": null,
        "status": "active",
        "team_id": "team-uuid-123"
      }
    ]
  },
  "next_steps": [
    { "command": "naive social post \"Hello!\" --platforms twitter", "description": "Create a post" },
    { "command": "naive social connect --platform <platform> --redirect-url <url>", "description": "Connect more accounts" }
  ],
  "hints": ["1 connected account(s)"]
}

Label Account

Set a label on a connected social media account. Useful for distinguishing multiple accounts on the same platform.

naive social label acc-uuid-001 --label "Personal"
naive social label acc-uuid-002 --label "Company Brand"

Options

Flag	Required	Description
`account-id`	Yes	Account ID (positional argument)
`--label <label>`	Yes	Label text to set

Output

{
  "success": true,
  "action": "social.label",
  "result": {
    "account_id": "acc-uuid-001",
    "label": "Personal"
  },
  "next_steps": [
    { "command": "naive social accounts", "description": "List accounts" }
  ],
  "hints": ["Label set to \"Personal\""]
}

Disconnect

Disconnect a social media account by its ID.

naive social disconnect acc-uuid-001

Output

{
  "success": true,
  "action": "social.disconnect",
  "result": {
    "disconnected": true,
    "account_id": "acc-uuid-001"
  },
  "next_steps": [
    { "command": "naive social accounts", "description": "List remaining accounts" }
  ],
  "hints": ["Account disconnected"]
}

Sync Accounts

Sync connected accounts. Run this after connecting new platforms via OAuth or the portal.

naive social sync

Output

{
  "success": true,
  "action": "social.sync",
  "result": {
    "synced": 3,
    "team_count": 1
  },
  "next_steps": [
    { "command": "naive social accounts", "description": "View synced accounts" }
  ],
  "hints": ["Synced 3 account(s)"]
}

Upload Media

Upload media from a public URL for use in social posts.

naive social upload --url https://example.com/video.mp4

Options

Flag	Required	Description
`--url <url>`	Yes	Public URL of the media file

Output

{
  "success": true,
  "action": "social.upload",
  "result": {
    "id": "upload-uuid-456",
    "type": "video",
    "url": "https://cdn.usenaive.ai/uploads/upload-uuid-456.mp4"
  },
  "next_steps": [
    { "command": "naive social post \"content\" --platforms youtube --media-url <url>", "description": "Create a post with media" }
  ],
  "hints": ["Media uploaded. Use the upload ID or pass media_urls when creating posts (auto-upload)."]
}

List Posts

List your social media posts with optional filters.

naive social posts
naive social posts --status draft --limit 5
naive social posts --status posted --limit 10 --offset 20

Options

Flag	Required	Description
`--status <status>`	No	Filter by status: `draft`, `scheduled`, `publishing`, `posted`, `failed`
`--limit <n>`	No	Max results (default: `50`)
`--offset <n>`	No	Pagination offset (default: `0`)

Output

{
  "success": true,
  "action": "social.posts",
  "result": {
    "posts": [
      {
        "id": "post-uuid-001",
        "title": "Excited to announce our new feature!",
        "content": "Excited to announce our new feature!",
        "platforms": ["TWITTER", "LINKEDIN"],
        "platform_data": { "TWITTER": { "text": "Excited to announce our new feature!" }, "LINKEDIN": { "text": "Excited to announce our new feature!" } },
        "upload_ids": null,
        "status": "posted",
        "post_id": "post-uuid-001",
        "scheduled_at": null,
        "posted_at": "2026-05-03T10:30:05.000Z",
        "error": null,
        "analytics": null,
        "created_at": "2026-05-03T10:30:00.000Z",
        "updated_at": "2026-05-03T10:30:05.000Z"
      }
    ],
    "count": 1,
    "limit": 50,
    "offset": 0
  },
  "next_steps": [
    { "command": "naive social post \"content\" --platforms twitter", "description": "Create a new post" }
  ],
  "hints": ["1 post(s) returned"]
}

Create Post

Create a social media post. Posts are created as drafts by default. Pass --publish to publish immediately, or --schedule-at to schedule.

Examples

naive social post "Just shipped a major update!" --platforms twitter,linkedin
naive social post "New video is live!" --platforms youtube --media-url https://example.com/video.mp4 --youtube-type SHORT
naive social post "Coming soon..." --platforms twitter --schedule-at "2026-05-10T14:00:00Z"
naive social post "Check this out" --platforms twitter,linkedin --publish
naive social post "My take on this" --platforms reddit --platform-data '{"REDDIT":{"sr":"programming"}}'
naive social post "Hello world" --platforms twitter --account-ids acc-uuid-001,acc-uuid-002
naive social post "Big news" --platforms twitter --title "Product Launch"

Options

Flag	Required	Description
`content`	Yes	Post content (positional argument)
`--platforms <list>`	Yes	Comma-separated platforms: `twitter,linkedin,youtube,...`
`--publish`	No	Publish immediately (default: create as draft)
`--title <title>`	No	Post title (auto-generated from content if omitted)
`--media-url <url>`	No	Media URL (auto-uploaded for video/image platforms)
`--upload-ids <ids>`	No	Comma-separated pre-uploaded media IDs (`upload_id` from Media Assets). Skips re-upload.
`--youtube-type <type>`	No	YouTube type: `SHORT` (vertical, under 3min) or `VIDEO` (landscape). No CLI default; service defaults to `SHORT`
`--platform-data <json>`	No	Per-platform overrides as JSON
`--account-ids <ids>`	No	Comma-separated account UUIDs to post from
`--schedule-at <datetime>`	No	ISO 8601 datetime to schedule the post

Output (draft)

{
  "success": true,
  "action": "social.post",
  "result": {
    "id": "post-uuid-003",
    "status": "draft",
    "platforms": ["TWITTER", "LINKEDIN"],
    "hint": "Draft created. Publish with POST /v1/social/posts/post-uuid-003/publish"
  },
  "next_steps": [
    { "command": "naive social publish post-uuid-003", "description": "Publish this draft" },
    { "command": "naive social analytics post-uuid-003", "description": "View post analytics (after publishing)" }
  ],
  "hints": ["Draft created. Use 'naive social publish' to publish, or re-run with --publish."]
}

Output (posted — with `--publish`)

{
  "success": true,
  "action": "social.post",
  "result": {
    "id": "post-uuid-003",
    "post_id": "post-uuid-003",
    "status": "publishing",
    "platforms": ["TWITTER", "LINKEDIN"],
    "scheduled_at": null,
    "hint": "Post queued for immediate publishing. Check status with GET /v1/social/posts/post-uuid-003"
  },
  "next_steps": [
    { "command": "naive social get post-uuid-003", "description": "Check post status" },
    { "command": "naive social analytics post-uuid-003", "description": "View post analytics (after publishing)" }
  ],
  "hints": ["Post queued for publishing. 1 credit deducted."]
}

Output (scheduled — with `--schedule-at`)

{
  "success": true,
  "action": "social.post",
  "result": {
    "id": "post-uuid-003",
    "post_id": "post-uuid-003",
    "status": "publishing",
    "platforms": ["TWITTER"],
    "scheduled_at": "2026-05-10T14:00:00Z",
    "hint": "Post scheduled for 2026-05-10T14:00:00Z. Check status with GET /v1/social/posts/post-uuid-003"
  },
  "next_steps": [
    { "command": "naive social get post-uuid-003", "description": "Check post status" },
    { "command": "naive social analytics post-uuid-003", "description": "View post analytics (after publishing)" }
  ],
  "hints": ["Post scheduled. 1 credit deducted."]
}

Get Post

Get full details of a specific post.

naive social get post-uuid-001

Output

{
  "success": true,
  "action": "social.get",
  "result": {
    "id": "post-uuid-001",
    "title": "Excited to announce our new feature!",
    "content": "Excited to announce our new feature!",
    "platforms": ["TWITTER", "LINKEDIN"],
    "platform_data": { "TWITTER": { "text": "Excited to announce our new feature!" }, "LINKEDIN": { "text": "Excited to announce our new feature!" } },
    "upload_ids": null,
    "status": "posted",
    "post_id": "post-uuid-001",
    "scheduled_at": null,
    "posted_at": "2026-05-03T10:30:05.000Z",
    "error": null,
    "analytics": null,
    "created_at": "2026-05-03T10:30:00.000Z",
    "updated_at": "2026-05-03T10:30:05.000Z"
  },
  "next_steps": [
    { "command": "naive social analytics post-uuid-001", "description": "View analytics" },
    { "command": "naive social comments post-uuid-001", "description": "View comments" }
  ],
  "hints": ["Post status: posted"]
}

Edit Post

Edit a draft post. Only draft posts can be edited.

naive social edit post-uuid-002 --content "Updated content here"
naive social edit post-uuid-002 --platforms youtube,tiktok
naive social edit post-uuid-002 --platform-data '{"REDDIT":{"sr":"javascript"}}'

Options

Flag	Required	Description
`post-id`	Yes	Post ID (positional argument)
`--content <text>`	No	Updated post content
`--platforms <list>`	No	Updated comma-separated platform list
`--platform-data <json>`	No	Updated per-platform overrides as JSON

Output

{
  "success": true,
  "action": "social.edit",
  "result": {
    "id": "post-uuid-002",
    "title": "Updated content here",
    "content": "Updated content here",
    "platforms": ["YOUTUBE", "TIKTOK"],
    "platform_data": { "YOUTUBE": { "text": "Updated content here", "type": "SHORT", "privacy": "PUBLIC", "madeForKids": false }, "TIKTOK": { "text": "Updated content here", "privacy": "PUBLIC_TO_EVERYONE" } },
    "upload_ids": null,
    "status": "draft",
    "post_id": null,
    "scheduled_at": null,
    "posted_at": null,
    "error": null,
    "analytics": null,
    "created_at": "2026-05-04T08:15:00.000Z",
    "updated_at": "2026-05-04T09:00:00.000Z"
  },
  "next_steps": [
    { "command": "naive social publish post-uuid-002", "description": "Publish the updated draft" }
  ],
  "hints": ["Draft updated"]
}

Delete Post

Delete a post by ID. If the post was posted, it is also deleted from the social media service.

naive social delete post-uuid-002

Output

{
  "success": true,
  "action": "social.delete",
  "result": {
    "deleted": true,
    "post_id": "post-uuid-002"
  },
  "next_steps": [
    { "command": "naive social posts", "description": "View remaining posts" }
  ],
  "hints": ["Post deleted"]
}

Publish Post

Publish a draft post. Sends the post to all specified platforms. Costs 1 credit.

naive social publish post-uuid-003

Output

{
  "success": true,
  "action": "social.publish",
  "result": {
    "id": "post-uuid-003",
    "post_id": "post-uuid-003",
    "status": "publishing",
    "platforms": ["TWITTER", "LINKEDIN"],
    "hint": "Post queued for publishing. Check status with GET /v1/social/posts/post-uuid-003"
  },
  "next_steps": [
    { "command": "naive social get post-uuid-003", "description": "Check post status" },
    { "command": "naive social analytics post-uuid-003", "description": "View analytics" }
  ],
  "hints": ["Post publishing (1 credit deducted)"]
}

Post Analytics

Get analytics for a posted post. Returns performance data (impressions, likes, shares, etc.).

naive social analytics post-uuid-001

Output

{
  "success": true,
  "action": "social.analytics",
  "result": {
    "post_id": "post-uuid-001",
    "analytics": { "...": "platform-specific analytics" }
  },
  "next_steps": [
    { "command": "naive social comments post-uuid-001", "description": "View comments" }
  ],
  "hints": ["Post analytics retrieved"]
}

If the post has not been posted yet, analytics will be null with a hint field explaining why.

Post Comments

Get comments on a posted post.

naive social comments post-uuid-001

Output

{
  "success": true,
  "action": "social.comments",
  "result": {
    "post_id": "post-uuid-001",
    "comments": [ "...comments from social media service..." ]
  },
  "next_steps": [
    { "command": "naive social analytics post-uuid-001", "description": "View analytics" }
  ],
  "hints": ["Post comments retrieved"]
}

If the post has not been posted yet, comments will be [] with a hint field.

Account Analytics

Get analytics for a specific connected account.

naive social account-analytics acc-uuid-001

Output

{
  "success": true,
  "action": "social.account-analytics",
  "result": {
    "account_id": "acc-uuid-001",
    "platform": "TWITTER",
    "analytics": { "...": "platform-specific analytics" }
  },
  "next_steps": [
    { "command": "naive social accounts", "description": "List all accounts" }
  ],
  "hints": ["Account analytics retrieved"]
}

Platform Tips

Platform	Tip
YouTube	Use `--youtube-type SHORT` for Shorts (vertical, under 3min) or `VIDEO` for landscape uploads. No CLI default; service defaults to `SHORT`.
TikTok	Privacy is auto-set to `PUBLIC_TO_EVERYONE`.
Instagram	Video posts default to Reel type. Provide media via `--media-url`.
Twitter	Content is auto-truncated to 280 characters.
Bluesky	Content is auto-truncated to 300 characters.
Reddit	Uses uppercase `REDDIT` key. Pass `--platform-data '{"REDDIT":{"sr":"yoursubreddit"}}'` to set the subreddit via the `sr` field.
Pinterest	A `title` is auto-generated from content (first 100 chars).

Supported platforms: TWITTER, LINKEDIN, INSTAGRAM, FACEBOOK, TIKTOK, YOUTUBE, THREADS, PINTEREST, REDDIT, BLUESKY

Credit Behavior

Publishing a post costs 1 credit — triggered by --publish, --schedule-at, or naive social publish
Drafts are free — creating, editing, and deleting drafts costs nothing
All other commands — connecting, syncing, uploading, analytics, comments — are free
Credits are deducted at publish time, not at draft creation
Use naive usage to audit credit deductions

​Overview

​Check Status

​Output

​Activate

​Output

​Connect

​Options

​Output

​Portal

​Options

​Output

​List Accounts

​Output

​Label Account

​Options

​Output

​Disconnect

​Output

​Sync Accounts

​Output

​Upload Media

​Options

​Output

​List Posts

​Options

​Output

​Create Post

​Examples

​Options

​Output (draft)

​Output (posted — with --publish)

​Output (scheduled — with --schedule-at)

​Get Post

​Output

​Edit Post

​Options

​Output

​Delete Post

​Output

​Publish Post

​Output

​Post Analytics

​Output

​Post Comments

​Output

​Account Analytics

​Output

​Platform Tips

​Credit Behavior

Overview

Check Status

Output

Activate

Output

Connect

Options

Output

Portal

Options

Output

List Accounts

Output

Label Account

Options

Output

Disconnect

Output

Sync Accounts

Output

Upload Media

Options

Output

List Posts

Options

Output

Create Post

Examples

Options

Output (draft)

Output (posted — with `--publish`)

Output (scheduled — with `--schedule-at`)

Get Post

Output

Edit Post

Options

Output

Delete Post

Output

Publish Post

Output

Post Analytics

Output

Post Comments

Output

Account Analytics

Output

Platform Tips

Credit Behavior