post

Post to social networks and set an auto-post schedule. Please see our Packages if you use Node, Python, Bubble.io, or Airtable.

post
post

https://app.ayrshare.com/api/post
Post to the social networks you have enabled in the web interface. 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 Dashboard.
Request
Response
Request
Headers
Authorization
required
string
Format: Authorization: Bearer API_KEY See Overview for more information.
Body Parameters
post
required
string
The post text sent to the social networks specified in the platforms parameter.
platforms
required
array
Social media platforms to post. Accepts an array of Strings with values: "facebook", "twitter", "linkedin", "instagram", "youtube", "reddit", or "telegram".
media_urls
optional
array
An array of image or video URLs to include in the post. You can use the /upload API to store an image or videos to your gallery. Videos require a Premium or Business Plan. Files have an accepted file ending type: jpg, jpeg, png, webp, gif, mp4, mov, or avi. Alt format: a single string image or video URL can be passed instead of an array of strings. Note on Max Images: Max images per platform: Twitter 4, LinkedIn 5, Instagram 1, and Facebook 10. Note on Videos: Only one video is allowed per post. Note on Content Type: Please be sure the content-type is set appropriately. E.g. image/png, image/jpg, or image/jpeg. Note on Instagram: Required for Instagram posts. Instagram images must be between 320 px and 1080 px and ratio ratio between 0.8 and 1.91. Note on Image/Video Size: Images should be less than 5 MB and videos less than 512 MB. YouTube videos less than 50 GB.
media_captions
optional
array
Facebook only. Set a caption for each media image posted. Accepts an array of string caption text. Each array must correspond to a media url. E.g. ["This is my best pic", "😃 here is the next"] refers to the 1st and 2nd media urls.
carousel
optional
object
Facebook only. Post a carousel of images. Please see below for additional details.
scheduleDate
optional
string
The datetime to schedule a future post. Accepts an ISO-8601 UTC date time. For example use format "YYYY-MM-DDThh:mm:ssZ" and send as "2021-07-08T12:30:00Z".
shorten_links
optional
boolean
Shorten links in the post for all platforms similar to bit.ly. Only URLS starting with http or https will be shortened. Default value: true.
autoSchedule
optional
boolean
Auto schedule posts based on the pre-defined schedule set in the /set-auto-schedule endpoint. Premium or Business Plan required.
autoScheduleTitle
optional
string
Use an autoSchedule pre-defined time group associated with "title" as set in the /set-auto-schedule endpoint. Default value is "default".
auto-hashtag
optional
number
Integer of max number of hashtags to post. Adds the the post relevant hashtags. Takes into account real-time hashtag popularity. Max must be < 5 and > 0. Premium or Business Plan required.
tagged
optional
array
Instagram only. Instagram users to tag a photo. Array of Strings of Instagram @ handles. E.g. ["@ayrshare", "@myHandle"]
unsplash
optional
string
Auto add Unsplash images. - Random Image: value String "random"; e.g. "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
youTubeVisibility
optional
string
YouTube only. Set the visibility of the uploaded video to "private", "unlisted", or "public".
title
optional
string
Reddit or YouTube only. The title of the Reddit or YouTube post.
subreddit
optional
string
Reddit only. The subreddit to send the post. Please be sure to follow the subreddit's posting guidelines.
reddit_link
optional
string
Reddit only. If posting to Reddit and want to post a link to the subreddit. The URL of the link. Example: https://www.my.site.com
Response
200: OK
A successful post will return a 200 code. You will get back a status of "success" with your post IDs for each platform as well as an ID for the Ayrshare platform. You can save the Ayrshare ID in your database for future reference.
{
"status": "success",
"errors": [],
"postIds": [
{
"status": "success",
"id": "1288899996423983105",
"platform": "twitter"
},
{
"status": "success",
"id": "104923907983682_108329000309742",
"platform": "facebook"
}
],
"id": "RhrbDtYh7hdSMc67zC8H"
}
500: Internal Server Error
Example of an error occurred posting to the networks.
{
"status": "error",
"errors": [
{
"action": "post",
"status": "error",
"code": 110,
"message": "Status is a duplicate.",
"post": "Today is a great day",
"platform": "twitter"
},
{
"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"
}

Request Example

cURL
Node.js
Python
PHP
Go
C#
cURL
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"post": "Today is a great day!", "platforms": ["twitter", "facebook", "instagram", "linkedin"]}, "media_urls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"], "unsplash": "random"' \
-X POST https://app.ayrshare.com/api/post
Node.js
const fetch = require("node-fetch");
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
media_urls: ["https://images.ayrshare.com/imgs/GhostBusters.jpg"], //optional
shorten_links: true, // optional
unsplash: "random", // 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'],
'media_urls': ['https://images.ayrshare.com/imgs/GhostBusters.jpg'],
'unsplash': 'random' }
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
require 'vendor/autoload.php'; // Composer auto-loader
$client = new GuzzleHttp\Client();
$res = $client->request(
'POST',
'https://app.ayrshare.com/api/post',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
],
'json' => [
'post' => 'Today is a great day!',
'platforms' => ['twitter', 'facebook', 'instagram', 'linkedin'], // required
'media_urls' => ['https://images.ayrshare.com/imgs/GhostBusters.jpg'], // optional
]
]
);
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
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"},
"media_urls": []string{"https://images.ayrshare.com/imgs/GhostBusters.jpg"},
"unsplash": "random"
}
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\" ],"
+ "\"media_urls\" : [ \"https://images.ayrshare.com/imgs/GhostBusters.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);
}
}
}
}

Additional Endpoint Examples

Post Facebook Carousel images through Ayrshare's API with the carousel body parameter.

"carousel": {
"link": "URL of See More At..."
"items": [
{
"name": "Image name",
"link": "URL when image clicked",
"picture": "URL of image"
},
{
"name": "Image name",
"link": "URL when image clicked",
"picture": "URL of image"
},
]
}

The top-level link parameter is the URL at the end of the carousel.

The items is an array of object containing the picture URL, link URL when the image is clicked, and name of the image displayed in each image card. At least two object must be present in the items array.

Note: Do not use the media_urls with carousel. If media_urls is used, carousels will be ignored.

Please see our Facebook Carousel Blog Post for more information.

YouTube

Posting to YouTube requires either a paid Premium or Business Plan. The following are required body parameters:

{
title: "YouTube Post Title", // Video Title
post: "YouTube Description", // Video description
platforms: ["youtube"],
media_urls: ["https://images.ayrshare.com/imgs/test-video.mp4"], // URL of video, 1 allowed
youTubeVisibility: "unlisted" // "public", "unlisted", or "private"
}

Video on Posting to YouTube via the API

Reddit

The following are required body parameters for posting to Reddit. Please be sure the subreddit allows automated posting.

{
title: "Reddit Post Title",
post: "Reddit post",
platforms: ["reddit"],
subreddit: "test", // the "/" is not required
reddit_link: "https://website.com", // Optional, post a link
}

Profile Keys

Post to on behalf of user by providing users' Profile Keys a a body parameter. Please see here for details. Business Plan required.