Endpoint Plan limits Post creation is gated by the checkUserPostLimit middleware. If your account has reached the maxPosts limit for your current plan, the request returns 403 with details about your current usage.
Once usage.postsCreated reaches limits.maxPosts for your plan, all create requests are rejected until you upgrade your subscription or your limit resets on the next billing cycle.
Request body Post content. Post body text. Sent to all selected platforms unless overridden in platformSpecificContent.
Media files to attach to the post. Upload files first using the Media Upload endpoint to obtain s3Url and s3Key values. Show media item properties
content.mediaItems[].s3Url
Full public URL returned by the media upload endpoint.
content.mediaItems[].s3Key
S3 object key returned by the media upload endpoint.
content.mediaItems[].mimeType
MIME type of the file, e.g. image/png, video/mp4.
One or more platforms to publish to. At least one value is required. Accepted values: bluesky, threads, instagram, facebook, mastodon, tumblr.
Per-platform content overrides. Keys are platform names. Each value may contain text and mediaItems that replace the top-level content fields for that platform only.
ISO 8601 datetime string. When provided, the post is queued with status SCHEDULED and published at this time. Omit to publish immediately (PENDING).
IANA timezone name used to interpret scheduledAt, e.g. America/New_York.
Set to DRAFT to save without queueing. Any other value (or omitting) follows the scheduledAt-based logic above.
Status determination status fieldscheduledAt presentResulting status DRAFTany DRAFT — not queuedomitted or other yes SCHEDULEDomitted or other no PENDING — queued immediately
Draft posts are not dispatched to the delivery queue. Publish a draft by updating the post and setting status to something other than DRAFT.
Response "Post created successfully"
MongoDB ObjectId of the newly created post.
Resolved post status: DRAFT, PENDING, or SCHEDULED.
ISO 8601 scheduled publish time. Present only when status is SCHEDULED.
Examples Publish immediately
Schedule a post
Save as draft
Post with media
Platform-specific overrides
curl --request POST \ --url 'https://api.hayon.app/api/posts' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "content": { "text": "Hello from Hayon!" }, "selectedPlatforms": ["bluesky", "mastodon"] }'
Example response { "success" : true , "message" : "Post created successfully" , "data" : { "postId" : "64f1a2b3c4d5e6f7a8b9c0d1" , "status" : "SCHEDULED" , "scheduledAt" : "2024-12-01T09:00:00.000Z" } }
Error responses { "message" : "Post creation limit reached (50/50). Upgrade to Pro for more." , "usage" : 50 , "limit" : 50 }
{ "success" : false , "message" : "Invalid request data" , "data" : { "selectedPlatforms" : { "_errors" : [ "At least one platform must be selected" ] } } }
