Postly
  1. Posts
Postly
  • Overview
  • Workspaces
    • Fetch workspaces
      GET
  • Social Accounts
    • Fetch social accounts
      GET
  • Files
    • Upload a file
      POST
    • Fetch files
      GET
    • Delete a file
      DELETE
  • Posts
    • Create a post
      POST
    • Update a post
      PUT
    • Fetch a post
      GET
    • Fetch posts
      GET
    • Delete a post
      DELETE
  1. Posts

Create a post

POST
/posts
Publishes a post with optional text and media to specified target platforms
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.postly.ai/v2/posts' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY;' \
--data-raw '{
    "text": "string",
    "timezone": "string",
    "media": [
        {
            "url": "string",
            "type": "string"
        }
    ],
    "target_platforms": [
        {
            "identifier": "string",
            "id": "string"
        }
    ],
    "workspace": "string",
    "one_off_schedule": {
        "one_off_date": "string",
        "time": "string",
        "timezone": "string"
    },
    "recurring_schedule": {
        "expression": "string",
        "start_date": "string",
        "end_date": "string",
        "time": "string",
        "timezone": "string",
        "week_days": [
            {
                "num": "string",
                "value": true
            }
        ],
        "day_of_month": 0,
        "rate_value": 0,
        "rate_unit": "string"
    },
    "platform_posts": [
        {
            "identifier": "string",
            "text_override": "string",
            "media_override": [
                {
                    "url": "string",
                    "type": "string"
                }
            ],
            "settings": {
                "identifier": "string",
                "tags": [
                    "string"
                ],
                "language_tags": "string",
                "one_off_schedule": {
                    "one_off_date": "string",
                    "time": "string",
                    "timezone": "string"
                },
                "recurring_schedule": {
                    "expression": "string",
                    "start_date": "string",
                    "end_date": "string",
                    "time": "string",
                    "timezone": "string",
                    "week_days": [
                        {
                            "num": "string",
                            "value": true
                        }
                    ],
                    "day_of_month": 0,
                    "rate_value": 0,
                    "rate_unit": "string"
                }
            }
        }
    ]
}'
Response Response Example
200 - PostEnqueueSuccess
{
    "code": 200,
    "message": "Post enqueued successfully",
    "data": {
        "_id": "683594f9d6bb51f6b3000000",
        "text": "Concido terror utroque ultra vado abeo. Turbo adiuvo deinde. Arbitro terebro ducimus ubi hic ipsum vilitas viridis.",
        "media": [
            {
                "url": "https://ideal-digestive.net/",
                "type": "image/png"
            },
            {
                "url": "https://fussy-acquaintance.com/",
                "type": "video/mp4"
            }
        ],
        "timezone": "Europe/Zurich",
        "one_off_schedule": {
            "one_off_date": "2026-02-21",
            "time": "2025-05-11T04:12:10.979Z",
            "timezone": "America/Inuvik"
        },
        "recurring_schedule": {
            "expression": "cron(*)",
            "start_date": "2025-06-22",
            "end_date": "2025-04-23",
            "time": "2025-04-20T16:37:54.216Z",
            "timezone": "Arctic/Longyearbyen",
            "week_days": [
                {
                    "num": 0,
                    "value": true
                },
                {
                    "num": 2,
                    "value": true
                },
                {
                    "num": 1,
                    "value": true
                }
            ],
            "day_of_month": 10,
            "rate_value": 10,
            "rate_unit": "minute"
        },
        "created_at": "2025-05-29T07:40:45.530Z",
        "updated_at": "2025-12-29"
    }
}

Request

Authorization
API Key
Add parameter in header
X-API-KEY
Example:
X-API-KEY: ********************
or
Body Params application/json
text
string 
optional
Optional text content of the post
timezone
string 
required
Optional timezone for scheduling the post, in IANA format (e.g., "Africa/Lagos")
media
array [object {2}] 
optional
Optional media items to include in the post
url
string 
required
Public URL of the uploaded file
type
string 
required
MIME type of the media (e.g., image/png, video/mp4)
target_platforms
array[object (PostTargetPlatform) {2}] 
required
The platforms this post should be published to
identifier
string 
required
Unique name of the platform (e.g., facebook)
id
string 
required
For platforms with pages (e.g., Facebook, LinkedIn, YouTube), this is the page ID.
For platforms without pages (e.g., TikTok, Bluesky, X/Twitter), this is the account ID.
workspace
string 
required
24-character hexadecimal workspace identifier
one_off_schedule
object (OneOffSchedule) 
optional
Optional one-off schedule for the post
one_off_date
string 
required
Date for a one-time post as a valid ISO 8601 date-time string
time
string 
required
Time of day for the scheduled post, as a valid ISO 8601 date-time string
timezone
string 
optional
Timezone for interpreting dates and times (default "UTC")
recurring_schedule
object (RecurringSchedule) 
optional
Optional recurring schedule for the post
expression
string 
required
Cron or rate expression defining the schedule. E.g "cron(0 9 * * ? *)" # Every day at 09:00 UTC
start_date
string 
required
Start date for the recurring schedule
end_date
string 
optional
End date of the recurring schedule
time
string 
required
Time of day for the scheduled post, as a valid ISO 8601 date-time string
timezone
string 
optional
Timezone for interpreting dates and times (default "UTC")
week_days
array[object (WeekDayMapping) {2}] 
optional
Optional Map of weekdays (0=Sunday to 6=Saturday) to include in recurring schedules
day_of_month
integer 
optional
Day of month for monthly schedules
rate_value
integer 
optional
Value for rate-based schedules
rate_unit
string 
optional
Unit for rate-based schedules
platform_posts
array[object (PlatformPost) {4}] 
optional
Optional platform specific posts to override original content
identifier
string 
required
Platform identifier for this post
text_override
string 
optional
Optional text to override the original content for this platform
media_override
array[object (FileData) {2}] 
optional
Optional media list to override the original media for this platform
settings
optional
Base settings for platform-specific post scheduling and metadata. E.g specify bluesky specific settings like language, labels
Examples

Responses

🟢200PostCreateSuccess
application/json
Body
code
string 
required
200
message
string 
required
Post enqueued successfully
data
object (Post) 
required
Enqueued post details
_id
string 
required
24-character hexadecimal post identifier
text
string 
optional
Text content of the post
media
array [object {2}] 
optional
Post media
timezone
string 
optional
Timezone used for scheduling (IANA format)
one_off_schedule
object (OneOffSchedule) 
optional
Optional one off schedule for one time posts
recurring_schedule
object (RecurringSchedule) 
optional
Optional recurring schedule for recurring posts
created_at
string 
required
Date string when post was created
updated_at
string 
required
Date string when post was updated
🟠400BadRequestResponse
🟠401UnAuthorizedResponse
Modified at 2025-05-29 23:51:42
Previous
Delete a file
Next
Update a post
Built with