> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create scheduled post
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Adds a post to the app's social calendar. The post starts as a `proposal`, which means it's on the calendar but nothing publishes it yet: approve it with [Approve scheduled posts](/api-reference/approve-scheduled-posts), then run [Start scheduling posts](/api-reference/start-scheduling-posts) to hand it to the publisher.
`instagram` and `linkedin` are the only platforms Base44 can publish to, so they're the only ones this endpoint accepts. The app needs a connected account for that platform with publishing permission by the time you schedule the post, not when you create it.
Set `scheduled_at` far enough ahead that it's still in the future when you schedule the post. Scheduling refuses an instant that has already passed and marks the post `failed`, and a failed post can't be revived. Send an offset-aware timestamp, or a naive one that Base44 reads as UTC. `scheduled_timezone` only decides the wall-clock time reported back in `scheduled_local_at`; it never moves the instant the post goes out.
The social calendar endpoints share two rate limits: 20 requests per minute across creating, editing, deleting and approving posts, and 40 requests per minute across the rest. This endpoint counts against the 20.
Only the fields documented here are accepted. Base44 owns the post's id, lifecycle status, plan lineage, workflow binding and publish results, and any other field in the body fails with a 422.
This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/social-calendar/posts
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/social-calendar/posts:
post:
summary: Create scheduled post
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Adds a post to the app's social calendar. The post starts as a
`proposal`, which means it's on the calendar but nothing publishes it
yet: approve it with [Approve scheduled
posts](/api-reference/approve-scheduled-posts), then run [Start
scheduling posts](/api-reference/start-scheduling-posts) to hand it to
the publisher.
`instagram` and `linkedin` are the only platforms Base44 can publish to,
so they're the only ones this endpoint accepts. The app needs a
connected account for that platform with publishing permission by the
time you schedule the post, not when you create it.
Set `scheduled_at` far enough ahead that it's still in the future when
you schedule the post. Scheduling refuses an instant that has already
passed and marks the post `failed`, and a failed post can't be revived.
Send an offset-aware timestamp, or a naive one that Base44 reads as UTC.
`scheduled_timezone` only decides the wall-clock time reported back in
`scheduled_local_at`; it never moves the instant the post goes out.
The social calendar endpoints share two rate limits: 20 requests per
minute across creating, editing, deleting and approving posts, and 40
requests per minute across the rest. This endpoint counts against the
20.
Only the fields documented here are accepted. Base44 owns the
post's id, lifecycle status, plan lineage, workflow binding and publish
results, and any other field in the body fails with a 422.
This endpoint accepts a personal API key. Workspace API keys are
not authorized for it and are rejected with a 403.
operationId: create_post_api_api_apps__app_id__social_calendar_posts_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose social calendar you want.
title: App Id
description: ID of the app whose social calendar you want.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScheduledPostPayload'
responses:
'201':
description: The created post.
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledPostResponse'
'401':
description: Missing or invalid credentials.
'403':
description: >-
You don't have editor access to this app, or you used a workspace
API key.
'404':
description: >-
App not found, or the social calendar is not enabled for your
account.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded (20 requests per minute).
components:
schemas:
CreateScheduledPostPayload:
properties:
platform:
$ref: '#/components/schemas/Platform'
description: >-
Account to publish to. Only `instagram` and `linkedin` are accepted;
the other values this enum carries are platforms Base44 plans for
but can't publish, and sending one fails with a 422.
example: linkedin
title:
type: string
maxLength: 300
minLength: 1
title: Title
description: >-
Title of the post, which labels it on the calendar. It isn't
published as text, except on LinkedIn, where a post with an image
sends it as the image's title.
example: Ship a CRM in an afternoon
body:
type: string
maxLength: 50000
title: Body
description: >-
Body text of the post. Base44 publishes this followed by `hashtags`,
so leave the tags out of it.
example: >-
We replaced our lead spreadsheet with an app we built in an
afternoon. Here's what changed.
scheduled_at:
type: string
format: date-time
title: Scheduled At
description: >-
When the post should publish, as an ISO 8601 timestamp between the
years 2000 and 2100. Send an offset, or a naive timestamp that
Base44 reads as UTC. It has to still be in the future when you
schedule the post.
example: '2026-09-15T14:00:00Z'
scheduled_timezone:
type: string
maxLength: 64
title: Scheduled Timezone
description: >-
IANA timezone name used to render `scheduled_local_at` in the
response. It never moves the instant the post publishes. Defaults to
`UTC`.
default: UTC
example: Asia/Jerusalem
hook:
type: string
maxLength: 500
title: Hook
description: >-
The angle the post leads with, for your own reference on the
calendar. Empty by default.
default: ''
example: pain_point
best_time_reason:
type: string
maxLength: 1000
title: Best Time Reason
description: >-
Why you picked this time, shown alongside the post on the calendar.
Empty by default.
default: ''
example: Weekday afternoons get the most engagement for this audience.
hashtags:
items:
type: string
maxLength: 100
type: array
maxItems: 30
title: Hashtags
description: >-
Up to 30 hashtags, published after `body`. Send them without the
leading `#`; one you include is stripped before publishing.
example:
- buildinpublic
- crm
image_url:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
title: Image Url
description: >-
HTTPS URL of the image to publish with the post. Required for an
Instagram post, which is rejected at publish time without one, and
optional on LinkedIn.
example: https://cdn.example.com/posts/crm-launch.png
image_prompt:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
title: Image Prompt
description: >-
Prompt the image came from, kept for reference. This endpoint
doesn't generate an image from it.
example: A freelancer closing a deal on a laptop, warm morning light
additionalProperties: false
type: object
required:
- platform
- title
- body
- scheduled_at
title: CreateScheduledPostPayload
description: >-
Content and schedule only. Ownership, lifecycle status, workflow
binding,
plan lineage and publish results are server-owned; sending them is an
error
rather than a silently ignored field.
ScheduledPostResponse:
properties:
id:
type: string
title: Id
description: >-
ID of the post. Pass it as `post_id` to the other social calendar
endpoints.
example: 6886b8d390dc7e2f4a2c91b3
app_id:
type: string
title: App Id
description: ID of the app the post belongs to.
example: 6820f3a4e7b91d003c45a1f2
plan_id:
anyOf:
- type: string
- type: 'null'
title: Plan Id
description: >-
ID of the content plan the post was generated from, or `null` for a
post created through [Create scheduled
post](/api-reference/create-scheduled-post).
example: 8c1f9a2e-3b7d-4c5e-9f01-2a3b4c5d6e7f
source_post_id:
anyOf:
- type: string
- type: 'null'
title: Source Post Id
description: >-
ID this post has inside the content plan it came from, or `null` for
a post created through the API.
example: 3f2504e0-4f89-11d3-9a0c-0305e82c3301
platform:
type: string
title: Platform
description: >-
Account the post publishes to. Base44 publishes to `instagram` and
`linkedin`. A post generated from a content plan can also name `x`,
`tiktok`, `reddit` or `facebook`, which Base44 plans for but can't
publish, and scheduling such a post fails it.
example: linkedin
title:
type: string
title: Title
description: >-
Title of the post. It labels the post on the calendar and isn't
published as text, except on LinkedIn, where a post with an image
sends it as the image's title.
example: Ship a CRM in an afternoon
body:
type: string
title: Body
description: >-
Body text of the post. Base44 publishes this followed by `hashtags`,
so leave the tags out of it.
example: >-
We replaced our lead spreadsheet with an app we built in an
afternoon. Here's what changed.
hook:
type: string
title: Hook
description: >-
The angle the post leads with. A plan-generated post carries the
angle the planner picked, such as `pain_point` or `social_proof`; a
post you create carries whatever you sent, or an empty string.
example: pain_point
cover_index:
type: integer
title: Cover Index
description: >-
Zero-based position of the post in the series its content plan
generated, which is how the calendar picks its cover image. Always
`0` for a post created through the API.
example: 0
scheduled_at:
type: string
format: date-time
title: Scheduled At
description: >-
When the post publishes, always in UTC. A post read back from the
calendar carries no offset (`2026-09-15T14:00:00`), while the one
[Create scheduled post](/api-reference/create-scheduled-post)
returns carries `+00:00`. Read both as UTC.
example: '2026-09-15T14:00:00'
scheduled_local_at:
type: string
title: Scheduled Local At
description: >-
The same instant as `scheduled_at`, rendered in `scheduled_timezone`
as an ISO 8601 timestamp. Display only.
example: '2026-09-15T17:00:00+03:00'
scheduled_timezone:
type: string
title: Scheduled Timezone
description: >-
IANA timezone `scheduled_local_at` is rendered in. It never moves
the instant the post publishes.
example: Asia/Jerusalem
best_time_reason:
type: string
title: Best Time Reason
description: >-
Why this time was picked, written by the planner for a
plan-generated post. Empty unless something set it.
example: Weekday afternoons get the most engagement for this audience.
hashtags:
items:
type: string
type: array
title: Hashtags
description: >-
Hashtags published after `body`, without the leading `#`. A leading
`#` you send is stripped before publishing.
example:
- buildinpublic
- crm
image_url:
anyOf:
- type: string
- type: 'null'
title: Image Url
description: >-
HTTPS URL of the image published with the post, or `null` if it has
none. An Instagram post needs one to publish.
example: https://cdn.example.com/posts/crm-launch.png
image_prompt:
anyOf:
- type: string
- type: 'null'
title: Image Prompt
description: >-
Prompt the post's image was generated from, or `null` if there is
none. Kept for reference; this endpoint doesn't generate images from
it.
example: A freelancer closing a deal on a laptop, warm morning light
status:
type: string
title: Status
description: >-
Where the post is in its lifecycle: `proposal` before you approve
it, `scheduled` once approved, `publishing` while it's going out,
then `posted`. `needs_reconnect` means the platform account has to
be reconnected, `not_materialized_plan_limit` that the workspace
plan doesn't cover publishing, `publish_outcome_unknown` that the
platform may have accepted the post but Base44 couldn't confirm it,
and `failed` that the post can't go out.
example: scheduled
workflow_id:
anyOf:
- type: string
- type: 'null'
title: Workflow Id
description: >-
ID of the automation that publishes this post, set once [Start
scheduling posts](/api-reference/start-scheduling-posts) hands it
over, and `null` before that. Its presence is what tells you the
publish time is fixed.
example: 68a1c4f0d21b4e0a3c77e912
type: object
required:
- id
- app_id
- plan_id
- source_post_id
- platform
- title
- body
- hook
- cover_index
- scheduled_at
- scheduled_local_at
- scheduled_timezone
- best_time_reason
- hashtags
- image_url
- image_prompt
- status
- workflow_id
title: ScheduledPostResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Platform:
type: string
enum:
- x
- instagram
- tiktok
- linkedin
- reddit
- facebook
title: Platform
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````