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 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 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", "telegram", or "tiktok".
mediaUrls
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 if you don't have an external URL. Videos require a Premium or Business Plan. Please see below "Image and Video Requirements" for more 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".
shortenLinks
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
object
Auto schedule posts based on the pre-defined schedule set in the /set-auto-schedule endpoint. Parameters: - schedule: (required) boolean - title: (optional) string. "title" references the schedule set in the /set-auto-schedule endpoint. Default title is "default". Premium or Business Plan required. { schedule: true, title: "Schedule Title" }
autoRepost
optional
object
Automatically repost n times every x days. Parameters: - repeat: (required) integer n times, max 10 - days: (required) integer x times, min 3 - startDateTime: (optional) as an ISO-8601 UTC date time. In not present, first post will send immediately. Premium or Business Plan required. { repeat: 3, days: 5, startDateTime: "2021-07-08T12:30:00Z" }
autoHashtag
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.
unsplash
optional
string
See below for details
faceBookOptions
optional
object
See below for details.
instagramOptions
optional
object
See below for details.
youTubeOptions
optional
object
See below for details.
redditOptions
optional
object
See below for details
ads
optional
object
See below for details
Response
200: OK
A successful post will return a 200 code with a status of "success". The top-level "id" is Ayrshare's reference ID for the overall post. "postIds" contains reference IDs for each platform (generated by the social network). We suggest saving the Ayrshare "id" in your database for future reference, such as with the /delete or /analytics endpoints.
{
"status": "success",
"errors": [],
"postIds": [
{
"status": "success",
"id": "1288899996423983105",
"platform": "twitter"
},
{
"status": "success",
"id": "104923907983682_108329000309742",
"platform": "facebook"
}
],
"id": "RhrbDtYh7hdSMc67zC8H"
}
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"
}
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"
}

Request Examples

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"], "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"]}' \
-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
mediaUrls: ["https://images.ayrshare.com/imgs/GhostBusters.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://images.ayrshare.com/imgs/GhostBusters.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
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
'mediaUrls' => ['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"},
"mediaUrls": []string{"https://images.ayrshare.com/imgs/GhostBusters.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://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

Instagram

Post images or videos directly to Instagram.

Instagram has the following requirements and restrictions:

  • Business Instagram Account connected with a Facebook Page - see here.

  • Only 25 Instagram posts are allowed over a 24 hour period - around 750 posts a month. See below for usedQuota

  • The post text may contain up to 30 hashtags (e.g. #wildtimes) and 20 username mentions (e.g. @natgeo).

  • @Mentioned Instagram users will receive a notification.

  • Maximum 2,200 post characters, 30 hashtags, and 20 @ tags.

  • Multi-image posts are not supported.

  • Delete not supported using the /delete endpoint.

Note: The aspect ratio of images & videos and the duration of video are very important to successfully post to Instagram. If they do not meet the requirements, the post will be rejected.

Please see the Instagram section of Image and Video Guidelines:

Instagram Business Account

Your Instagram account must be a Business Account and connected with a Facebook Page. The setup is free and easy.

See here for detailed instructions:

Additional Post Parameters - User Tags and Location

The Instagram user will be notified when you use their username in a post. Please be cautious to not spam users or post with their username repeatedly. If you do, Instagram will suspend or deactivate your account.

An image can be tagged with Instagram users and images/videos can be tagged with a location, for a given Facebook Page Id, using the instagramOptions parameter.

In the following example, a location is specified by a locationId, which is a Facebook Page Id of the Guggenheim Museum. Users are specified by a userTags containing an Array of objects with an Instagram username and x/y coordinates on the image.

  • Usernames must be public Instagram accounts.

  • x and y values must be float numbers that originate from the top-left of the image, with a range of 0.01.0.

{
"post": "Let it go!",
"platforms": [
"instagram"
],
"media_urls": [
"https://images.ayrshare.com/imgs/GhostBusters.jpg"
],
"instagramOptions": {
"locationId": 7640348500,
"userTags": [
{
"username": "ayrshare",
"x": 0.5,
"y": 0.5
},
{
"username": "ayrshare",
"x": 0.3,
"y": 0.2
}
]
}
}

Post Response

The Instagram response will include the current usedQuota for the number of Instagram posts done over a rolling 24-hours period. Only 25 Instagram posts are permitted by Instagram in a 24-rolling-hour period.

{
"status": "success",
"errors": [],
"postIds": [
{
"status": "success",
"id": "17823977408036085",
"usedQuota": 15,
"platform": "instagram"
}
],
"id": "l4FaPHSXWJNdmMfm3dIE"
}

If the quota has been reached, an error message will be returned.

Facebook

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

{
"faceBookOptions": {
"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.

Media Captions

Set a caption for each Facebook 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 one"] refers to the 1st and 2nd urls in mediaUrls.

{
"faceBookOptions": {
"mediaCaptions": ["This is my best pic", "😃 here is the next one"]
}
}

Page Mentions

You can mention another Facebook Page by including the following in the post text. Note, Premium or Business Plan required for mentions.

@[page-id]

An example post text: "This is the best post by @[109905187950644]".

The Facebook Page id will resolve to the matching page and notify the other page of mention.

To find your Page ID:

  1. From News Feed, click Pages in the left side menu.

  2. Click your Page name to go to your Page.

  3. Click About at the top of your Page. If you don't see it, click More.

  4. Scroll down to find your Page ID below MORE INFO.

YouTube

Posting to YouTube requires either a paid Premium or Business Plan. The following are required body parameters. Please see the comments for requirements:

{
post: "YouTube Description", // required: Video description
platforms: ["youtube"], // required
mediaUrls: ["https://images.ayrshare.com/imgs/test-video-1.mp4"], // required: URL of video, 1 allowed
youTubeOptions: {
title: "YouTube Title", // required: Video Title
youTubeVisibility: "private", // optional: "public", "unlisted", or "private" - default "private"
thumbNail: "https://images.ayrshare.com/imgs/GhostBusters.jpg", // optional: URL of a JPEG or PNG
playListId: "PLrav6EfwgDX5peD7Ni-pOKa7B13WjLyUB" // optional: Playlist ID to add the video
}
}

Thumbnail Requirements

Thumbnails and other features, such as uploading 15 minute videos, require verification of your phone number.

In "YouTube Studio" go to "Setting" -> "Channel". Select "Feature Eligibility" and click "Features that require phone verification". Enter your phone number to enable.

YouTube Verify Phone

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

{
post: "Reddit post", // required
platforms: ["reddit"], // required
redditOptions: {
title: "Reddit Post Title", // required
subreddit: "test", // required (no "/r/" needed)
reddit_link: "https://www.website.com", // optional: post a link
}
}
  • subreddit: The subreddit to send the post. Please be sure to follow the subreddit's posting guidelines. A good subreddit to use for testing is /r/test/

  • reddit_link: If posting to Reddit and you want to post a link instead of text to the subreddit.

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.

Image and Video Requirements

Posting images and videos have different requirements for each network. See below for details, but don't worry. Our system verifies your post before sending, so you'll get an error response if something is wrong.

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.

Ads (early access)

Early Access Only. Please contact us if you're interested in ads.

Take your or your users' posts to the next level my promoting them as ads. We currently only support Twitter Promoted Tweets, but additional networks are coming soon.

{
"post": "Today is a great day!",
"platforms": [
"twitter"
],
"ads": {
"twitter": {
"campaign": "19ce55aplcy",
"group": "it9bm"
}
}
}

Promoting a post as an add requires two parameters: campaign and group ids. When the post successfully is sent, it will be promoted as an ad in the given campaign and group.

If the campaign and group ids were preset with the PUT /ads/twitter/ids endpoint, use the createAd parameter to automatically promote the post.

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

Please see the ads docs for more details:

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

post
bulk

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.
Request
Response
Request
Headers
Authorization
optional
string
Format: Authorization: Bearer API_KEY See Overview for more information.
Content-Type
required
string
multipart/form-data
Form Data Parameters
file
required
object
Multipart form-data CSV file of scheduled posts. See below for template.
Response
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"
}
]
}

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 '[email protected]"./Ayrshare CSV Template.csv"' \
-X POST https://app.ayrshare.com/api/post/bulk

The CSV file contains the following fields (template below):

  • 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. Formate MM/DD/YYYY h:m. E.g. 5/23/2021 14:34. Times are in UTC−08:00.

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.