post
Schedule posts, auto hashtag, auto-post schedule, and more: Facebook Pages, Instagram, LinkedIn, X/Twitter, Pinterest, YouTube, Telegram, Google Business Profile, Reddit, & TikTok.
POST Send a Post
POST
https://app.ayrshare.com/api/post
Post to the social networks you have enabled in the web dashboard. If you want to post to one or many client profiles, please see the /profiles endpoint.
Please be sure to add your API KEY in place of API_KEY
in the Authorization header. The API Key can be found in the Ayrshare Developer Dashboard under the API Key page.
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Format: |
Profile-Key | string | Profile Key of a user profile. |
Request Body
Name | Type | Description |
---|---|---|
post* | string | The post text sent to the social networks specified in the platforms parameter. You can include URLs in the post or rich text. See below for advanced options. |
platforms* | array | Social media platforms to post. Accepts an array of Strings with values: Use |
mediaUrls | array | An array of image or video URLs to include in the post. You can use the /upload endpoint to store an image or videos to your gallery if you don't have an external URL. Image or a video URLs to natively post to social media. URLs must be secure and begin with Please see below Image and Video Requirements and advanced options. |
isVideo | boolean | Ayrshare will try to determine the media type based on the file extension in the URL (.mp4). You can explicitly set the media a video if the URL does not end in a known video extension, such as animated GIFs. Please see below of details. |
scheduleDate | string | The datetime to schedule a future post. Accepts a UTC date time. For example, use format |
firstComment | object | Add in a first comment automatically after posting. See below for details. |
disableComments | boolean | Disable comments for the post. Only available for Instagram, LinkedIn, and TikTok. |
shortenLinks | boolean | Shorten links in the post for all platforms using Ayrshare's link shortener. Only URLS starting with https will be shortened. Default value: Max Pack required for link shortening. Please see here for using 3rd party link shorteners. |
autoSchedule | object | Please see /auto-schedule endpoint. |
autoRepost | object | Also known as Evergreen Content, automatically repost n times every x days. Premium or Business Plan required.
Parameters:
- Please judiciously auto repost to stay in compliance with the social networks. |
autoHashtag | object | See below for details. |
unsplash | string | See below for details. |
faceBookOptions | object | See Facebook details. |
instagramOptions | object | See Instagram details. |
gmbOptions | object | See Google Business Profile details. |
youTubeOptions | object | See YouTube details. |
redditOptions | object | See Reddit details. |
ads | object | See below for details. |
pinterestOptions | object | See Pinterest details. |
twitterOptions | object | See Twitter details. |
tikTokOptions | object | See TikTok details. |
linkedInOptions | object | See LinkedIn details. |
telegramOptions | object | See Telegram details. |
requiresApproval | boolean | See below for details. |
randomPost | boolean | Generate random post text for testing. |
randomMediaUrl | boolean | Generate a random media image for testing. |
idempotencyKey | string | An optional unique ID associated with the post. Duplicate IDs will be rejected. Please see Idempotent Posts for important information. |
notes | string | Set notes on a post that can be retrieved via the /history endpoint. Notes are fore reference only and do not affect the post. |
Request Examples
Details on Specific Social Networks
Please see the details pages on each social network for examples and options.
Social NetworksProfile Keys
Post to on behalf of user by providing users' Profile Keys a a body parameter and the additional data in the response. Business Plan required.
profilesImage and Video Requirements
Posting images and videos have different requirements for each network, but don't worry. Our system verifies your post before sending, so you'll get an error response if something is wrong. See the below link of details on image and video guidelines.
Image and Video GuidelinesValid URL
Be sure your media URL(s) are valid and directly access the media. A first test is trying the URL in a browser...if the image won't load or be downloaded in a browser it will likely fail.
For example:
fails because of the space test .webp
.
And this Unsplash image:
fails because it isn't directly accessing the image, but showing a web app. Learn more about Unsplash.
Additional Info:
If you're self hosting, make sure the URL can be externally accessed and doesn't require special permissions.
See below the how to handle videos with unknown extensions, often signed URLs such as AWS S3.
If you are using a signed URL, such as S3, we recommend to set the URL expiration to at least 7 days. This allows our team to assist with any questions you have on publishing the post.
Test if the media URL exists with our verify media tools.
Download Speed
Be sure the your media hosting has a fast connection, especially download speed. You can test your media hosting performance at pingdom. We recommend at least a B rating.
Larger Videos
The app.ayrshare.com domain has a 60 second timeout. If the social network takes an extended period to process a video, an HTTP 500 response may be returned - the video will still be published if no errors occur.
We recommend for larger video files over 25 MB or Facebook/Instagram reels to create a scheduled post with the scheduleDate
parameter for async processing or use the beta api.ayrshare.com domain.
Video Extension
If your URL does not end in a known video extension such as mp4, you can use the isVideo: true
field in the post to specify the mediaUrl
is a video . Ayrshare will try to determine the file type, such as MOV. However, we recommend explicitly ending your video file with a known extension, such as mp4, since this has a higher success rate with the social networks.
Image or Video Only
A few social networks support sending media without post text. If you do not want post text included send and empty String post: ""
The following social networks support no post/blank text: Facebook, Instagram, LinkedIn, TikTok, and X/Twitter.
Schedule Posts
You can schedule future posts by specifying the scheduleDate
parameter with the datetime in Zulu/UTC. Zulu Time, also known as Coordinated Universal Time (UTC), is the world standard for time.
For example, use format "YYYY-MM-DDThh:mm:ssZ"
and send as "2023-07-08T12:30:00Z".
Please see https://www.utctime.net/
Note: If the scheduled datetime is in the past, the post will immediately be sent.
If a mediaUrl
is included with a scheduled post, the media must be available at the scheduled publication time. For example, if the post is scheduled to be published on March 1, the media must be available on March 1.
First Comment
Automatically add in a first comment immediately after publishing the post. Posting the first comment on your own social media post can help kickstart engagement and set the tone for the discussion that follows.
Auto Hashtags
Add the most relevant hashtags to your post.
autoHashtag
is an object, or Boolean - see below, with the following parameters:
max
: (optional) Integer of hashtags to add, range 1-10. Default 2.position
: (optional) String "auto" or "end". Auto adds the hashtags within the post or to the end. "end" adds hashtags just to the end.
Premium or Business Plan required.
If you do not want to send any of the above options, pass the Boolean value true
instead of an object.
Approval Workflow
If your workflow, often for agencies, requires approval before sending a post, set the requiresApproval
field to true
. The post will have a status of "awaiting approval" until the approved
parameter is set to true
via the /post PUT operation.
Publish your post using the /post endpoint with the
requiresApproval
field astrue
. You may also including standard parameters such asscheduleDate
.The post will be in a status of "awaiting approval" and will be held until approval is granted.
Update the post with the /post PUT operation setting the
approved
field astrue
. The post will now be sent at the scheduled time.Optional: Set
notes
on the post for reference, such as who needs to approve the post.
Pause Scheduled Posts
You may paused scheduled posts that have not yet been published. Pausing a scheduled post will prevent it from being published until the post has been unpaused.
Use the PATCH call to pause or unpause the scheduled post. Please note if a post is unpaused and the scheduleDate
is in the past the post will immediately be publish. Consider updating the scheduleDate
before unpausing.
Unsplash
Auto add Unsplash Image Parameters
The following fields are available for the unsplash
body parameter:
Random Image:
random
returns a random Unsplash image.Search Based Image: value String search term ; e.g.
money
will select a random image based on money.Image IDs: value Array of Ids [ids]; e.g. ["HubtZZb2fCM"] of image https://unsplash.com/photos/HubtZZb2fCM
If copying an Unsplash URL to post in mediaUrls
, please be sure to copy the image address and not just the URL. Please see this example for more information.
Shorten Links
Links in a post can be shortened using the Ayrshare link shortner. You can turn on the automatic link shortening with the shortenLinks
parameter when sending a post. Max Pack required.
Idempotent Posts
Idempotency is a feature that ensures a request is only executed once, even if it is accidentally sent multiple times. When posting content using the API, you can include an optional idempotencyKey
parameter in the request body to uniquely identify the operation. This allows you to safely retry the post request without the risk of creating duplicate posts.
To use idempotency, add the idempotencyKey
parameter to the JSON body of the /post
POST request:
The value of idempotencyKey
should be a unique string per User Profile. If a request is made with the same idempotencyKey
for a given User Profile, regardless of the post's state (success, error, pending, or deleted), an error will be returned, indicating that a duplicate key was found.
The API must first accept and process the POST request to store the idempotency key and check for duplicates. However, if multiple POST requests with the same idempotencyKey
are sent simultaneously or scheduled for the same posting time, the API may not detect the duplicate keys. This is because the API processes these concurrent or simultaneously scheduled requests in parallel, before it has a chance to register the idempotency key from any single request. As a result, there's no guarantee that duplicate idempotent keys will be caught in these scenarios of simultaneous submission or execution of scheduled posts.
Using idempotency helps prevent accidental creation of duplicate posts when retrying failed requests or handling network issues. However, it's still recommended to implement appropriate error handling and retry mechanisms in your application to handle potential failures gracefully.
Advertising
Take your users' posts to the next level by promoting them as ads. see here for more info:
adsUse Pre-Set Campaign and Group Ids
Preset the campaign
and group
ids with the /ads/twitter/ids endpoint and automatically use these ids when posting and promoting a Tweet with the createAd
boolean parameter. You do not need to send the campaign
or group
ids.
Additional Info
Line Breaks
If you want to line breaks, new lines, in a post, use the invisible line break \u2063\n.
For example, This is a new\u2063\nline.
We also recommend trying in Postman to see how the new line break is translated in your language of choice. For example, PHP often only uses a \n
Some social networks do not currently support line breaks in the post text.
Rich Text Posts
You can add rich text such as "𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂?". You can use rich text on networks such as Twitter, Facebook, LinkedIn, Telegram, and Instagram. If posting to Reddit, please use Reddit-flavored Markdown formatting.
HTML elements are used to specify the type of rich text, which is translated into unicode. For example:
HTML Elements
HTML | Example |
---|---|
<b>Nice One!</b> | Nice One! |
<strong>Hello, world!</strong> | Hello, world! |
<em>World</em> | World |
normal <i>italics <b>bold italics</b></i> | normal italics bold italics |
<pre>Hello, world!</pre> | |
<code><b>Hello</b>, world!</code> |
|
<samp>123</samp> | 𝟷𝟸𝟹 |
<var>Hello</var> | 𝓗𝓮𝓵𝓵𝓸 |
x<sub>2</sub> | x₂ |
x<sup>2</sup> | x² |
Additional CSS Codes
Code | Example | Result |
---|---|---|
\u00B0 | It's 25\u00B0C today! | It's 25°C today! |
\u2063\n | This is a new\u2063\nline. | This is a new line. |
Testing Images and Videos
Consider using the generate random text and random image or video to speed up your testing. Stop trying to think up something different for each of your test posts!
Multi-Platform Posts and Media
This feature allows you to customize your post content and media for different social networks within a single API call. You can specify unique text and/or images for each platform by using objects for the post
and mediaUrls
fields.
Use an object structure for
post
and/ormediaUrls
fields.Specify platform-specific content using platform names as keys.
Include a
default
key for content to be used on platforms not explicitly specified.
In the example above:
Instagram will use its specific text and image URL.
Facebook will use its specific text and the default image URL.
LinkedIn will use the default text and its specific image URL.
Note: If you need to post multiple images to different platforms, create separate posts for each platform instead of using this multi-platform structure.
GET Retrieve a Post
GET
https://app.ayrshare.com/api/post/:id
Get the history for a specific posts sent via Ayrshare. Returns the status, post parameters, and other details. Replace :id
with the Ayrshare Post ID.
Note, you may also call the /history endpoint for the same data.
Post status
fields values:
⮕ awaiting approval
: Posts are awaiting to be approved via the Approval Workflow.
⮕ deleted
: Post has been deleted. Note: deleted posts are only returned with the status query filter. Please see below.
⮕ error
: An error occurred with one or more social networks.
⮕ pending
: The posts has not yet been processed. Typically a scheduled post.
⮕ success
: The post was successfully sent to all social networks.
Path Parameters
Name | Type | Description |
---|---|---|
id* | string | Ayrshare Post ID from /post |
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Format: |
Profile-Key | string | Profile Key of a user profile. |
Please see the /history endpoint for retrieving all posts, including post not sent via Ayrshare.
Request Examples
Get a User Profile Post
Get a post for a particular user profile by passing the profileKey
parameter as a query parameter.
Available for Business Plans.
cURL example:
DELETE Delete a Post
DELETE
https://app.ayrshare.com/api/post
Delete a post using the post ID returned from the /post endpoint. You can delete both published and scheduled posts, but there are some differences based on the social network (platform):
Scheduled posts maybe deleted for all social networks (platforms).
Published posts maybe deleted for all social networks (platforms) except for Instagram and TikTok. Instagram and TikTok do not provide API support for deleting published posts. If you need to delete a published post on these platforms, you must do so manually using their respective mobile apps.
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Format: |
Profile-Key | string | Profile Key of a user profile. |
Request Body
Name | Type | Description |
---|---|---|
id* | string | Ayrshare Post ID of the post to delete. Not required if bulk or deleteAllScheduled parameter sent. If the post is scheduled and still pending, the scheduled posts will be deleted and not sent to the networks. If the post has already been sent to the networks, the post will be deleted from the networks. |
deleteAllScheduled | boolean | If true will delete all scheduled posts still in a pending state, i.e. posts that have not yet been published to the networks.
Required if the |
bulk | array | Array of Strings post Ids to bulk delete. Required if id or deleteAllScheduled parameter not sent. |
Request Examples
Instagram and TikTok do not support delete via their APIs. Please go to the Instagram or TikTok mobile apps to delete the posts.
Delete User Profile Posts
Delete a post for a particular user profile by passing the profileKey
parameter as a body parameter.
Available for Business Plans.
Node.js example:
PATCH Update a Post
PATCH
https://app.ayrshare.com/api/post
Update the scheduleDate
of a post, approval
status of a post, notes
, or visibility
of a posted YouTube video.
⮕ The post must have originally have a scheduleDate
and be in a "pending" status
. The status
can be checked with the /history or GET /post endpoints.
⮕ The YouTube video must have been successfully posted to change visibility.
⮕ The approval workflow requires the current status of the post be in "awaiting approval".
If other parameters need to be updated, delete the post and repost.
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Format: |
Profile-Key | string | Profile Key of a user profile. |
Request Body
Name | Type | Description |
---|---|---|
id* | string | Ayrshare Post ID of the post to update. Ayrshare Post ID returned from /post. |
scheduleDate | string | The datetime to schedule a future post. Accepts a UTC date time. For example, use format Note: If the |
scheduledPaused | boolean | Pause or unpause a scheduled post. If a post us unpaused and the |
approved | boolean | The original post required approval and has a status of "awaiting approval", set to |
disableComments | boolean | Enable or disable comments on a posts. Only Instagram and LinkedIn supported. Disabling LinkedIn comments will delete all existing comments on the thread. Instagram comments will not be deleted. TikTok comments can not be changed after publishing. |
youTubeOptions | object | Update the visibility of the YouTube video with the Update the For example: "youTubeOptions": { "visibility": "unlisted", "description": "awesome", "title": "Title", "categoryId": 24 } |
notes | string | Set notes on a post that can be retrieved via the /history endpoint. Notes are fore reference only and do not affect the post. |
Request Examples
Update a User Profile Post
Update a post for a particular user profile by passing the profileKey
parameter as a body parameter.
Available for Business Plans.
cURL example:
PUT Retry a Post
PUT
https://app.ayrshare.com/api/post/retry
Retry to publish a post that failed with a status
of "error".
A retried post will be treated as a scheduled post, thus the final status can be obtained via the /history endpoint or the scheduled action webhook.
While the post is being retried, the status
will be "pending"
. You may check on the status of the retry by calling the GET post endpoint.
The post can only be retried only once. Recommend to only use if the error message indicates a retry is possible.
When retrying a failed social media post, first verify that the post hasn't already been published. Social networks may sometimes report errors even when they've successfully processed and published the post.
Available for Premium or Business Plan user only.
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Format: |
Profile-Key | string | Profile Key of a user profile. |
Request Body
Name | Type | Description |
---|---|---|
id* | string | The top-level Ayrshare Post ID. The original post must have a status of "error". |
Request Examples
POST Bulk Post
POST
https://app.ayrshare.com/api/post/bulk
Bulk schedule posts with CSV (Comma Separated Values) file of posts data. Content-Type must be multipart/form-data.
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Format: |
Content-Type | string | multipart/form-data |
Profile-Key | string | Profile Key of a user profile. |
Request Body
Name | Type | Description |
---|---|---|
file | object | Multipart form-data CSV file of scheduled posts. See below for template. |
Request Examples
A multipart form-data containing a CSV file of posts will schedule them for a future date.
The CSV file contains the following fields (template below) and are required:
post
: The post text.platforms
: Comma separated list of platforms, e.g. "twitter, facebook, instagram".mediaUrls
: URL of media, such as an image or video to include in the post.scheduleDate
: Datetime to schedule the post in UTC format. For example, use format "YYYY-MM-DDThh:mm:ssZ" and send as "2023-07-08T12:30:00Z". Please see https://www.utctime.net/ for examples.
Don't send duplicate posts less than three days apart.
If the scheduleDate of two posts with the exact same text are less than three days apart, the second post will be rejected when the scheduleDate occurs. This is done to protect your account at the networks; they often suspend or shadow-ban accounts with frequent duplicate posts.
CSV Template
Download the template and save as a .csv file.
Last updated