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

NameTypeDescription

Authorization*

string

Format: Authorization: Bearer API_KEY See Overview for more information.

Profile-Key

string

Profile Key of a user profile.

Request Body

NameTypeDescription

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.

platforms*

array

Social media platforms to post. Accepts an array of Strings with values: facebook, twitter, linkedin, instagram, youtube, reddit, telegram, gmb, pinterest, or tiktok. Please note: use facebook for Facebook Pages, and gmb for Google Business Profile.

Use all to post to all linked social networks. Also include the required fields for al social network. E.g. title must be included in youTubeOptions if youtube is linked.

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 https://. If the URL has special characters, e.g. nĖƒ, please encode the special characters before sending. Videos require a Premium or Business Plan.

Please see below Image and Video Requirements for more details.

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 "YYYY-MM-DDThh:mm:ssZ" and send as "2023-07-08T12:30:00Z". Please 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: false.

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: - repeat: (required) integer n times, max 10 - days: (required) integer x times, min 3 - startDateTime: (optional) as an ISO-8601 UTC date time. If not present, the first post will send immediately. { repeat: 3, days: 5, startDateTime: "2021-07-08T12:30:00Z" }

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

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. randomPost: true will ignore the post field.

randomMediaUrl

boolean

Generate a random media image for testing. randomMediaUrl: true will ignore the mediaUrls field.

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.

{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "1288899996423983105", // Twitter Social ID
            "platform": "twitter",
            "postUrl": "https://twitter.com/handle/status/1288899996423983105"
        },
        {
            "status": "success",
            "id": "104923907983682_108329000309742", // Facebook Social ID
            "platform": "facebook",
            "postUrl": "https://www.facebook.com/104923907983682_108329000309742",
        },
        {
            "status": "success",
            "platform": "instagram", // Instagram Social ID
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "usedQuota": 12
        },
        {
            "status": "success",
            "id": 635, // Telegram Social ID
            "postUrl": "https://t.me/c/1424847122/635",
            "platform": "telegram"
        }
    ],
    "id": "RhrbDtYh7hdSMc67zC8H"    // Ayrshare Post ID used for delete, analytics, comments, etc.
}

Request Examples

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"post": "Today is a great day!", "platforms": ["twitter", "facebook", "instagram", "linkedin"], "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"]}' \
-X POST https://app.ayrshare.com/api/post

Details on Specific Social Networks

Please see the details pages on each social network for examples and options.

Social Networks

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 Plan required.

profiles

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

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

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

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.

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.

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

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.

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

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

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

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

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

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

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

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
}

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.

It's important to note that the post request must first be accepted by the API to store the idempotency key and perform the duplicate check. If two post requests with the same idempotencyKey are sent simultaneously, there is no guarantee that both requests will fail, as the key may not have been stored yet.

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:

ads

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

{
    "post": "Today is a great day!",
    "platforms": [
        "twitter"
    ],
    "ads": {
        "twitter": {
            "createAd": true
        }
    }
}

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.

Rich Text Post example

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

HTMLExample

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

Hello, world!

<code><b>Hello</b>, world!</code>

Hello, world!

<samp>123</samp>

𝟷ðŸļðŸđ

<var>Hello</var>

𝓗ð“Ūð“ĩð“ĩð“ļ

x<sub>2</sub>

x₂

x<sup>2</sup>

xÂē

Additional CSS Codes

CodeExampleResult

\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!


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

NameTypeDescription

id*

string

Ayrshare Post ID from /post

Headers

NameTypeDescription

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Profile-Key

string

Profile Key of a user profile.

[
    {
        "tier": "business",
        "status": "success",
        "mediaUrls": [
            "https://img.ayrshare.com/012/gb.jpg"
        ],
        "postIds": [
            {
                "platform": "facebook",
                "postUrl": "https://www.facebook.com/1105775157895689_361710168628052",
                "status": "success",
                "id": "105775157895689_361710168628052" // Facebook Social ID
            }
        ],
        "id": "TBEEAqAMMJoweA8wKHUp",
        "errors": [],
        "platforms": [
            "facebook"
        ],
        "scheduleDate": "2020-11-05T12:21:29Z",
        "created": "2022-05-20T17:25:06Z",
        "shortenLinks": true,
        "post": "Today is a great day",
        "type": "scheduled"
    }
]

Please see the /history endpoint for retrieving all posts, including post not sent via Ayrshare.

Request Examples

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://app.ayrshare.com/api/post/TBEAAqAMMJoweA9wKHUl

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:

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://app.ayrshare.com/api/history/9dJk82s901X?profileKey=ldfnk0s82j-Hjdkws-jksjwa8-j2jksd

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

NameTypeDescription

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Profile-Key

string

Profile Key of a user profile.

Request Body

NameTypeDescription

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 id or bulk parameter is not sent.

bulk

array

Array of Strings post Ids to bulk delete. Required if id or deleteAllScheduled parameter not sent.

{
    "twitter": {
        "action": "delete",
        "status": "success",
        "id": "1288900099663775749" // Twitter Social ID
    },
    "facebook": {
        "action": "delete",
        "status": "success",
        "id": "104920007983682_108683297607743" // Facebook Social ID
    },
    "status": "success"
}

Request Examples

curl \
-H "Authorization: Bearer API Key" \
-H 'Content-Type: application/json' \
-d '{"id": "Post ID"}' \
-X DELETE https://app.ayrshare.com/api/post

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:

const API_KEY = "API_KEY";
const PROFILE_KEY = "PROFILE_KEY";
const id = "Post ID"; // Ayrshare Post ID used for delete, comment, analytics, etc.

fetch("https://app.ayrshare.com/api/post", {
      method: "DELETE",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({ 
        profileKey: PROFILE_KEY,  // a single Profile Key passed as a String
        id 
      }),
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

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

NameTypeDescription

Authorization*

string

Format: Authorization: Bearer API_KEY See Overview for more information.

Profile-Key

string

Profile Key of a user profile.

Request Body

NameTypeDescription

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 "YYYY-MM-DDThh:mm:ssZ" and send as "2023-07-08T12:30:00Z". Please see https://www.utctime.net/

Note: If the datetime is in the past, the post will immediately be sent.

approved

boolean

The original post required approval and has a status of "awaiting approval", set to true to approve and send the post.

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 visibility field and values "unlisted", "private", or "public".

Update the description, title, or categoryId. If no description or categoryId originally set, the default values are "" and 24 (Entertainment), respectively.

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.

{
    "status": "success",
    "id": "ZSU1tnnuykDy25wA6kvX", // Ayrshare Post ID
    "scheduleDate": "2025-07-08T12:30:00Z"
}

Request Examples

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"id": "s8k2jsk0pl", "scheduleDate": "2023-07-08T12:30:00Z"}' \
-X PATCH https://app.ayrshare.com/api/post

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:

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"id": "s8k2jsk0pl", "scheduleDate": "2023-07-08T12:30:00Z", "profileKey": "6EAL0QQ-JGMMFE7-GJ1CHNQ-7L7ESA0"}' \
-X PUT https://app.ayrshare.com/api/post

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

NameTypeDescription

Authorization*

string

Format: Authorization: Bearer API_KEY See Overview for more information.

Profile-Key

string

Profile Key of a user profile.

Request Body

NameTypeDescription

id*

string

The top-level Ayrshare Post ID. The original post must have a status of "error".

{
    "status": "pending", // The post will be retried