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: Authorization: Bearer API_KEY See Overview for more information.
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: 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. ñ, please encode the special characters before sending. Videos require a Premium or Business Plan. 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 "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	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. 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.

200: OK Successful immediate 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.
}

400: Bad Request Network not linked, but trying to post or a duplicate post.

{
    "status": "error",
    "errors": [
        {
            "action": "post",
            "status": "error",
            "code": 156,
            "message": "Youtube does not seem to be linked with Ayrshare. Please confirm the linkage on the Social Accounts page in your dashboard. https://docs.ayrshare.com/additional-info/troubleshooting",
            "platform": "youtube"
        },
        {
            "action": "post",
            "status": "error",
            "code": 110,
            "message": "Status is a duplicate.",
            "post": "Today is a great day",
            "platform": "twitter"
        },
    ],
    "postIds": [],
    "id": "0OGBzZssN5hxy8dMSRaD" // Ayrshare Post ID used for delete, comment, analytics, etc.
}

500: Internal Server Error Example of an error occurred posting to the networks.

{
    "status": "error",
    "errors": [
        {
            "action": "post",
            "status": "error",
            "code": 107,
            "message": "Facebook Error: This status update is identical to the last one you posted. Try posting something different, or delete your previous update.",
            "platform": "facebook"
        }
    ],
    "postIds": [],
    "id": "6APU4qqI7XO7JM3BOy6B" // Ayrshare Post ID used for delete, comment, analytics, etc.
}

200: OK Successful scheduled post.

{
    "status": "scheduled",
    "scheduleDate": "2023-04-01T10:04:12Z",
    "id": "IUiaqFkQP96UJJXYjRpv", // Ayrshare Post ID used for delete, comment, analytics, etc.
    "refId": "9abf1426d6ce9122effdeeddfdfdfd",
    "post": "Genius is eternal patience. - Michelangelo"
}

200: OK Successful scheduled post with a Profile Key.

{
    "status": "success",
    "posts": [
        {
            "status": "scheduled",
            "scheduleDate": "2023-04-01T10:04:12Z",
            "id": "qvu8gysraodz2WFZgRX7", // Ayrshare Post ID used for delete, comment, analytics, etc.
            "refId": "9abf1426d6ce9122effdeeddfdfdfd",
            "profileTitle": "Best Profile",
            "post": "I never thought of myself as being handsome or good-looking or whatever. I always felt like an outsider. - Elton John"
        }
    ]
}

Request Examples

cURL

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

Node.js

const API_KEY = "API_KEY";

fetch("https://app.ayrshare.com/api/post", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        post: "Today is a great day!", // required
        platforms: ["twitter", "facebook", "instagram", "linkedin"], // required
        mediaUrls: ["https://img.ayrshare.com/012/gb.jpg"] //optional
      }),
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

payload = {'post': 'Today is a great day!', 
        'platforms': ['twitter', 'facebook', 'instagram', 'linkedin'],
        'mediaUrls': ['https://img.ayrshare.com/012/gb.jpg']}
headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.post('https://app.ayrshare.com/api/post', 
    json=payload, 
    headers=headers)
    
print(r.json())

PHP

<?php

$curl = curl_init();
$data = [
    "post" => "Today is a great day!",
    "platforms" => ["twitter", "facebook", "instagram", "linkedin", "pinterest"],
    "mediaUrls" => ["https://img.ayrshare.com/012/gb.jpg"]
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ayrshare.com/api/post',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

Go

package main

import (
	"bytes"
	"encoding/json"
	"log"
	"net/http"
)

func main() {
	message := map[string]interface{}{
		"post":      "Today is a great day!",
		"platforms": []string{"twitter", "facebook", "instagram", "linkedin"},
		"mediaUrls": []string{"https://img.ayrshare.com/012/gb.jpg"}
	}

	bytesRepresentation, err := json.Marshal(message)
	if err != nil {
		log.Fatalln(err)
	}

	req, _ := http.NewRequest("POST", "https://app.ayrshare.com/api/post",
		bytes.NewBuffer(bytesRepresentation))

	req.Header.Add("Content-Type", "application/json; charset=UTF-8")
	req.Header.Add("Authorization", "Bearer API_KEY")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal("Error:", err)
	}

	res.Body.Close()
}

C#

using System;
using System.Net;
using System.IO;

namespace PostPOSTRequest_charp
{
    class Post
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/post";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "POST";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                string json = "{\"post\" : \"Today is a great day!\","
                    + "\"platforms\" : [ \"twitter\", \"facebook\", \"instagram\", \"linkedin\" ]," 
                    + "\"mediaUrls\" : [ \"https://img.ayrshare.com/012/gb.jpg\" ]}";

                streamWriter.Write(json);
                streamWriter.Flush();
            }

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

Ruby

require 'httparty'    # gem install httparty

res = HTTParty.post("https://app.ayrshare.com/api/post", 
    headers: {Authorization: "Bearer API_KEY"}, 
    body: {
        post: "Today is a great day!", 
        platforms: ['twitter', 'facebook', 'instagram'],
        mediuaUlrs: ["https://img.ayrshare.com/012/gb.jpg"]
    }).body

puts res

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.

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
}

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

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

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.

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.

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: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200: OK Returns the post object in an Array

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

400: Bad Request ID not found

{
    "action": "history",
    "status": "error",
    "code": 221,
    "message": "History not found.",
    "id": "4W3f3RPr6QSrw8S5Yo8"
}

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

Request Examples

cURL

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

Node.js

const API_KEY = "API_KEY";
fetch("https://app.ayrshare.com/api/post/TBEAAqAMMJoweA9wKHUl", {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

headers = {'Authorization': 'Bearer API_KEY'}

r = requests.get('https://app.ayrshare.com/api/post/TBEAAqAMMJoweA9wKHUl', headers=headers)
    
print(r.json())

PHP

<?php

// URL and authorization details
$url = 'https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl';
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

// Initialize a cURL session
$curl = curl_init();

// Set cURL options
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

// Execute cURL session and get the response
$response = curl_exec($curl);

// Check if any error occurred
if(curl_errno($curl)){
    echo 'Curl error: ' . curl_error($curl);
} else {
    // Decode and re-encode the JSON response to pretty print
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

// Close cURL session
curl_close($curl);

C#

using System;
using System.Net;
using System.IO;

namespace HistoryGETRequest_charp
{
    class History
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

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

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
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 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.

200: OK Post successfully deleted

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

400: Bad Request ID not found

{
    "action": "delete",
    "status": "error",
    "code": 114,
    "message": "Delete id not found.",
    "id": "IdpUOyihLEpIx0d0N9mI" // Ayrshare Post ID used for delete, comment, analytics, etc.
}

Request Examples

cURL

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

Node.js

const API_KEY = "API_KEY";
const id = "Post ID";

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

Python

import requests

payload = {'id': 'Post ID'}
headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.delete('https://app.ayrshare.com/api/post', 
    json=payload, 
    headers=headers)
    
print(r.json())

PHP

<?php

$apiUrl = 'https://app.ayrshare.com/api/post';
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key
$postId = '7NFVK0QIXET5rCUS9tmf'; // Replace with your actual post ID

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$data = json_encode(['id' => $postId]);

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $data
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

C#

using System;
using System.Net;
using System.IO;

namespace DeletePOSTRequest_charp
{
    class Delete
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/post";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "DELETE";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                string json = "{\"id\" : \"Post ID\"}";

                streamWriter.Write(json);
                streamWriter.Flush();
            }

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

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

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY See Overview for more information.
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 "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.

200: OK Successful update.

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

400: Bad Request ID not found

{
    "action": "update",
    "status": "error",
    "code": 305,
    "message": "Error updating post. Post ID not found."
}on

400: Bad Request Invalid scheduleDate

{
    "action": "post",
    "status": "error",
    "code": 104,
    "message": "Invalid schedule date format for scheduleDate. https://docs.ayrshare.com/rest-api/endpoints/post#send-a-post"
}

Request Examples

cURL

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

Node.js

const API_KEY = "API_KEY";

fetch("https://app.ayrshare.com/api/post", {
      method: "PATCH",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        id: "s8k2jsk0pl", // required
        scheduleDate: "2023-07-08T12:30:00Z"]
      }),
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

payload = {'id': 's8k2jsk0pl', 
        'scheduleDate': '2023-07-08T12:30:00Z'}
headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.patch('https://app.ayrshare.com/api/post', 
    json=payload, 
    headers=headers)
    
print(r.json())

PHP

<?php

$apiUrl = 'https://app.ayrshare.com/api/post';
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$data = json_encode([
    'id' => 's8k2jsk0pl',  // Replace with your actual post ID
    'scheduleDate' => '2023-07-08T12:30:00Z'
]);

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $data
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

Go

package main

import (
	"bytes"
	"encoding/json"
	"log"
	"net/http"
)

func main() {
	message := map[string]interface{}{
		"id": "s8k2jsk0pl",
		"scheduleDate": "2023-07-08T12:30:00Z"
	}

	bytesRepresentation, err := json.Marshal(message)
	if err != nil {
		log.Fatalln(err)
	}

	req, _ := http.NewRequest("PATCH", "https://app.ayrshare.com/api/post",
		bytes.NewBuffer(bytesRepresentation))

	req.Header.Add("Content-Type", "application/json; charset=UTF-8")
	req.Header.Add("Authorization", "Bearer API_KEY")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal("Error:", err)
	}

	res.Body.Close()
}

C#

using System;
using System.Net;
using System.IO;

namespace PostPOSTRequest_charp
{
    class Post
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/post";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "PATCH";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                string json = "{\"id\" : \"s8k2jsk0pl\","
                    + "\"scheduleDate\" : \"2023-07-08T12:30:00Z\",";

                streamWriter.Write(json);
                streamWriter.Flush();
            }

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}#

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

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY See Overview for more information.
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".

200: OK Successful scheduling of retry

{
    "status": "pending", // The post will be retried
    "id": "N7kaDiZAfwc544OBKlgc" // Ayrshare Post ID
}

400: Bad Request Retry already done

{
    "action": "post",
    "status": "error",
    "code": 329,
    "message": "This post was already retired and cannot be retired again."
}

Request Examples

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"id": "s8k2jsk0pl"}' \
-X PUT https://app.ayrshare.com/api/post/retry

Node.js

const API_KEY = "API_KEY";

fetch("https://app.ayrshare.com/api/post/retry", {
      method: "PUT",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        id: "s8k2jsk0pl", // required
      }),
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

payload = {'id': 's8k2jsk0pl'}
headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.put('https://app.ayrshare.com/api/post/retry', 
    json=payload, 
    headers=headers)
    
print(r.json())pyth

PHP

<?php

$apiUrl = 'https://app.ayrshare.com/api/post/retry';
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$data = json_encode([
    'id' => 's8k2jsk0pl'  // Replace with your actual ID
]);

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $data
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

Go

package main

import (
	"bytes"
	"encoding/json"
	"log"
	"net/http"
)

func main() {
	message := map[string]interface{}{
		"id": "s8k2jsk0pl"
	}

	bytesRepresentation, err := json.Marshal(message)
	if err != nil {
		log.Fatalln(err)
	}

	req, _ := http.NewRequest("PUT", "https://app.ayrshare.com/api/post/retry",
		bytes.NewBuffer(bytesRepresentation))

	req.Header.Add("Content-Type", "application/json; charset=UTF-8")
	req.Header.Add("Authorization", "Bearer API_KEY")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal("Error:", err)
	}

	res.Body.Close()
}

---

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: Authorization: Bearer API_KEY See Overview for more information.
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.

200: OK Example with two scheduled posts.

{
    "status": "success",
    "posts": [
        {
            "status": "scheduled",
            "scheduleDate": "4/6/21 12:50",
            "id": "X3uTExuEJhyM3u8wCRsA",
            "post": "A great post"
        },
        {
            "status": "scheduled",
            "scheduleDate": "4/6/21 13:00",
            "id": "8RGrekuxMnVa7lVnARFm",
            "post": "An even better postt"
        }
    ]
}

Request Examples

A multipart form-data containing a CSV file of posts will schedule them for a future date.

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: multipart/form-data' \
-F 'file=@"./Ayrshare CSV Template.csv"' \
-X POST https://app.ayrshare.com/api/post/bulk

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.

188B

Ayrshare CSV Template.csv