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

# Social

> AI-generated multi-platform posts, scheduled publishing, OAuth account connections — with brand voice baked in.

The Social pillar is a standalone product: AI-generated posts in your brand
voice, scheduled or published immediately to Facebook, Instagram, X, TikTok,
LinkedIn or YouTube. You can use it without using the CMS or blog or
commerce — many customers do.

## What this gives you

* **Connected accounts** for Facebook, Instagram, X, TikTok, LinkedIn,
  YouTube — OAuth handled by us.
* **AI generation** per platform, with per-platform tone and length conventions
  baked in.
* **Per-platform content** — write once, get six platform-tailored variants;
  override any of them by hand.
* **Scheduling** — pick a date/time per post, or a tone calendar for a week of
  posts at once.
* **Publishing** — fire-and-forget; we handle the platform APIs and surface
  per-platform success/failure on the resource.

## Quick example

Generate and schedule a cross-platform post in one shot.

<CodeGroup>
  ```bash cURL theme={null}
  # 1. Kick off generation
  curl -X POST https://api.neuraldraft.io/v1/jobs \
    -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "social_post.generate",
      "custom_title": "Launching our v1 API",
      "platforms": ["facebook", "instagram", "twitter", "linkedin"],
      "tone": "warm",
      "media_type": "image",
      "visual_style": "minimal_brand"
    }'
  # => { "job_id": "job_2Nh4PqRsTuVw", "status": "pending" }

  # 2. After completion, schedule the resulting post
  curl -X POST https://api.neuraldraft.io/v1/social-posts/882/schedule \
    -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"scheduled_at":"2026-04-22T14:00:00Z"}'
  ```

  ```ts SDK theme={null}
  // Social-post resources are not yet covered by the v0.3.0 SDK; call the REST
  // endpoints directly. The SDK does provide `jobs.poll()` for the async pieces.
  import { NeuralDraftClient } from "@neuraldraft/sdk";

  const nd = new NeuralDraftClient({ apiKey: process.env.NEURALDRAFT_API_KEY! });

  const job = await fetch("https://api.neuraldraft.io/v1/jobs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEURALDRAFT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "social_post.generate",
      custom_title: "Launching our v1 API",
      platforms: ["facebook", "instagram", "twitter", "linkedin"],
      tone: "warm",
      media_type: "image",
    }),
  }).then((r) => r.json());

  // Wait for completion using the SDK's job poller.
  const finished = await nd.jobs.poll(job.id);
  const socialPostId = finished.result?.social_post_id;
  ```
</CodeGroup>

Cost: **5 credits** (`social_post`) for the text base, regardless of how
many platforms you fan out to in a single call. If `media_type=image` is
set an extra **32 credits** (`image`) is charged; `media_type=video`
charges an extra **40 credits** (`video`, budget tier). Scheduling is free.

## Common workflows

### 1. Connect a social account

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/social-accounts/connect/instagram \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uri":"https://example.com/oauth/callback"}'
```

```json theme={null}
{
  "oauth_url": "https://app.neuraldraft.io/oauth/instagram?state=...",
  "expires_in": 600
}
```

Surface the URL to the user. After they authorize, we redirect to your
`redirect_uri` with `?status=connected&account_id=...`.

### 2. List connected accounts

```bash theme={null}
curl https://api.neuraldraft.io/v1/social-accounts \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY"
```

```json theme={null}
{
  "data": [
    { "id": 12, "platform": "instagram", "username": "@acme", "is_active": true, "expires_at": "2026-09-01T00:00:00Z" }
  ]
}
```

### 3. Publish immediately, no scheduling

Skip `schedule`; call `publish` instead.

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/social-posts/882/publish \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY"
```

The post enters `published` state on success per platform; check the
`publish_results` field on the resource for per-platform outcomes:

```json theme={null}
{
  "id": 882,
  "status": "published",
  "publish_results": [
    { "platform": "facebook", "status": "success", "external_id": "fb_post_..." },
    { "platform": "instagram", "status": "failed", "error": "media_too_large" }
  ]
}
```

Subscribe to `social_post.failed` to react to per-platform failures.

### 4. Override per-platform content

The AI generates platform-tailored variants; you can override any of them
before publish:

```bash theme={null}
curl -X PUT https://api.neuraldraft.io/v1/social-posts/882 \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "twitter_content": "Launching our v1 API today. ndsk_live_... in your hand in 60 seconds."
  }'
```

### 5. Generate from an existing blog post

Cross-promote a blog post to social with one call. The pipeline reads the
post, summarises per platform, generates an image, and saves a draft.

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/jobs \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "social_post.generate",
    "post_id": 4711,
    "platforms": ["twitter", "linkedin"],
    "tone": "warm",
    "media_type": "image"
  }'
```

## Reference

| Endpoint                                      | Tag                                 |
| --------------------------------------------- | ----------------------------------- |
| `GET /v1/social-posts`                        | [Social](/api-reference#tag/Social) |
| `POST /v1/social-posts`                       | [Social](/api-reference#tag/Social) |
| `GET /v1/social-posts/{id}`                   | [Social](/api-reference#tag/Social) |
| `PUT /v1/social-posts/{id}`                   | [Social](/api-reference#tag/Social) |
| `POST /v1/social-posts/{id}/publish`          | [Social](/api-reference#tag/Social) |
| `POST /v1/social-posts/{id}/schedule`         | [Social](/api-reference#tag/Social) |
| `GET /v1/social-posts/{id}/status`            | [Social](/api-reference#tag/Social) |
| `GET /v1/social-accounts`                     | [Social](/api-reference#tag/Social) |
| `POST /v1/social-accounts/connect/{platform}` | [Social](/api-reference#tag/Social) |
| `DELETE /v1/social-accounts/{id}`             | [Social](/api-reference#tag/Social) |
| `POST /v1/jobs` (`social_post.generate`)      | [Jobs](/api-reference#tag/Jobs)     |