Internal API

Social posts

5 endpoints.

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

Create a social post draft (internal)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string \| null`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonSocialPostWriteBody

Field Type Description

content_markdownrequired 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

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

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_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

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.

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

Get a social post (internal)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

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.

PATCH/api/v1/internal/businesses/{business_id}/social_posts/{social_post_id}

Update a social post draft (internal)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`x-internal-api-key`	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.

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

Publish a social post immediately (internal)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`social_post_id`required	path	`string (uuid)`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonSocialPostPublishBody

Field	Type	Description
`target_profile_ids`	`string[]`	string[] fields
`target_formats`	`SocialPostTargetFormatBody[]`	SocialPostTargetFormatBody[] fields SocialPostTargetFormatBody, expanded above.

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/internal/businesses/{business_id}/social_posts/generate

Generate social post caption (internal)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string \| null`
`x-internal-api-key`	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.