Ayrshare Docs
Ayrshare HomeLoginBusiness PlanChat with Us
Search
⌃K
Links

post

Schedule posts, auto hashtag, auto-post schedule, and more. Social Media API networks: Facebook Pages, Facebook Groups, Instagram, LinkedIn, Twitter, Pinterest, YouTube, Telegram, Reddit, & TikTok.

Post API Endpoint

❗Click the › in the endpoint to view details.
post
https://app.ayrshare.com/api
/post
Send a Post

Request Examples

cURL
Node.js
Python
PHP
Go
C#
Ruby
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
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", "fbg", "instagram", "linkedin"], // required
mediaUrls: ["https://img.ayrshare.com/012/gb.jpg"] //optional
}),
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
​
payload = {'post': 'Today is a great day!',
'platforms': ['twitter', 'facebook', 'fbg', '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
​
$curl = curl_init();
$data = array (
"post" => "Today is a great day!",
"platforms" => ["twitter", "facebook", "fbg", "instagram", "linkedin", "pinterest],
"mediaUrls" => ["https://img.ayrshare.com/012/gb.jpg"]
);
​
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://app.ayrshare.com/api/post',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => http_build_query($data),
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY',
'Accept-Encoding: gzip'
),
));
​
$response = curl_exec($curl);
curl_close($curl);
echo $response;
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", "fbg", "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()
}
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\", \"fbg\", \"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);
}
}
}
}
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', 'fbg'],
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.

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.

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.
Larger Videos
We recommend for larger video files over 50 MB create a scheduled post with the scheduleDate parameter for async processing.
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 text: Facebook, Facebook Groups, Instagram, TikTok, and 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"
Note: If the 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. 1.
    Publish your post using the /post endpoint with the requiresApproval field as true. You may also including standard parameters such as scheduleDate.
  2. 2.
    The post will be in a status of "awaiting approval" and will be held until approval is granted.
  3. 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. 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 key was already used for User Profile 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:

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

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!
​
get
https://app.ayrshare.com/api
/post/:id
Get a Post
Please see the /history endpoint for retrieving all posts, including post not sent via Ayrshare.

Request Examples

cURL
Node.js
Python
PHP
C#
curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://app.ayrshare.com/api/post/TBEAAqAMMJoweA9wKHUl
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);
import requests
​
headers = {'Authorization': 'Bearer API_KEY'}
​
r = requests.get('https://app.ayrshare.com/api/post/TBEAAqAMMJoweA9wKHUl', headers=headers)
print(r.json())
<?php
require 'vendor/autoload.php';// Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html
​
$client = new GuzzleHttp\Client();
$res = $client->request(
'GET',
'https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
]
]
);
​
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
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
https://app.ayrshare.com/api
/post
Delete a Post

Request Examples

cURL
Node.js
Python
PHP
C#
curl \
-H "Authorization: Bearer API Key" \
-H 'Content-Type: application/json' \
-d '{"id": "Post ID"}' \
-X DELETE https://app.ayrshare.com/api/post
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);
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
require 'vendor/autoload.php'; // Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html
​
$client = new GuzzleHttp\Client();
$res = $client->request(
'DELETE',
'https://app.ayrshare.com/api/post',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
],
'json' => [
'id' => ['7NFVK0QIXET5rCUS9tmf'] // top-level id from post request
]
]
);
​
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
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 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
https://app.ayrshare.com/api
/post
Update a Post

Request Examples

cURL
Node.js
Python
PHP
Go
C#
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
const API_KEY = "API_KEY";
​
fetch("https://app.ayrshare.com/api/post", {
method: "PUT",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${API_KEY}`
},
body: JSON.stringify({
id: "s8k2jsk0pl", // required
scheduleDate: "2023-07-08T12:30:00Z"] // required
}),
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
​
payload = {'id': 's8k2jsk0pl',
'scheduleDate': '2023-07-08T12:30:00Z'}
headers = {'Content-Type': 'application/json',
'Authorization': 'Bearer API_KEY'}
​
r = requests.put('https://app.ayrshare.com/api/post',
json=payload,
headers=headers)
print(r.json())
<?php
require 'vendor/autoload.php'; // Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html
​
$client = new GuzzleHttp\Client(); // Use the HTTP library of your choice
$res = $client->request(
'PUT',
'https://app.ayrshare.com/api/post',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
],
'json' => [
'id' => 's8k2jsk0pl', // required
'scheduleDate' => '2023-07-08T12:30:00Z' // required
]
]
);
​
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
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("PUT", "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()
}
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 = "PUT";
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
https://app.ayrshare.com/api
/post/retryPost
Retry a Post

Request Examples

cURL
Node.js
Python
PHP
Go
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"id": "s8k2jsk0pl"}' \
-X PUT https://app.ayrshare.com/api/post/retryPost
const API_KEY = "API_KEY";
​
fetch("https://app.ayrshare.com/api/post/retryPost", {
method: "PUT",
headers: {