Post API Overview

Available on Basic, Premium, Business, Enterprise plans.

The post endpoint allows you to publish posts to the social networks: Bluesky, Facebook, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Telegram, TikTok, X/Twitter, and YouTube. There are many options to customize your post, such as scheduling posts, adding auto hashtag, auto-post schedule, and more. Often this is used by agencies when multiple stakeholders need to approve a post before it is published. Start publishing posts with the /post POST endpoint.

Approval Workflow

If your publishing workflow requires approval before sending a post, set the requiresApproval field to true. This is equivalent to pausing the post until the approved parameter is set to true.

Approval Workflow Example

The post will have a status of “awaiting approval” until the approved parameter is set to true via the /post PATCH endpoint.

Publish with parameters

Publish your post using the /post endpoint with the requiresApproval field as true. You may also including standard parameters such as scheduleDate.

Status is awaiting approval

The post will be in a status of “awaiting approval” and will be held until approval is granted.

Approve the post

Update the post with the /post PATCH operation setting the approved field as true. The post will now be sent at the scheduled time.

Use notes

Optional: Set notes on the post for reference, such as who needs to approve the post.

Publish the Post with Approval

{
  "requiresApproval": true,
  "notes": "need approval by John Smith" // optional
}

If the scheduleDate is included and the date is in the past, the post will be published immediately upon approval.

Approval Workflow Video

Please see the video below for an example of the approval workflow.

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.

A paid plan is required.

{
  "hashtags": {
    "max": 3, // optional: Integer range 1-10
    "position": "auto" // optional: String "auto" or "end"
  }
}

If you do not want to send any of the above options, pass the Boolean value true instead of an object.

{
  "autoHashtag": true
}

Auto Repost

Automatically reposts your content multiple times at regular intervals, creating evergreen content that stays fresh and visible to your audience. A paid plan is required. Parameters:

repeat: (required) The number of times to repost the content. Must be between 1 and 10.
days: (required) The number of days between each repost. Must be at least 2 days.
startDate: (optional) When to start the repost schedule, in ISO-8601 UTC format. If not specified, the first post will be published immediately. You should use the startDate parameter in lieu of the top-level scheduleDate parameter.

Auto Repost

{
  "repeat": 2, // min 2, max 10
  "days": 5, // min 2
  "startDate": "2021-07-08T12:30:00Z"
}

The response will included all the future scheduled reposts and an autoRepostId for each repost.

Auto Repost Response

{
  "status": "scheduled",
  "scheduleDate": "2025-06-13T12:30:00.000Z",
  "id": "eIT96IYEodNuzU4oMmwG",
  "refId": "9abf1426d6ce9122ef11c72bd",
  "autoRepostId": "F5wdoaOAAGtDQVciExSxL",
  "post": "The most important things are the hardest to say - Stephen King"
}

When creating an auto repost an ID autoRepostId is assigned to track that series of posts. You may get all of the auto reposts for a post with the History call with the autoRepostId. If you need to delete a repost, you can use the DELETE call with the post ID.

Important: When using auto-repost, ensure you follow each social network’s posting frequency guidelines to avoid account restrictions.Note: The autoRepost feature cannot be used together with scheduleDate. If you include both parameters, the scheduleDate will take precedence and autoRepost will be ignored. Please use the startDate parameter instead.

First Comment

Automatically add in a first comment, with media, 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.

{
  "firstComment": {
    "comment": "My first comment", // required
    "mediaUrls": ["https://..."] // Facebook, LinkedIn, and X/Twitter only
  }
}

First Comment Processing Time

When you include a first comment with your post, the API response will be delayed because our system must:

Wait for the original post to be fully published on the social network.
Then add the comment to that published post.

This sequential process results in the following delays:

Most social networks: Approximately 20 second delay.
TikTok: Up to 90 second delay (due to TikTok’s longer content processing time).

Important TikTok Note: For first comments to work properly on TikTok, the post’s visibility parameter must be set to public.

Idempotent Posts

Idempotency is an optional 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:

Idempotency Key

{
  "idempotencyKey": "Unique Key"
}

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 the 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.

Image & 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 & Video Guidelines

Valid 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 will not load or cannot be downloaded in a browser it will likely fail. For example, a DropBox URL that opens the DropBox web app will not work.

If you have a Google Drive Share URL or a Dropbox Share URL, you can just use the URL in the mediaUrls parameter when publishing a post or comment. Ayrshare will automatically convert the share URL to a download link.

We verify the media URL by making a HEAD request. Please be sure the hosting provider is not blocking the HEAD request or the post will fail with a 403 error. For example, here is a HEAD request to the media URL:

Fetch HEAD Request

const run = async () => {
  const url = "https://img.ayrshare.com/012/gb.jpg";
  return await fetch(url, {
    method: "HEAD"
  })
    .then((res) => {
      if (res.ok) {
        return console.log("Success:", res.status, res.statusText);
      } else {
        return console.error("Error:", res.status, res.statusText, res);
      }
    })
    .catch((error) => {
      return console.error("Error Catch:", error);
    });
};

run();

Spaces & Special Characters

We recommend to avoid the following in your media URLs:

Spaces in the URL.
URL encoded spaces in the URL.
Special characters in the URL even if they are url encoded, such as accent marks é.

For example:

https://img.ayrshare.com/012/test .webp

This URL fails because of the space test .webp. We also don’t recommend using URL encoded spaces, such as %20 in the URL - this can also cause issues with some social networks. And this Unsplash image:

https://unsplash.com/photos/a-house-in-the-middle-of-a-field-with-trees-in-the-background-znbmh2-cIj0

This Unsplash image fails because it isn’t directly accessing the image, but showing a web app.

Sanitize File Names & URLs

You can sanitize your file names with a regular express such as /[^a-z0-9\/\.]/gi.

const sanitizeFileName = (url) => url.replace(/[^a-z0-9\/\.]/gi, "_");
sanitizeFileName("tést .webp"); // t_st_.webp

or sanatize a URL

const sanitizeUrl = (url) => {
  const [protocol, rest] = url.split("://");
  const [domain, ...path] = rest.split("/");
  const sanitizedPath = path.join("/").replace(/[^a-z0-9\/\.]/gi, "_");
  return `${protocol}://${domain}/${sanitizedPath}`;
};

// Output: https://img.ayrshare.com/012/t_st_.webp
sanitizeUrl("https://img.ayrshare.com/012/tést .webp");

Additional Information

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.

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, Threads, TikTok, and X/Twitter.

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!

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 \nSome social networks do not currently support line breaks in the post text.

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/or mediaUrls fields.
Specify platform-specific content using platform names as keys.
Include a default key for content to be used on platforms not explicitly specified.

{
  "post": {
    "instagram": "Great IG pic!",
    "facebook": "Great FB pic!",
    "default": "Great default pic!"
  },
  "platforms": ["instagram", "facebook", "linkedin"],
  "mediaUrls": {
    "instagram": "https://img.ayrshare.com/012/gb.jpg",
    "linkedin": "https://img.ayrshare.com/012/gb.jpg",
    "default": "https://img.ayrshare.com/012/gb.jpg"
  }
}

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.

If you need to post multiple images to different platforms, create separate posts for each platform instead of using this multi-platform structure.

Profile Keys

Post to on behalf of user by providing users’ Profile Keys a a body parameter and the additional data in the response. Business or Enterprise Plan required.

Profiles

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:

{
    "post": "<var>Hello</var>, how about a little <b>bold text</b> and <i>italics text</i> and an x<sub>2</sub>?"
    "platforms": ["twitter"]
}

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
`<b>Hello</b>, world!`	`Hello, world!`
`<b>Hello</b>, world!`	`Hello``, world!`
<samp>123</samp>	𝟷𝟸𝟹
<var>Hello</var>	𝓗𝓮𝓵𝓵𝓸
x<sub>2</sub>	x₂
x<sup>2</sup>	x²

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.

Schedule Posts

Create Scheduled 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 2026-07-08T12:30:00Z. Please see utctime for more examples.

{
  "post": "Hello, world!",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["facebook", "instagram"],
  "scheduleDate": "2023-07-08T12:30:00Z"
}

Please see https://www.utctime.net/ on how to convert your local time to Zulu/UTC time. 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 5, 2026, the media must be available on March 5, 2026.

Error Handling for Scheduled vs Immediate PostsThere is an important difference in how validation errors are handled between immediate and scheduled posts:

Immediate Posts
- When publishing immediately (without scheduleDate), if one platform fails validation checks, the other platforms will continue to be processed. For example, if a post exceeds Twitter’s character limit but is valid for Facebook and Instagram, the post will fail on Twitter but still be published to Facebook and Instagram.
Scheduled Posts
- When scheduling posts for future publication (with scheduleDate), all platforms must pass initial validation checks before the post is scheduled. If any platform fails these pre-validation checks, the entire scheduling operation will be rejected and an error will be returned immediately.
- However, some platform-specific errors may not be detected until the actual posting time. In these cases, the scheduled post will attempt to publish to all platforms, and individual platform failures will be reported in the final results without affecting the other platforms.

Check a Scheduled Post Status

You can check the status of a scheduled post several ways:

Set up the Webhook Scheduled Action to automatically receive the status of the scheduled post. This is available for the Business plan and is the recommended method.
Get the status of a scheduled post with the GET call with the post ID.
Check the status in the Ayrshare Dashboard. First switch to the User Profile the post as published under, then go to “Posts” page and search using the Ayrhare Post ID.

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 published. Consider updating the scheduleDate before unpausing.

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.

{
  "post": "Hello, world with a link https://www.ayrshare.com",
  "platforms": ["linkedin"],
  "shortenLinks": true
}

Unsplash Images

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; e.g. [“HubtZZb2fCM”] of image https://unsplash.com/photos/HubtZZb2fCM

{
  "post": "Hello, world!",
  "platforms": ["instagram"],
  "unsplash": "random",
  "unsplash": "search term", // unsplash: "money"
  "unsplash": ["unsplash image ID"] // unsplash: ["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.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Approval Workflow

Approval Workflow Example

Approval Workflow Video

Auto Hashtags

Auto Repost

First Comment

First Comment Processing Time

Idempotent Posts

Image & Video Requirements

Image & Video Guidelines

Valid URL

Spaces & Special Characters

Sanitize File Names & URLs

Additional Information

Download Speed

Video Extension

Image or Video Only

Testing Images and Videos

Line Breaks

Multi-Platform Posts and Media

Profile Keys

Profiles

Rich Text Posts

HTML Elements

CSS Codes

Schedule Posts

Create Scheduled Posts

Check a Scheduled Post Status

Pause Scheduled Posts

Shorten Links

Unsplash Images

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

​Approval Workflow

​Approval Workflow Example

​Approval Workflow Video

​Auto Hashtags

​Auto Repost

​First Comment

​First Comment Processing Time

​Idempotent Posts

​Image & Video Requirements

Image & Video Guidelines

​Valid URL

​Spaces & Special Characters

​Sanitize File Names & URLs

​Additional Information

​Download Speed

​Video Extension

​Image or Video Only

​Testing Images and Videos

​Line Breaks

​Multi-Platform Posts and Media

​Profile Keys

Profiles

​Rich Text Posts

​HTML Elements

​CSS Codes

​Schedule Posts

​Create Scheduled Posts

​Check a Scheduled Post Status

​Pause Scheduled Posts

​Shorten Links

​Unsplash Images

Approval Workflow

Approval Workflow Example

Approval Workflow Video

Auto Hashtags

Auto Repost

First Comment

First Comment Processing Time

Idempotent Posts

Image & Video Requirements

Valid URL

Spaces & Special Characters

Sanitize File Names & URLs

Additional Information

Download Speed

Video Extension

Image or Video Only

Testing Images and Videos

Line Breaks

Multi-Platform Posts and Media

Profile Keys

Rich Text Posts

HTML Elements

CSS Codes

Schedule Posts

Create Scheduled Posts

Check a Scheduled Post Status

Pause Scheduled Posts

Shorten Links

Unsplash Images