Post API Overview

The post endpoint allows you to publish posts to the social networks: Facebook Pages, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, 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.

Start publishing posts with the /post POST endpoint.

​

Approval Workflow

If your workflow requires approval before sending a post, set the requiresApproval field to true. This is a common workflow for agencies, for example.

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

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

​

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
}

​

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.

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

​

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:

{
  "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.

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.

​

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.

​

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 can not be downloaded in a browser it will likely fail.

​

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");

​

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.

For file uploads greater than 10 MB, obtain a presigned URL to upload a file.

​

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.

​

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

​

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.

1. Use an object structure for post and/or mediaUrls fields.
2. Specify platform-specific content using platform names as keys.
3. 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.

​

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.

​

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

​

CSS Codes

​

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 2023-07-08T12:30:00Z.

"scheduleDate": "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.

​

Check a Scheduled Post Status

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

• Setup 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.

{
  "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

"unsplash": "random"
"unsplash": "search term"           // unsplash: "money"
"unsplash": ["unsplash image ID"]   // unsplash: ["HubtZZb2fCM"]