post

Schedule posts, auto hashtag, auto-post schedule, and more: Facebook Pages, Facebook Groups, 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, fbg, twitter, linkedin, instagram, youtube, reddit, telegram, gmb, pinterest, or tiktok. Please note: use facebook for Facebook Pages. fbg for Facebook Groups, 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.

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: true.

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

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

pageprofiles

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.

pageImage and Video Guidelines

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 mov, 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, Facebook Groups, 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.

Auto Hashtags

Adds the the post relevant hashtags. Takes into account real-time hashtag popularity.

autoHashtag is an object, or Boolean - see below, with the following parameters:

  • max: (optional) Integer of hashtags to add, range 1-5. 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.

Post max length 1,000 characters, else hashtags will not added.

Premium or Business Plan required.

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

If you do not want to send any of the above options, pass the Boolean value trueinstead 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.

By default, links in a post are shortened using the Ayrshare link shortner. You can turn off the automatic link shortening with the shortenLinks parameter when sending a post.

{
    "shortenLinks": false
}

Idempotent Posts

Idempotency allows you to safely retry posts without accidentally performing the same operation twice.

Add the optional idempotencyKey body parameter to the /post POST with your key as a unique String.

{
    "idempotencyKey": "Unique Key"
}

The key is unique per User Profile. If a duplicate key for a given User Profile is found an error will be returned.

The post must first be accepted to store the idempotency key and perform the check. Two posts with the same key are sent at the exact same time are not guaranteed to fail.

Advertising

Take your users' posts to the next level by promoting them as ads. see here for more info:

pageads

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 published posts or scheduled posts. Takes a post id returned from the /post. Note, Instagram, Facebook Groups, and TikTok do not support delete.

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 - has not yet been published to the networks. Required if id or bulk parameter 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 Facebook Groups do not support delete via an API. Please go to instagram.com or facebook.com 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);

PUT Update a Post

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

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

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
    "id": "N7kaDiZAfwc544OBKlgc" // Ayrshare Post ID
}

Request Examples