Console API

Social posts

13 endpoints.

GET/api/v1/admin/businesses/{business_id}/social_posts

List social posts for a business

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`status`	query	`string`	Status filter: all\|draft\|queued\|published\|failed default "all"
`platform`	query	`string`	Platform filter: all\|facebook\|instagram default "all"
`search`	query	`string \| null`	Search post content
`cursor`	query	`string \| null`
`direction`	query	`string`	Pagination direction: next\|prev default "next"
`limit`	query	`integer`	default 30
`from_date`	query	`string \| null`	Optional scheduled/published lower bound as YYYY-MM-DD
`to_date`	query	`string \| null`	Optional scheduled/published upper bound as YYYY-MM-DD
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_SocialPostListItemData__

Field Type Description

request_idrequired string

success true default true

datarequired

SocialPostListItemData[]

SocialPostListItemData[] fields

Field	Type	Description
`id`required	`string`
`business_id`required	`string`
`content_preview`required	`string`
`status`required	`enum`	one of "draft", "queued", "publishing", "published", "failed"
`origin`	`string`	default "keystone"
`scheduled_at`	`integer \| null`
`timezone`	`string \| null`
`published_at`	`integer \| null`
`photo_ids`	`string[]`	string[] fields Nested object (not expanded)
`media_status`	`string \| null`
`thumbnail_photo_id`	`string \| null`
`thumbnail_url`	`string \| null`
`primary_profile_name`	`string \| null`
`primary_profile_username`	`string \| null`
`platforms`	`SocialPostPlatformSummary[]`	SocialPostPlatformSummary[] fields Nested object (not expanded)
`engagement`	`SocialEngagementData`	SocialEngagementData fields SocialEngagementData (not expanded)
`last_engagement_synced_at`	`integer \| null`
`has_external_changes`	`boolean`	default false
`external_change_kind`	`string \| null`
`removed_externally`	`boolean`	default false
`created_at`required	`integer`
`updated_at`required	`integer`

metadata

ResponseMetadata | null

ResponseMetadata fields

Field Type Description

pagination

PaginationMetadata | null

PaginationMetadata fields

Field	Type	Description
`limit`required	`integer`
`next_cursor`	`string \| null`
`prev_cursor`	`string \| null`
`has_more`required	`boolean`
`has_prev`	`boolean`	default false
`total_count`	`integer \| null`

status_counts

object | null

object | null fields

Map of string to integer

lifecycle_counts

LifecycleCounts | null

LifecycleCounts fields

Field	Type	Description
`lead`	`integer`	default 0
`prospect`	`integer`	default 0
`customer`	`integer`	default 0
`former_customer`	`integer`	default 0

classification_counts

ClassificationCounts | null

ClassificationCounts fields

Field	Type	Description
`signal`	`object`	object fields Nested object (not expanded)
`touch`	`object`	object fields Nested object (not expanded)
`stage`	`object`	object fields Nested object (not expanded)

meta

ResponseMeta | null

ResponseMeta fields

Field	Type	Description
`total`	`integer \| null`
`total_count`	`integer \| null`
`page`	`integer \| null`
`per_page`	`integer \| null`

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts

Create a social post

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonSocialPostWriteBody

Field	Type	Description
`content_markdown`required	`string`	max length 5000
`link_url`	`string \| null`
`photo_ids`	`string[]`	max items 10 string[] fields
`target_profile_ids`	`string[]`	string[] fields
`target_formats`	`SocialPostTargetFormatBody[]`	SocialPostTargetFormatBody[] fields SocialPostTargetFormatBody, expanded above.
`publish_mode`	`enum`	one of "draft", "publish_now", "schedule" · default "draft"
`scheduled_at`	`integer \| null`
`timezone`	`string \| null`
`workflow_run_id`	`string \| null`
`thread_id`	`string \| null`
`media_status`	`string \| null`

Responses

201Successful Response

application/jsonSuccessResponse_SocialPostData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`SocialPostData`	SocialPostData fields SocialPostData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/social_posts/{social_post_id}

Get a social post

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_SocialPostData_

Field Type Description

request_idrequired string

success true default true

datarequired

SocialPostData

SocialPostData fields

Field Type Description

idrequired string

business_idrequired string

workflow_run_id string | null

thread_id string | null

content_markdownrequired string

link_url string | null

photo_ids

string[]

string[] fields

media_status string | null

statusrequired enum one of "draft", "queued", "publishing", "published", "failed"

origin string default "keystone"

scheduled_at integer | null

timezone string | null

published_at integer | null

kairos_schedule_id string | null

kairos_schedule_status string | null

engagement

SocialEngagementData

SocialEngagementData fields

Field	Type	Description
`likes`	`integer \| null`
`comments`	`integer \| null`
`shares`	`integer \| null`
`views`	`integer \| null`
`reach`	`integer \| null`
`saved`	`integer \| null`

last_engagement_synced_at integer | null

media

SocialPostPreviewMediaData[]

SocialPostPreviewMediaData[] fields

SocialPostPreviewMediaData (not expanded)

targets

SocialPostTargetData[]

SocialPostTargetData[] fields

SocialPostTargetData (not expanded)

available_profiles

SocialProfileData[]

SocialProfileData[] fields

SocialProfileData (not expanded)

has_external_changes boolean default false

created_atrequired integer

updated_atrequired integer

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PUT/api/v1/admin/businesses/{business_id}/social_posts/{social_post_id}

Update a social post

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonSocialPostWriteBody

SocialPostWriteBody, expanded above.

Responses

200Successful Response

application/jsonSuccessResponse_SocialPostData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`SocialPostData`	SocialPostData fields SocialPostData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/admin/businesses/{business_id}/social_posts/{social_post_id}

Delete a social post

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

204Successful Response

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts/{social_post_id}/preview

Preview a social post

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonSocialPostPreviewBody

Field	Type	Description
`surface`required	`enum`	one of "facebook_feed", "facebook_carousel", "instagram_feed", "instagram_carousel"

Responses

200Successful Response

application/jsonSuccessResponse_SocialPostPreviewData_

Field Type Description

request_idrequired string

success true default true

datarequired

SocialPostPreviewData

SocialPostPreviewData fields

Field	Type	Description
`surface`required	`enum`	one of "facebook_feed", "facebook_carousel", "instagram_feed", "instagram_carousel"
`profile_name`required	`string`
`profile_username`	`string \| null`
`profile_avatar_url`	`string \| null`
`caption`required	`string`
`link_url`	`string \| null`
`photo_ids`	`string[]`	string[] fields
`media`	`SocialPostPreviewMediaData[]`	SocialPostPreviewMediaData[] fields SocialPostPreviewMediaData (not expanded)
`engagement`	`SocialEngagementData`	SocialEngagementData fields SocialEngagementData, expanded above.
`created_at`required	`integer`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts/{social_post_id}/publish

Publish a social post immediately

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonSocialPostPublishBody

Field Type Description

target_profile_ids

string[]

string[] fields

target_formats

SocialPostTargetFormatBody[]

SocialPostTargetFormatBody[] fields

Field	Type	Description
`social_profile_id`required	`string`
`format`required	`enum`	one of "facebook_feed", "facebook_carousel", "instagram_feed", "instagram_carousel"

Responses

200Successful Response

application/jsonSuccessResponse_SocialPostPublishResult_

Field Type Description

request_idrequired string

success true default true

datarequired

SocialPostPublishResult

SocialPostPublishResult fields

Field	Type	Description
`social_post`required	`SocialPostData`	SocialPostData fields SocialPostData, expanded above.
`results`required	`SocialPostPublishTargetResult[]`	SocialPostPublishTargetResult[] fields SocialPostPublishTargetResult (not expanded)
`success`required	`boolean`
`successful_count`required	`integer`
`failed_count`required	`integer`
`total_count`required	`integer`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts/{social_post_id}/sync

Sync one post from Meta now (targeted re-read — catches IG edits)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_SocialFeedSyncData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`SocialFeedSyncData`	SocialFeedSyncData fields SocialFeedSyncData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts/{social_post_id}/sync_engagement

Refresh engagement metrics for a published social post

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_SocialEngagementSyncData_

Field Type Description

request_idrequired string

success true default true

datarequired

SocialEngagementSyncData

SocialEngagementSyncData fields

Field	Type	Description
`social_post`required	`SocialPostData`	SocialPostData fields SocialPostData, expanded above.
`synced`required	`integer`
`failed`required	`integer`
`skipped`required	`integer`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/social_posts/calendar_events

List social post calendar events

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`from_date`	query	`string \| null`	Optional lower bound as YYYY-MM-DD
`to_date`	query	`string \| null`	Optional upper bound as YYYY-MM-DD
`platform`	query	`string`	Platform filter: all\|facebook\|instagram default "all"
`status`	query	`string`	Status filter: all\|queued\|published\|failed default "all"
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 200
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_SocialPostCalendarEventData__

Field Type Description

request_idrequired string

success true default true

datarequired

SocialPostCalendarEventData[]

SocialPostCalendarEventData[] fields

Field	Type	Description
`id`required	`string`
`post_id`required	`string`
`target_id`required	`string`
`social_post_id`required	`string`
`social_post_target_id`required	`string`
`social_profile_id`required	`string`
`platform`required	`enum`	one of "facebook", "instagram"
`status`required	`enum`	enum fields Nested object (not expanded)
`scheduled_at`	`integer \| null`
`published_at`	`integer \| null`
`title`required	`string`
`content_preview`required	`string`
`profile_name`	`string \| null`
`profile_username`	`string \| null`
`thumbnail_photo_id`	`string \| null`
`thumbnail_url`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts/full_sync

Admin: deep full sync of all feeds (re-reads every post, catches edits)

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_SocialFeedSyncData_

Field Type Description

request_idrequired string

success true default true

datarequired

SocialFeedSyncData

SocialFeedSyncData fields

Field	Type	Description
`status`required	`string`
`detail`	`object \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts/generate

Generate editable social post content

Generate a caption -- through the workflow when it is enabled.

The workflow path persists the draft (and its photos) and returns it, so the console navigates into an existing post. The inline path returns a caption and nothing else, which is what it has always done.

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string \| null`
`X-Workflow-Bypass`	header	`string \| null`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonSocialPostGenerateBody

Field	Type	Description
`prompt`	`string \| null`
`target_profile_ids`	`string[]`	string[] fields
`platforms`	`enum[]`	enum[] fields
`provider`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_SocialPostGenerateData_

Field Type Description

request_idrequired string

success true default true

datarequired

SocialPostGenerateData

SocialPostGenerateData fields

Field Type Description

content_markdownrequired string

media_briefs

object[]

Photo briefs for the workflow worker to resolve against the media library, in display order. Empty unless social_media_briefs_enabled is on. The inline (non-workflow) callers return them but never act on them.

object[] fields

metadatarequired

SocialPostGenerateMetadata

SocialPostGenerateMetadata fields

Field	Type	Description
`provider`required	`string`
`model`required	`string`
`latency_ms`required	`integer`
`context_sources`	`string[]`	string[] fields Nested object (not expanded)

generation_status string default "completed"

workflow_run_id string | null

thread_id string | null

social_post

SocialPostData | null

SocialPostData fields

SocialPostData, expanded above.

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/social_posts/sync

Sync all connected feeds now (incremental delta from Meta)

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_SocialFeedSyncData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`SocialFeedSyncData`	SocialFeedSyncData fields SocialFeedSyncData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.