@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/socialPublishing.md

@@ -0,0 +1,1245 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.socialPublishing`: Social Publishing
+
+22 operations (10 read, 3 write, 3 destructive, 1 billable, 5 external).
+
+No hand-written client covers this area. Call it through `g8.api.socialPublishing.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [socialPublishing.d.ts](socialPublishing.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addSocialEngagersToAudience`](#op-addsocialengagerstoaudience) | `POST /api/v1/social/posts/{post_id}/engagers/add-to-audience` | external | `campaigns:run` | Add Social Engagers To Audience |
+| [`cancelSocialPost`](#op-cancelsocialpost) | `POST /api/v1/social/posts/{post_id}/cancel` | destructive | `campaigns:delete` | Cancel Social Post |
+| [`createSocialPost`](#op-createsocialpost) | `POST /api/v1/social/posts` | write | `campaigns:write` | Create Social Post |
+| [`deleteSocialPost`](#op-deletesocialpost) | `DELETE /api/v1/social/posts/{post_id}` | destructive | `campaigns:delete` | Delete Social Post |
+| [`disconnectSocialAccount`](#op-disconnectsocialaccount) | `DELETE /api/v1/social/accounts/{account_id}` | destructive | `campaigns:delete` | Disconnect Social Account |
+| [`enrollSocialEngagers`](#op-enrollsocialengagers) | `POST /api/v1/social/posts/{post_id}/engagers/enroll` | external | `campaigns:run` | Enroll Social Engagers |
+| [`generateSocialPost`](#op-generatesocialpost) | `POST /api/v1/social/posts/generate` | billable | `campaigns:run` | Generate Social Post |
+| [`getSocialAnalytics`](#op-getsocialanalytics) | `GET /api/v1/social/analytics` | read | `campaigns:read` | Get Social Analytics |
+| [`getSocialAutopilot`](#op-getsocialautopilot) | `GET /api/v1/social/autopilot/{account_id}` | read | `campaigns:read` | Get Social Autopilot |
+| [`getSocialGenerationContext`](#op-getsocialgenerationcontext) | `GET /api/v1/social/generate/context` | read | `campaigns:read` | Get Social Generation Context |
+| [`getSocialPost`](#op-getsocialpost) | `GET /api/v1/social/posts/{post_id}` | read | `campaigns:read` | Get Social Post |
+| [`getSocialPostMetrics`](#op-getsocialpostmetrics) | `GET /api/v1/social/posts/{post_id}/metrics` | read | `campaigns:read` | Get Social Post Metrics |
+| [`listSocialAccounts`](#op-listsocialaccounts) | `GET /api/v1/social/accounts` | read | `campaigns:read` | List Social Accounts |
+| [`listSocialIdeas`](#op-listsocialideas) | `GET /api/v1/social/ideas` | read | `campaigns:read` | List Social Ideas |
+| [`listSocialPostEngagers`](#op-listsocialpostengagers) | `GET /api/v1/social/posts/{post_id}/engagers` | read | `campaigns:read` | List Social Post Engagers |
+| [`listSocialPosts`](#op-listsocialposts) | `GET /api/v1/social/posts` | read | `campaigns:read` | List Social Posts |
+| [`listSocialProviders`](#op-listsocialproviders) | `GET /api/v1/social/providers` | read | `campaigns:read` | List Social Providers |
+| [`pauseSocialAutopilot`](#op-pausesocialautopilot) | `POST /api/v1/social/autopilot/{account_id}/pause` | write | `campaigns:write` | Pause Social Autopilot |
+| [`publishSocialPost`](#op-publishsocialpost) | `POST /api/v1/social/posts/{post_id}/publish` | external | `campaigns:run` | Publish Social Post |
+| [`saveSocialAutopilot`](#op-savesocialautopilot) | `PUT /api/v1/social/autopilot/{account_id}` | external | `campaigns:run` | Save Social Autopilot |
+| [`scheduleSocialPost`](#op-schedulesocialpost) | `POST /api/v1/social/posts/{post_id}/schedule` | external | `campaigns:run` | Schedule Social Post |
+| [`updateSocialPost`](#op-updatesocialpost) | `PATCH /api/v1/social/posts/{post_id}` | write | `campaigns:write` | Update Social Post |
+
+---
+
+<a id="op-addsocialengagerstoaudience"></a>
+
+### `g8.api.socialPublishing.addSocialEngagersToAudience(input)`
+
+**Add Social Engagers To Audience**
+
+- HTTP: `POST /api/v1/social/posts/{post_id}/engagers/add-to-audience`
+- operationId: `add_social_engagers_to_audience_social_posts__post_id__engagers_add_to_audience_post` (also callable as `g8.api.call("add_social_engagers_to_audience_social_posts__post_id__engagers_add_to_audience_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Build an audience from a post's engagers, creating contacts for the ones not yet in the CRM.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+| `body` | `SocialAudienceFromEngagersRequest` | yes | Request body; fields below. |
+
+Body fields (`SocialAudienceFromEngagersRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_name` | `string \| null` | no | max length 200 |
+
+**Returns** `ApiResponse_SocialAudienceFromEngagers_`: the envelope `{ data: SocialAudienceFromEngagers, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialAudienceFromEngagers` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `added` | `integer` | yes |  |
+| `audience_id` | `integer` | yes |  |
+| `audience_name` | `string` | yes |  |
+| `created` | `integer` | yes |  |
+| `matched` | `integer` | yes |  |
+| `skipped_no_identity` | `integer` | yes |  |
+| `truncated` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.socialPublishing.addSocialEngagersToAudience({ path: { post_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-cancelsocialpost"></a>
+
+### `g8.api.socialPublishing.cancelSocialPost(input)`
+
+**Cancel Social Post**
+
+- HTTP: `POST /api/v1/social/posts/{post_id}/cancel`
+- operationId: `cancel_social_post_social_posts__post_id__cancel_post` (also callable as `g8.api.call("cancel_social_post_social_posts__post_id__cancel_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Take a scheduled post off the schedule. It stays as a post; nothing is published.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+
+**Returns** `ApiResponse_SocialPost_`: the envelope `{ data: SocialPost, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPost` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes |  |
+| `created_by` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `post_type` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `account_ref` | `string \| null` | no |  |
+| `autopilot_config_id` | `string \| null` | no |  |
+| `autopilot_version` | `integer \| null` | no |  |
+| `campaign_id` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `external_post_id` | `string \| null` | no |  |
+| `external_post_url` | `string \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `generation_metadata` | `Record<string, unknown> \| null` | no |  |
+| `generation_sources` | `Array<string> \| null` | no |  |
+| `idea_id` | `string \| null` | no |  |
+| `media` | `Array<Record<string, unknown>> \| null` | no |  |
+| `provider` | `string \| null` | no |  |
+| `published_at` | `string \| null` | no |  |
+| `scheduled_at` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.socialPublishing.cancelSocialPost({ path: { post_id: "id" } });
+```
+
+---
+
+<a id="op-createsocialpost"></a>
+
+### `g8.api.socialPublishing.createSocialPost(input)`
+
+**Create Social Post**
+
+- HTTP: `POST /api/v1/social/posts`
+- operationId: `create_social_post_social_posts_post` (also callable as `g8.api.call("create_social_post_social_posts_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Create a DRAFT post. Nothing is published until you schedule or publish it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SocialPostCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`SocialPostCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | The post text. min length 1, max length 3000 |
+| `body.account_ref` | `string \| null` | no | The account it will publish from - an `id` from `GET /social/accounts`. Optional: a draft can be written before any account is connected, but one is required to schedule or publish. |
+| `body.campaign_id` | `string \| null` | no | Campaign to attribute the post to. |
+| `body.generation_sources` | `Array<string> \| null` | no | max items 10 |
+| `body.idea_id` | `string \| null` | no | The idea from `GET /social/ideas` this came from. |
+| `body.idempotency_key` | `string \| null` | no | Repeat a create with the same key to get the original post back instead of a duplicate. max length 255 |
+| `body.media` | `Array<SocialMediaItem> \| null` | no | max items 9 |
+| `body.post_type` | `"text" \| "image" \| "video" \| "document"` | no | default `"text"` |
+
+**Returns** `ApiResponse_SocialPost_`: the envelope `{ data: SocialPost, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPost` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes |  |
+| `created_by` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `post_type` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `account_ref` | `string \| null` | no |  |
+| `autopilot_config_id` | `string \| null` | no |  |
+| `autopilot_version` | `integer \| null` | no |  |
+| `campaign_id` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `external_post_id` | `string \| null` | no |  |
+| `external_post_url` | `string \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `generation_metadata` | `Record<string, unknown> \| null` | no |  |
+| `generation_sources` | `Array<string> \| null` | no |  |
+| `idea_id` | `string \| null` | no |  |
+| `media` | `Array<Record<string, unknown>> \| null` | no |  |
+| `provider` | `string \| null` | no |  |
+| `published_at` | `string \| null` | no |  |
+| `scheduled_at` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.createSocialPost({ body: { body: "example" } });
+```
+
+---
+
+<a id="op-deletesocialpost"></a>
+
+### `g8.api.socialPublishing.deleteSocialPost(input)`
+
+**Delete Social Post**
+
+- HTTP: `DELETE /api/v1/social/posts/{post_id}`
+- operationId: `delete_social_post_social_posts__post_id__delete` (also callable as `g8.api.call("delete_social_post_social_posts__post_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete a post that has not been published. A published post is not removed from the network.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+
+**Returns** `ApiResponse_SocialDeleted_`: the envelope `{ data: SocialDeleted, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialDeleted` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `deleted` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.socialPublishing.deleteSocialPost({ path: { post_id: "id" } });
+```
+
+---
+
+<a id="op-disconnectsocialaccount"></a>
+
+### `g8.api.socialPublishing.disconnectSocialAccount(input)`
+
+**Disconnect Social Account**
+
+- HTTP: `DELETE /api/v1/social/accounts/{account_id}`
+- operationId: `disconnect_social_account_social_accounts__account_id__delete` (also callable as `g8.api.call("disconnect_social_account_social_accounts__account_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Disconnect an account connected through the official sign-in. 404 for any other kind.
+
+Posts scheduled on it can no longer publish. Reconnecting is a browser sign-in.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | An `id` from `GET /social/accounts`. |
+
+**Returns** `ApiResponse_SocialDeleted_`: the envelope `{ data: SocialDeleted, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialDeleted` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `deleted` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.socialPublishing.disconnectSocialAccount({ path: { account_id: "id" } });
+```
+
+---
+
+<a id="op-enrollsocialengagers"></a>
+
+### `g8.api.socialPublishing.enrollSocialEngagers(input)`
+
+**Enroll Social Engagers**
+
+- HTTP: `POST /api/v1/social/posts/{post_id}/engagers/enroll`
+- operationId: `enroll_social_engagers_social_posts__post_id__engagers_enroll_post` (also callable as `g8.api.call("enroll_social_engagers_social_posts__post_id__engagers_enroll_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Enroll engagers into a sequence. REAL OUTREACH: the sequence starts contacting them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+| `body` | `SocialEnrollEngagersRequest` | yes | Request body; fields below. |
+
+Body fields (`SocialEnrollEngagersRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | yes | `contact_id`s from the post's engagers. min items 1 |
+| `body.sequence_id` | `string` | yes | min length 1 |
+
+**Returns** `ApiResponse_SocialEnrollResult_`: the envelope `{ data: SocialEnrollResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialEnrollResult` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `audience_id` | `integer` | yes |  |
+| `enrolled` | `integer` | yes |  |
+| `sequence_status` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.socialPublishing.enrollSocialEngagers({
+  path: { post_id: "id" },
+  body: { contact_ids: [123], sequence_id: "id" },
+});
+```
+
+---
+
+<a id="op-generatesocialpost"></a>
+
+### `g8.api.socialPublishing.generateSocialPost(input)`
+
+**Generate Social Post**
+
+- HTTP: `POST /api/v1/social/posts/generate`
+- operationId: `generate_social_post_social_posts_generate_post` (also callable as `g8.api.call("generate_social_post_social_posts_generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Draft up to three variants with AI. SPENDS CREDITS (`credits_used`); saves nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SocialPostGenerateRequest` | yes | Request body; fields below. |
+
+Body fields (`SocialPostGenerateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.campaign_id` | `string \| null` | no |  |
+| `body.context` | `string \| null` | no | Older synonym of `instructions`. max length 2000 |
+| `body.frame` | `string \| null` | no | max length 40 |
+| `body.hashtags_max` | `integer` | no | default `3`, min 0, max 3 |
+| `body.idea_id` | `string \| null` | no |  |
+| `body.instructions` | `string \| null` | no | max length 2000 |
+| `body.reference_post` | `string \| null` | no | Someone else's post, used as a structural template only. max length 4000 |
+| `body.refine` | `SocialRefineSpec \| null` | no |  |
+| `body.sources` | `Array<string> \| null` | no | Grounding sources. Omit for the default set (brand_voice, campaign_brief, proof_catalog, inbox_insights). `GET /social/generate/context` says which have data. max items 6 |
+| `body.tone` | `string \| null` | no | max length 200 |
+| `body.variants` | `integer` | no | default `3`, min 1, max 3 |
+
+**Returns** `ApiResponse_SocialGenerated_`: the envelope `{ data: SocialGenerated, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialGenerated` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `credits_used` | `integer` | yes |  |
+| `provenance` | `Array<string>` | yes |  |
+| `variants` | `Array<SocialVariant>` | yes |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.socialPublishing.generateSocialPost({ body: {} });
+```
+
+---
+
+<a id="op-getsocialanalytics"></a>
+
+### `g8.api.socialPublishing.getSocialAnalytics(input?)`
+
+**Get Social Analytics**
+
+- HTTP: `GET /api/v1/social/analytics`
+- operationId: `get_social_analytics_social_analytics_get` (also callable as `g8.api.call("get_social_analytics_social_analytics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Totals and a per-day series across all posts.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Window, in days back from today. default `30` |
+
+**Returns** `ApiResponse_SocialAnalytics_`: the envelope `{ data: SocialAnalytics, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialAnalytics` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `per_day` | `Array<Record<string, unknown>>` | yes |  |
+| `totals` | `Record<string, integer>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.getSocialAnalytics();
+```
+
+---
+
+<a id="op-getsocialautopilot"></a>
+
+### `g8.api.socialPublishing.getSocialAutopilot(input)`
+
+**Get Social Autopilot**
+
+- HTTP: `GET /api/v1/social/autopilot/{account_id}`
+- operationId: `get_social_autopilot_social_autopilot__account_id__get` (also callable as `g8.api.call("get_social_autopilot_social_autopilot__account_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Autopilot configuration for one account, including a disconnected one (so the reconnect state is visible).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | An `id` from `GET /social/accounts`. |
+
+**Returns** `ApiResponse_SocialAutopilot_`: the envelope `{ data: SocialAutopilot, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialAutopilot` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_ref` | `string` | yes |  |
+| `available` | `boolean` | yes |  |
+| `auto_publish_confirmed` | `boolean` | no | default `false` |
+| `configured` | `boolean` | no | default `true` |
+| `direction` | `string` | no | default `""` |
+| `enabled` | `boolean` | no | default `false` |
+| `estimated_generation_credits` | `integer` | no | default `0` |
+| `id` | `string \| null` | no |  |
+| `last_blocking_error` | `string \| null` | no |  |
+| `last_planned_at` | `string \| null` | no |  |
+| `next_slots` | `Array<string>` | no |  |
+| `prompt_version` | `integer` | no | default `1` |
+| `scheduled_count` | `integer` | no | default `0` |
+| `timezone` | `string` | no | default `"UTC"` |
+| `unscheduled_posts` | `integer` | no | default `0` |
+| `weekly_queue_slots` | `Array<SocialQueueSlot>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.getSocialAutopilot({ path: { account_id: "id" } });
+```
+
+---
+
+<a id="op-getsocialgenerationcontext"></a>
+
+### `g8.api.socialPublishing.getSocialGenerationContext(input?)`
+
+**Get Social Generation Context**
+
+- HTTP: `GET /api/v1/social/generate/context`
+- operationId: `get_social_generation_context_social_generate_context_get` (also callable as `g8.api.call("get_social_generation_context_social_generate_context_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Which grounding sources have data for AI drafting.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialGenerationContext_`: the envelope `{ data: SocialGenerationContext, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialGenerationContext` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `brand_voice` | `boolean` | yes |  |
+| `campaign_brief` | `boolean` | yes |  |
+| `inbox_insights` | `integer` | yes |  |
+| `proof_points` | `integer` | yes |  |
+| `recent_content` | `integer` | yes |  |
+| `top_posts` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.getSocialGenerationContext();
+```
+
+---
+
+<a id="op-getsocialpost"></a>
+
+### `g8.api.socialPublishing.getSocialPost(input)`
+
+**Get Social Post**
+
+- HTTP: `GET /api/v1/social/posts/{post_id}`
+- operationId: `get_social_post_social_posts__post_id__get` (also callable as `g8.api.call("get_social_post_social_posts__post_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One post.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+
+**Returns** `ApiResponse_SocialPost_`: the envelope `{ data: SocialPost, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPost` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes |  |
+| `created_by` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `post_type` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `account_ref` | `string \| null` | no |  |
+| `autopilot_config_id` | `string \| null` | no |  |
+| `autopilot_version` | `integer \| null` | no |  |
+| `campaign_id` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `external_post_id` | `string \| null` | no |  |
+| `external_post_url` | `string \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `generation_metadata` | `Record<string, unknown> \| null` | no |  |
+| `generation_sources` | `Array<string> \| null` | no |  |
+| `idea_id` | `string \| null` | no |  |
+| `media` | `Array<Record<string, unknown>> \| null` | no |  |
+| `provider` | `string \| null` | no |  |
+| `published_at` | `string \| null` | no |  |
+| `scheduled_at` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.getSocialPost({ path: { post_id: "id" } });
+```
+
+---
+
+<a id="op-getsocialpostmetrics"></a>
+
+### `g8.api.socialPublishing.getSocialPostMetrics(input)`
+
+**Get Social Post Metrics**
+
+- HTTP: `GET /api/v1/social/posts/{post_id}/metrics`
+- operationId: `get_social_post_metrics_social_posts__post_id__metrics_get` (also callable as `g8.api.call("get_social_post_metrics_social_posts__post_id__metrics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Impressions, reactions, comments and shares from the latest snapshot.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+
+**Returns** `ApiResponse_SocialPostMetrics_`: the envelope `{ data: SocialPostMetrics, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPostMetrics` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `comments` | `integer` | no | default `0` |
+| `fetched_at` | `string \| null` | no |  |
+| `impressions` | `integer` | no | default `0` |
+| `reactions` | `integer` | no | default `0` |
+| `shares` | `integer` | no | default `0` |
+| `supported` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.getSocialPostMetrics({ path: { post_id: "id" } });
+```
+
+---
+
+<a id="op-listsocialaccounts"></a>
+
+### `g8.api.socialPublishing.listSocialAccounts(input?)`
+
+**List Social Accounts**
+
+- HTTP: `GET /api/v1/social/accounts`
+- operationId: `list_social_accounts_social_accounts_get` (also callable as `g8.api.call("list_social_accounts_social_accounts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Connected accounts, their capabilities and this period's publishing capacity.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialAccountList_`: the envelope `{ data: SocialAccountList, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialAccountList` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<SocialAccount>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.listSocialAccounts();
+```
+
+---
+
+<a id="op-listsocialideas"></a>
+
+### `g8.api.socialPublishing.listSocialIdeas(input?)`
+
+**List Social Ideas**
+
+- HTTP: `GET /api/v1/social/ideas`
+- operationId: `list_social_ideas_social_ideas_get` (also callable as `g8.api.call("list_social_ideas_social_ideas_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Post ideas mined from the org's own signals and content.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.source` | `"signal_mining" \| "linkedin_trending" \| "proof_freshness" \| "repurpose" \| "ai" \| null` | no | Only ideas from this source. |
+| `query.refresh` | `boolean` | no | Mine fresh ideas before answering. default `false` |
+
+**Returns** `ApiResponse_SocialIdeas_`: the envelope `{ data: SocialIdeas, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialIdeas` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<SocialIdea>` | yes |  |
+| `sources` | `Record<string, integer>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.listSocialIdeas();
+```
+
+---
+
+<a id="op-listsocialpostengagers"></a>
+
+### `g8.api.socialPublishing.listSocialPostEngagers(input)`
+
+**List Social Post Engagers**
+
+- HTTP: `GET /api/v1/social/posts/{post_id}/engagers`
+- operationId: `list_social_post_engagers_social_posts__post_id__engagers_get` (also callable as `g8.api.call("list_social_post_engagers_social_posts__post_id__engagers_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+People who reacted to or commented on a post, matched to contacts where possible.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+| `query.refresh` | `boolean` | no | Fetch fresh from the network instead of the stored copy. default `false` |
+
+**Returns** `ApiResponse_SocialEngagers_`: the envelope `{ data: SocialEngagers, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialEngagers` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<SocialEngager>` | yes |  |
+| `total` | `integer` | yes |  |
+| `supported` | `boolean` | no | default `true` |
+| `truncated` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.listSocialPostEngagers({ path: { post_id: "id" } });
+```
+
+---
+
+<a id="op-listsocialposts"></a>
+
+### `g8.api.socialPublishing.listSocialPosts(input?)`
+
+**List Social Posts**
+
+- HTTP: `GET /api/v1/social/posts`
+- operationId: `list_social_posts_social_posts_get` (also callable as `g8.api.call("list_social_posts_social_posts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Posts, newest first, with the org-wide count per status.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `"draft" \| "ready" \| "scheduled" \| "publishing" \| "live" \| "failed" \| "cancelled" \| null` | no | Only posts in this state. |
+| `query.page` | `integer` | no | default `1` |
+| `query.page_size` | `integer` | no | default `25` |
+
+**Returns** `ApiResponse_SocialPostPage_`: the envelope `{ data: SocialPostPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPostPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `counts` | `Record<string, integer>` | yes |  |
+| `items` | `Array<SocialPost>` | yes |  |
+| `total` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.listSocialPosts();
+```
+
+---
+
+<a id="op-listsocialproviders"></a>
+
+### `g8.api.socialPublishing.listSocialProviders(input?)`
+
+**List Social Providers**
+
+- HTTP: `GET /api/v1/social/providers`
+- operationId: `list_social_providers_social_providers_get` (also callable as `g8.api.call("list_social_providers_social_providers_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The ways an account can be connected, and what each can do.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialProviderList_`: the envelope `{ data: SocialProviderList, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialProviderList` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<SocialProvider>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.listSocialProviders();
+```
+
+---
+
+<a id="op-pausesocialautopilot"></a>
+
+### `g8.api.socialPublishing.pauseSocialAutopilot(input)`
+
+**Pause Social Autopilot**
+
+- HTTP: `POST /api/v1/social/autopilot/{account_id}/pause`
+- operationId: `pause_social_autopilot_social_autopilot__account_id__pause_post` (also callable as `g8.api.call("pause_social_autopilot_social_autopilot__account_id__pause_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Stop autopilot for one account. Posts it already scheduled stay scheduled.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | An `id` from `GET /social/accounts`. |
+
+**Returns** `ApiResponse_SocialAutopilot_`: the envelope `{ data: SocialAutopilot, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialAutopilot` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_ref` | `string` | yes |  |
+| `available` | `boolean` | yes |  |
+| `auto_publish_confirmed` | `boolean` | no | default `false` |
+| `configured` | `boolean` | no | default `true` |
+| `direction` | `string` | no | default `""` |
+| `enabled` | `boolean` | no | default `false` |
+| `estimated_generation_credits` | `integer` | no | default `0` |
+| `id` | `string \| null` | no |  |
+| `last_blocking_error` | `string \| null` | no |  |
+| `last_planned_at` | `string \| null` | no |  |
+| `next_slots` | `Array<string>` | no |  |
+| `prompt_version` | `integer` | no | default `1` |
+| `scheduled_count` | `integer` | no | default `0` |
+| `timezone` | `string` | no | default `"UTC"` |
+| `unscheduled_posts` | `integer` | no | default `0` |
+| `weekly_queue_slots` | `Array<SocialQueueSlot>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.pauseSocialAutopilot({ path: { account_id: "id" } });
+```
+
+---
+
+<a id="op-publishsocialpost"></a>
+
+### `g8.api.socialPublishing.publishSocialPost(input)`
+
+**Publish Social Post**
+
+- HTTP: `POST /api/v1/social/posts/{post_id}/publish`
+- operationId: `publish_social_post_social_posts__post_id__publish_post` (also callable as `g8.api.call("publish_social_post_social_posts__post_id__publish_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Publish now. PUBLIC AND IRREVERSIBLE from here: the post goes out on the connected account.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+
+**Returns** `ApiResponse_SocialPublishAccepted_`: the envelope `{ data: SocialPublishAccepted, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPublishAccepted` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `post` | `SocialPost` | yes |  |
+| `status` | `string` | yes |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.socialPublishing.publishSocialPost({ path: { post_id: "id" } });
+```
+
+---
+
+<a id="op-savesocialautopilot"></a>
+
+### `g8.api.socialPublishing.saveSocialAutopilot(input)`
+
+**Save Social Autopilot**
+
+- HTTP: `PUT /api/v1/social/autopilot/{account_id}`
+- operationId: `save_social_autopilot_social_autopilot__account_id__put` (also callable as `g8.api.call("save_social_autopilot_social_autopilot__account_id__put", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Configure autopilot for one account.
+
+With `enabled` and `auto_publish_confirmed` both true, autopilot writes AND
+PUBLISHES posts on its own. Requires the campaign-launch permission, as in
+the app.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `string` | yes | An `id` from `GET /social/accounts`. |
+| `body` | `SocialAutopilotSaveRequest` | yes | Request body; fields below. |
+
+Body fields (`SocialAutopilotSaveRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.direction` | `string` | yes | What autopilot should post about. min length 1, max length 2000 |
+| `body.timezone` | `string` | yes | IANA timezone. min length 1, max length 64 |
+| `body.weekly_queue_slots` | `Array<SocialQueueSlot>` | yes | min items 1, max items 14 |
+| `body.auto_publish_confirmed` | `boolean` | no | True lets autopilot PUBLISH what it writes without a human approving each post. default `false` |
+| `body.enabled` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_SocialAutopilot_`: the envelope `{ data: SocialAutopilot, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialAutopilot` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_ref` | `string` | yes |  |
+| `available` | `boolean` | yes |  |
+| `auto_publish_confirmed` | `boolean` | no | default `false` |
+| `configured` | `boolean` | no | default `true` |
+| `direction` | `string` | no | default `""` |
+| `enabled` | `boolean` | no | default `false` |
+| `estimated_generation_credits` | `integer` | no | default `0` |
+| `id` | `string \| null` | no |  |
+| `last_blocking_error` | `string \| null` | no |  |
+| `last_planned_at` | `string \| null` | no |  |
+| `next_slots` | `Array<string>` | no |  |
+| `prompt_version` | `integer` | no | default `1` |
+| `scheduled_count` | `integer` | no | default `0` |
+| `timezone` | `string` | no | default `"UTC"` |
+| `unscheduled_posts` | `integer` | no | default `0` |
+| `weekly_queue_slots` | `Array<SocialQueueSlot>` | no |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.socialPublishing.saveSocialAutopilot({
+  path: { account_id: "id" },
+  body: {
+    direction: "example",
+    timezone: "example",
+    weekly_queue_slots: [{ day: 0, time: "example" }],
+  },
+});
+```
+
+---
+
+<a id="op-schedulesocialpost"></a>
+
+### `g8.api.socialPublishing.scheduleSocialPost(input)`
+
+**Schedule Social Post**
+
+- HTTP: `POST /api/v1/social/posts/{post_id}/schedule`
+- operationId: `schedule_social_post_social_posts__post_id__schedule_post` (also callable as `g8.api.call("schedule_social_post_social_posts__post_id__schedule_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Schedule a post. It PUBLISHES PUBLICLY at `scheduled_at` with no further step.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+| `body` | `SocialPostScheduleRequest` | yes | Request body; fields below. |
+
+Body fields (`SocialPostScheduleRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.scheduled_at` | `string (date-time)` | yes | ISO 8601. Include a timezone offset. |
+
+**Returns** `ApiResponse_SocialPost_`: the envelope `{ data: SocialPost, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPost` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes |  |
+| `created_by` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `post_type` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `account_ref` | `string \| null` | no |  |
+| `autopilot_config_id` | `string \| null` | no |  |
+| `autopilot_version` | `integer \| null` | no |  |
+| `campaign_id` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `external_post_id` | `string \| null` | no |  |
+| `external_post_url` | `string \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `generation_metadata` | `Record<string, unknown> \| null` | no |  |
+| `generation_sources` | `Array<string> \| null` | no |  |
+| `idea_id` | `string \| null` | no |  |
+| `media` | `Array<Record<string, unknown>> \| null` | no |  |
+| `provider` | `string \| null` | no |  |
+| `published_at` | `string \| null` | no |  |
+| `scheduled_at` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.socialPublishing.scheduleSocialPost({
+  path: { post_id: "id" },
+  body: { scheduled_at: "2026-01-01T09:00:00Z" },
+});
+```
+
+---
+
+<a id="op-updatesocialpost"></a>
+
+### `g8.api.socialPublishing.updateSocialPost(input)`
+
+**Update Social Post**
+
+- HTTP: `PATCH /api/v1/social/posts/{post_id}`
+- operationId: `update_social_post_social_posts__post_id__patch` (also callable as `g8.api.call("update_social_post_social_posts__post_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Edit a post that has not gone out yet. Only the fields you send change.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's id. |
+| `body` | `SocialPostUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`SocialPostUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.account_ref` | `string \| null` | no |  |
+| `body.body` | `string \| null` | no | max length 3000 |
+| `body.media` | `Array<SocialMediaItem> \| null` | no | max items 9 |
+| `body.post_type` | `"text" \| "image" \| "video" \| "document" \| null` | no |  |
+
+**Returns** `ApiResponse_SocialPost_`: the envelope `{ data: SocialPost, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialPost` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes |  |
+| `created_by` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `post_type` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `account_ref` | `string \| null` | no |  |
+| `autopilot_config_id` | `string \| null` | no |  |
+| `autopilot_version` | `integer \| null` | no |  |
+| `campaign_id` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `external_post_id` | `string \| null` | no |  |
+| `external_post_url` | `string \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `generation_metadata` | `Record<string, unknown> \| null` | no |  |
+| `generation_sources` | `Array<string> \| null` | no |  |
+| `idea_id` | `string \| null` | no |  |
+| `media` | `Array<Record<string, unknown>> \| null` | no |  |
+| `provider` | `string \| null` | no |  |
+| `published_at` | `string \| null` | no |  |
+| `scheduled_at` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.socialPublishing.updateSocialPost({ path: { post_id: "id" }, body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-socialaccount"></a>
+
+### `SocialAccount`
+
+A connected social account. `id` is what `account_ref` takes everywhere else.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `capabilities` | `SocialCapabilities` | yes |  |
+| `capacity` | `SocialAccountCapacity` | yes |  |
+| `id` | `string` | yes |  |
+| `provider` | `string` | yes |  |
+| `display_name` | `string \| null` | no |  |
+| `profile_url` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+
+<a id="type-socialengager"></a>
+
+### `SocialEngager`
+
+One person who engaged with a post.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `resolution` | `string` | yes |  |
+| `contact_id` | `integer \| null` | no |  |
+| `headline` | `string` | no | default `""` |
+| `linkedin_url` | `string \| null` | no |  |
+
+<a id="type-socialidea"></a>
+
+### `SocialIdea`
+
+One post idea.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fit` | `SocialIdeaFit` | yes |  |
+| `id` | `string` | yes |  |
+| `source` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `concept` | `string` | no | default `""` |
+| `created_at` | `string \| null` | no |  |
+| `drafted_count` | `integer` | no | default `0` |
+| `favorited` | `boolean` | no | default `false` |
+| `primary_hook` | `string \| null` | no |  |
+| `proof_points` | `string \| null` | no |  |
+| `receipts` | `Array<SocialIdeaReceipt>` | no |  |
+| `secondary_hooks` | `Array<string>` | no |  |
+| `why` | `string` | no | default `""` |
+
+<a id="type-socialmediaitem"></a>
+
+### `SocialMediaItem`
+
+One image (or other asset) attached to a post.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `url` | `string` | yes | Publicly fetchable URL of the asset. |
+| `alt` | `string` | no | Alt text. `alt_text` is accepted as a synonym. default `""` |
+| `id` | `string \| null` | no | Asset-library id, when the asset came from there. |
+| `kind` | `string` | no | Asset kind. `image` for a picture. default `"image"` |
+
+<a id="type-socialprovider"></a>
+
+### `SocialProvider`
+
+A way of connecting an account.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `available` | `boolean` | yes |  |
+| `capabilities` | `SocialCapabilities` | yes |  |
+| `connect_method` | `string` | yes |  |
+| `description` | `string` | yes |  |
+| `key` | `string` | yes |  |
+| `label` | `string` | yes |  |
+
+<a id="type-socialqueueslot"></a>
+
+### `SocialQueueSlot`
+
+A weekly publishing slot.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `day` | `integer` | yes | 0 = Monday ... 6 = Sunday. min 0, max 6 |
+| `time` | `string` | yes | HH:MM in the autopilot's timezone. pattern `^\\d{2}:\\d{2}$` |
+
+<a id="type-socialrefinespec"></a>
+
+### `SocialRefineSpec`
+
+Rewrite an existing draft instead of generating from scratch.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes | min length 1, max length 3000 |
+| `instruction` | `string` | yes | min length 1, max length 300 |
+
+<a id="type-socialvariant"></a>
+
+### `SocialVariant`
+
+One generated draft.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes |  |
+| `frame` | `string` | yes |  |