---
title: "Generate Social Post"
method: POST
path: "/social/posts/generate"
tags: ["Social Publishing"]
---

# Generate Social Post

`POST /social/posts/generate`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/social/posts/generate`
- Auth: HTTP bearer

Draft up to three variants with AI. SPENDS CREDITS (`credits_used`); saves nothing.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- SocialPostGenerateRequest: Ask the AI studio for draft variants. SPENDS CREDITS; saves nothing. The variants come back in the response - create a post from the one you want with `POST /social/posts`.
  - `instructions` string, nullable
  - `context` string, nullable: Older synonym of `instructions`.
  - `idea_id` string, nullable
  - `sources` string[], nullable: Grounding sources. Omit for the default set (brand_voice, campaign_brief, proof_catalog, inbox_insights). `GET /social/generate/context` says which have data.
  - `tone` string, nullable
  - `frame` string, nullable
  - `variants` integer
  - `hashtags_max` integer
  - `refine` SocialRefineSpec: Rewrite an existing draft instead of generating from scratch.
    - `body` string, required
    - `instruction` string, required
  - `campaign_id` string, nullable
  - `reference_post` string, nullable: Someone else's post, used as a structural template only.

## Response `200`

Successful Response

- ApiResponseSocialGenerated
  - `data` SocialGenerated, required: Generated drafts. Nothing has been saved.
    - `variants` SocialVariant[], required
      - `frame` string, required
      - `body` string, required
    - `credits_used` integer, required
    - `provenance` string[], required
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/2e7cfa0ca921?raw)