> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Social

> Connect 10+ social platforms, then publish, schedule, and manage posts and comments across all of them from a single API — or let Crevio write and schedule them for you.

**Social lets you publish to ten-plus platforms — X, LinkedIn, Instagram, Facebook, YouTube, TikTok, Pinterest, Threads, Reddit, and Bluesky — through one API, with scheduling, drafts, per-platform overrides, comment management, and analytics.**

You can just ask Crevio to write and schedule a week of posts, or drive it yourself: connect accounts once, then `POST /socials/posts` with your content and a list of platforms. One call fans out to every channel, and you manage the replies and analytics from the same place.

## Connect platforms

Posting requires at least one connected account. Two ways to connect:

<CodeGroup>
  ```bash OAuth (per platform) theme={null}
  # Returns a connect URL to send the user through
  curl -X POST https://api.crevio.co/v1/socials/connect \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "platform": "linkedin" }'
  ```

  ```bash Hosted portal (all platforms) theme={null}
  # Returns a hosted page where the user can connect everything
  curl -X POST https://api.crevio.co/v1/socials/portal \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```
</CodeGroup>

Supported platforms (use these exact lowercase values): `twitter`, `linkedin`, `instagram`, `facebook`, `youtube`, `tiktok`, `pinterest`, `threads`, `reddit`, `bluesky`.

## Publish a post

`content` and `platforms` are required. Without `publish_now` or `scheduled_at`, the post is saved as a **draft**.

| Field           | Purpose                                  |
| --------------- | ---------------------------------------- |
| `content`       | The post text (required)                 |
| `platforms`     | Array of target platforms (required)     |
| `publish_now`   | `true` to post immediately               |
| `scheduled_at`  | ISO-8601 time to schedule for later      |
| `media_urls`    | Public image/video URLs                  |
| `upload_ids`    | IDs from prior `POST /socials/upload`    |
| `platform_data` | Per-platform overrides keyed by platform |
| `youtube_type`  | `SHORT` or `VIDEO` (for YouTube)         |
| `title`         | Title (where the platform uses one)      |

## Worked example: schedule a post to three platforms

This schedules one post to LinkedIn, X, and Threads, with a LinkedIn-specific override and an attached image.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.crevio.co/v1/socials/posts \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "Fall portrait mini-sessions are open — booking a handful of slots only.",
      "platforms": ["linkedin", "twitter", "threads"],
      "scheduled_at": "2026-07-01T15:00:00Z",
      "media_urls": ["https://cdn.example.com/mini-sessions.jpg"],
      "platform_data": {
        "linkedin": {
          "content": "Now booking fall portrait mini-sessions for families and professionals. A limited number of slots are available this month."
        }
      }
    }'
  ```

  ```typescript SDK theme={null}
  import { Crevio } from "@crevio/sdk";

  const crevio = new Crevio({ apiKeyAuth: "YOUR_API_TOKEN" });

  const post = await crevio.socials.posts.create({
    content: "Fall portrait mini-sessions are open — booking a handful of slots only.",
    platforms: ["linkedin", "twitter", "threads"],
    scheduled_at: "2026-07-01T15:00:00Z",
    media_urls: ["https://cdn.example.com/mini-sessions.jpg"],
    platform_data: {
      linkedin: {
        content:
          "Now booking fall portrait mini-sessions for families and professionals. " +
          "A limited number of slots are available this month.",
      },
    },
  });
  ```

  ```text MCP (agent) theme={null}
  Schedule a post for July 1st about my fall portrait mini-sessions
  to LinkedIn, X, and Threads, with a more professional spin on LinkedIn.
  ```
</CodeGroup>

<Tip>
  Upload media first via `POST /socials/upload` and pass the returned IDs in `upload_ids` when you want to reuse the same asset across posts, instead of re-fetching a URL each time.
</Tip>

### Pinterest

A Pinterest pin is an image, so a Pinterest post is rejected with `422` unless you attach media via `media_urls` or `upload_ids`.

Pins also need a board. If you don't name one, Crevio pins to the first board on the connected account; pass `platform_data.pinterest.board_id` to choose. An account with no boards at all fails with a message telling you to create one.

```bash theme={null}
curl -X POST https://api.crevio.co/v1/socials/posts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Fall portrait mini-sessions are open.",
    "platforms": ["pinterest"],
    "publish_now": true,
    "media_urls": ["https://cdn.example.com/mini-sessions.png"],
    "platform_data": {
      "pinterest": {
        "board_id": "1234567890",
        "title": "Fall mini-sessions",
        "link": "https://example.com/book"
      }
    }
  }'
```

### Publish a draft later

Posts created without `publish_now`/`scheduled_at` stay as drafts until you publish them.

```bash theme={null}
curl -X POST https://api.crevio.co/v1/socials/posts/post_abc123/publish \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Manage comments

Crevio surfaces incoming comments so you (or an agent) can engage without leaving the API. Reply publicly, hide spam, like, send a private reply, or delete.

```bash theme={null}
# Reply to a comment
curl -X POST https://api.crevio.co/v1/socials/comments/cmt_abc123/reply \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Thanks! Booking opens next week." }'

# Hide / unhide
curl -X POST https://api.crevio.co/v1/socials/comments/cmt_abc123/hide \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Other comment actions follow the same shape: `unhide`, `like`, `private_reply`, and `delete`.

<Tip>
  Pair this with a [Task](/docs/developer/guides/tasks) to let Crevio triage and reply to comments automatically on a schedule.
</Tip>

## X (Twitter) engagement

`/v1/socials/twitter/*` covers the X-only reads and engagement that have no cross-platform equivalent: searching public posts, resolving one by id or URL, and reposting, bookmarking and following with their inverses.

<Note>
  Nothing under `/socials/twitter` publishes. A reply is still a post — `POST /socials/posts` with `platform_data.twitter.replyToTweetId` set to the id you found — so there is exactly one endpoint that says something publicly.
</Note>

Every call acts as your connected X account. `SocialAccount` holds one row per platform, so the account is unambiguous and the optional `account_id` (a `sacct_…` id) is an explicit override, not a required selector. With no X account connected you get a `404`; pointing `account_id` at a non-X account gets a `400`.

| Endpoint                                   | Purpose                                  |
| ------------------------------------------ | ---------------------------------------- |
| `GET /socials/twitter/search`              | Search public posts from the last 7 days |
| `GET /socials/twitter/tweets/{id}`         | Read one post by numeric id              |
| `GET /socials/twitter/tweets/lookup?id=`   | Read one post by id **or** URL           |
| `POST`/`DELETE /socials/twitter/retweets`  | Repost / undo a repost                   |
| `POST`/`DELETE /socials/twitter/bookmarks` | Bookmark / remove a bookmark             |
| `POST`/`DELETE /socials/twitter/follows`   | Follow / unfollow a user                 |

### Search

`query` is passed to X unchanged, so its own operators (`from:`, `to:`, `-is:retweet`, `conversation_id:`, quoted phrases, boolean `OR`) all work. Standalone operators like `is:`, `has:` and `lang:` must be combined with a keyword or a `from:` clause. Results are cursor-paginated, and search is limited to 300 requests per 15-minute window per connected account.

```bash theme={null}
curl -G https://api.crevio.co/v1/socials/twitter/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode 'query=("mini sessions" OR "portrait session") -is:retweet' \
  -d limit=25 -d sort_order=recency
```

| Parameter                 | Notes                                |
| ------------------------- | ------------------------------------ |
| `query`                   | Required, at most 512 characters     |
| `limit`                   | 10–100 — X rejects smaller pages     |
| `since_id` / `until_id`   | Numeric X post ids                   |
| `start_time` / `end_time` | ISO-8601 bounds                      |
| `cursor`                  | Opaque cursor from the previous page |
| `sort_order`              | `recency` or `relevancy`             |

Each result carries `id`, `text`, `created`, `conversation_id`, `in_reply_to_tweet_id`, `lang`, `author`, and the public counts (`like_count`, `reply_count`, `retweet_count`, `quote_count`).

<Tip>
  Poll mentions by re-running the same query with `since_id` set to the highest `id` you have already seen. Search only reaches back 7 days; **lookup does not**, which makes it the way to read the parent of a thread before replying to it.
</Tip>

### Lookup and engagement

A tweet URL carries slashes, so it can't ride in a path segment — pass it to `tweets/lookup` as a query parameter instead.

```bash theme={null}
# By URL (or by id) — not limited to the last 7 days
curl -G https://api.crevio.co/v1/socials/twitter/tweets/lookup \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode 'id=https://x.com/someone/status/1234567890123456789'

# Repost, bookmark, follow — the id goes in the body
curl -X POST https://api.crevio.co/v1/socials/twitter/retweets \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tweet_id": "1234567890123456789" }'

# The inverses take it in the path
curl -X DELETE https://api.crevio.co/v1/socials/twitter/retweets/1234567890123456789 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

`retweets` and `bookmarks` take `tweet_id`; `follows` takes the target's numeric `target_user_id`. Follow answers with `following` and `pending_follow` — a protected account yields a pending follow request rather than a completed follow.

<Warning>
  Reposting shares X's 300-per-3-hours creation budget with publishing, so a repost loop competes with your scheduled posts.
</Warning>

## Analytics

Pull performance at the account level (across all connected channels) or for an individual post.

```bash theme={null}
# Account-level analytics
curl https://api.crevio.co/v1/socials/analytics \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# A single post's analytics
curl https://api.crevio.co/v1/socials/posts/post_abc123/analytics \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Next steps

<CardGroup cols={2}>
  <Card title="Tasks" icon="robot" href="/docs/developer/guides/tasks">
    Have Crevio write and schedule social posts on a recurring basis.
  </Card>

  <Card title="Images" icon="image" href="/docs/developer/guides/ai-content">
    Generate post visuals with AI.
  </Card>

  <Card title="Ads & Voice" icon="bullhorn" href="/docs/developer/guides/ads-and-voice">
    Turn a high-performing post into a paid ad.
  </Card>

  <Card title="API reference" icon="book" href="/docs/developer/api-reference/introduction">
    Every social endpoint and parameter.
  </Card>
</CardGroup>