> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish a Post

> Publish a post to social media platforms

export const XByoNotice = () => <Info>
  <strong>Targeting X/Twitter?</strong> Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
  <br /><br />
  <code>X-Twitter-OAuth1-Api-Key</code> — Your API Key (Consumer Key)<br />
  <code>X-Twitter-OAuth1-Api-Secret</code> — Your API Key Secret (Consumer Secret)
  <br /><br />
  Not linked yet? See the <a href="/dashboard/connect-social-accounts/x-twitter-byo-keys">full setup guide</a> to connect your X account.
  <br /><br />
  Your keys are never logged or stored by Ayrshare.
</Info>;

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

<XByoNotice />

Publish posts to the social networks you or your users have linked.
If you want to publish posts to User Profiles, please see the [/profiles endpoint](/apis/profiles/overview) for more details.

Please be sure to add your `API_KEY`, and the `PROFILE_KEY` if publishing to a User Profile, in the [Authorization header](/apis/overview#authorization).
The API Key can be found in the Ayrshare Developer Dashboard under the API Key page.

See the [Post API Overview](/apis/post/overview) for more details on posting options.

## Header Parameters

<HeaderAPI />

## Body Parameters

<ParamField body="post" type="string" required>
  The post text sent to the social networks specified in the platforms parameter.
  See here for [advanced options](/apis/post/overview), including how to include URLs and rich text.

  You may send an empty string `""`to publish with no text.
</ParamField>

<ParamField body="platforms" type="array" required>
  Social media platforms to post. Accepts an array of Strings with values: `bluesky`, `facebook`, `gmb`, `instagram`, `linkedin`, `pinterest`, `reddit`, `snapchat`, `telegram`, `threads`, `tiktok`, `twitter`, or `youtube`.

  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 all social network.
  E.g. `title` must be included in `youTubeOptions` if `youtube` is linked.
</ParamField>

<ParamField body="mediaUrls" type="array">
  An array of image or video URLs to include in the post. Please see [/media endpoint](/apis/media/overview) to learn more.

  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 paid plan.

  Please see here for [Image and Video Requirements](/apis/post/overview#image-%26-video-requirements) and [other advanced options](/apis/post/overview).
</ParamField>

<ParamField body="isVideo" type="boolean" default={false}>
  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 [video extension](/apis/post/overview#video-extension) for details.
</ParamField>

<ParamField body="scheduleDate" type="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 `2026-07-08T12:30:00Z`.
  Please see [utctime](https://www.utctime.net/) for more examples.

  Also see [schedule posts](/apis/post/overview#schedule-posts) for details.
</ParamField>

<ParamField body="validateScheduled" type="boolean" default={true}>
  By default, scheduled posts are checked (pre-validated) for issues such as media requirements before they are accepted.
  If any problems are found by Ayrshare checks, you will receive an immediate error response and the post will not be scheduled.
  When the scheduled date is reached, the post will be published, at which time the final success or error response will be sent either via webhook or the [/history endpoint](/apis/history/overview).

  To skip this pre-validation step, set `validateScheduled` to `false`.

  We recommend keeping validation enabled for scheduled posts to catch errors early.
  Otherwise, the post will be scheduled and you will only receive an error when it is published.

  Please see [scheduled webhook actions](/apis/webhooks/actions#scheduled-action) for more details.
</ParamField>

<ParamField body="firstComment" type="object">
  Add in a first comment automatically after posting. See [first comment](/apis/post/overview#first-comment) for details.
</ParamField>

<ParamField body="disableComments" type="boolean" default={false}>
  Disable comments for the post. Only available for Instagram, LinkedIn, and TikTok.
</ParamField>

<ParamField body="shortenLinks" type="boolean" default={false}>
  Shorten links in the post for all platforms using [Ayrshare's link shortener](/apis/links/overview).

  Only URLs starting with https will be shortened.

  [Max Pack required](/additional/maxpack) for link shortening.

  Please see here for using [3rd party link shorteners](/apis/links/overview#custom-link-domain).
</ParamField>

<ParamField body="autoSchedule" type="object">
  Please see [auto-schedule](/apis/auto-schedule/overview) for details.
</ParamField>

<ParamField body="autoRepost" type="object">
  Automatically reposts your content multiple times at regular intervals, creating evergreen content that stays fresh and visible to your audience.

  See [auto repost](/apis/post/overview#auto-repost) for details.
</ParamField>

<ParamField body="autoHashtag" type="object">
  See [auto hashtags](/apis/post/overview#auto-hashtags) for details.
</ParamField>

<ParamField body="unsplash" type="string">
  See [unsplash](/apis/post/overview#unsplash) for details.
</ParamField>

<ParamField body="blueskyOptions" type="object">
  See [Bluesky details](/apis/post/social-networks/bluesky).
</ParamField>

<ParamField body="faceBookOptions" type="object">
  See [Facebook details](/apis/post/social-networks/facebook).
</ParamField>

<ParamField body="gmbOptions" type="object">
  See [Google Business Profile details](/apis/post/social-networks/google).
</ParamField>

<ParamField body="instagramOptions" type="object">
  See [Instagram details](/apis/post/social-networks/instagram).
</ParamField>

<ParamField body="linkedInOptions" type="object">
  See [LinkedIn details](/apis/post/social-networks/linkedin).
</ParamField>

<ParamField body="pinterestOptions" type="object">
  See [Pinterest details](/apis/post/social-networks/pinterest).
</ParamField>

<ParamField body="redditOptions" type="object">
  See [Reddit details](/apis/post/social-networks/reddit).
</ParamField>

<ParamField body="snapChatOptions" type="object">
  See [Snapchat details](/apis/post/social-networks/snapchat).
</ParamField>

<ParamField body="telegramOptions" type="object">
  See [Telegram details](/apis/post/social-networks/telegram).
</ParamField>

<ParamField body="threadsOptions" type="object">
  See [Threads details](/apis/post/social-networks/threads).
</ParamField>

<ParamField body="tikTokOptions" type="object">
  See [TikTok details](/apis/post/social-networks/tiktok).
</ParamField>

<ParamField body="twitterOptions" type="object">
  See [X/Twitter details](/apis/post/social-networks/x-twitter).
</ParamField>

<ParamField body="youTubeOptions" type="object">
  See [YouTube details](/apis/post/social-networks/youtube).
</ParamField>

<ParamField body="requiresApproval" type="boolean" default={false}>
  See [approval workflow](/apis/post/overview#approval-workflow) for details.
</ParamField>

<ParamField body="randomPost" type="boolean" default={false}>
  [Generate random post text](/quickstart#random-quote) for testing. `randomPost: true` will ignore the `post` field.
</ParamField>

<ParamField body="randomMediaUrl" type="boolean" default={false}>
  [Generate a random media image](/quickstart#random-image) for testing. `randomMediaUrl: true` will ignore the `mediaUrls` field.
</ParamField>

<ParamField body="idempotencyKey" type="string">
  An optional unique ID associated with the post. Duplicate IDs will be rejected. Please see [idempotency](/apis/post/overview#idempotent-posts) for details.
</ParamField>

<ParamField body="notes" type="string">
  Set notes on a post that can be retrieved via the [/history endpoint](/apis/history/overview). Notes are for reference only and do not affect the post.
</ParamField>

<RequestExample>
  ```bash cURL theme={"system"}
  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://api.ayrshare.com/api/post
  ```

  ```javascript JavaScript theme={"system"}
  const API_KEY = "API_KEY";

  fetch("https://api.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: ["bluesky", "facebook", "instagram", "linkedin", "twitter"], // required
          mediaUrls: ["https://img.ayrshare.com/012/gb.jpg"] //optional
        }),
      })
        .then((res) => res.json())
        .then((json) => console.log(json))
        .catch(console.error);
  ```

  ```python Python theme={"system"}
  import requests

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

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

  print(r.json())
  ```

  ```php PHP theme={"system"}
  <?php

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

  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://api.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 Go theme={"system"}
  package main

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

  func main() {
  	message := map[string]interface{}{
  		"post":      "Today is a great day!",
  		"platforms": []string{"bluesky", "facebook", "instagram", "linkedin", "twitter"},
  		"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://api.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()
  }
  ```

  ```csharp C# theme={"system"}
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  namespace PostPOSTRequest_csharp
  {
    class Post
    {
      private static readonly HttpClient client = new HttpClient();

          static async Task Main(string[] args)
          {
              string API_KEY = "API_KEY";
              string url = "https://api.ayrshare.com/api/post";

              // Set up request headers
              client.DefaultRequestHeaders.Add("Authorization", "Bearer " + API_KEY);

              // Prepare JSON content
              string json = "{\"post\" : \"Today is a great day!\","
                  + "\"platforms\" : [ \"bluesky\", \"facebook\", \"instagram\", \"linkedin\", \"twitter\" ],"
                  + "\"mediaUrls\" : [ \"https://img.ayrshare.com/012/gb.jpg\" ]}";
              var content = new StringContent(json, Encoding.UTF8, "application/json");

              try
              {
                  // Send POST request
                  HttpResponseMessage response = await client.PostAsync(url, content);
                  response.EnsureSuccessStatusCode();

                  // Read response
                  string responseBody = await response.Content.ReadAsStringAsync();
                  Console.WriteLine(responseBody);
              }
              catch (HttpRequestException e)
              {
                  Console.WriteLine($"Error: {e.Message}");
              }
          }
      }
  }
  ```

  ```ruby Ruby theme={"system"}
  require 'httparty'    # gem install httparty

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

  puts res
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
      "status": "success",
      "errors": [],
      "postIds": [
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/bluesky
              "status": "success",
              "id": "at://did:plc:n7atrjd22xgkmgwig6dzlhzd/app.bsky.feed.post/3lez7fwx452", // Bluesky Social Post ID
              "cid": "bafyreie6n475cd3ynr6sfacvohu5qgjibcooxnug6zcbghkwnrwi5stafy",         // Bluesky Content ID
              "postUrl": "https://bsky.app/profile/madworlds.bsky.social/post/3lez7fwx4572",
              "platform": "bluesky"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/facebook
              "status": "success",
              "id": "104923907983682_108329000309742", // Facebook Social Post ID
              "platform": "facebook", 
              "postUrl": "https://www.facebook.com/104923907983682_108329000309742",
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/google
              "status": "success",
              "id": "3837985438581442258", // Google Business Profile Social Post ID
              "postUrl": "https://local.google.com/place?id=5229466225881728772&use=posts&lpsid=CM",
              "type": "localPosts",
              "platform": "gmb"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/instagram
              "status": "success",
              "platform": "instagram", // Instagram Social Post ID
              "id": "17878176260289172",
              "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
              "usedQuota": 12,
              "contentIssues": {  // Optional — only present when Ayrshare detected and resolved a content issue
                  "originMediaHostFailed": true,
                  "details": ["Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."]
              }
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/linkedin
              "status": "success",
              "id": "urn:li:share:7282181682126807041", // LinkedIn Social Post ID
              "postUrl": "https://www.linkedin.com/feed/update/urn:li:share:7282181682126807041",
              "owner": "urn:li:organization:77682157",
              "platform": "linkedin"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/pinterest
              "status": "success",
              "id": "42995371460659062", // Pinterest Social Post ID
              "postUrl": "https://www.pinterest.com/pin/429953714606062/",
              "platform": "pinterest"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/reddit
              "status": "success",
              "id": "1hvdvof", // Reddit Social Post ID
              "postUrl": "https://www.reddit.com/r/test/comments/1hvdvof/reddit_post_title/",
              "platform": "reddit"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/snapchat
              "status": "success",
              "id": "921ed204-e123-5b08-a9ce-zx489f1f38c5",                             // Snapchat Social Post ID 
              "mediaId": "V6noC6UOQgOcABCDEgFZEwAAgd3F0cnp1eWtxZAb9PsH-MXb9PsIWAAAAAA", // Snapchat Media ID
              "postUrl": "https://www.snapchat.com/add/samsmith1920/921ed204-e123-5b08-a9ce-zx489f1f38c5",
              "type": "stories",
              "ended": "2025-05-23T13:04:30.545Z",
              "platform": "snapchat"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/telegram
              "status": "success",
              "id": 635, // Telegram Social Post ID
              "postUrl": "https://t.me/c/1424847122/635",
              "platform": "telegram"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/tiktok
              "status": "success",
              "idShare": "v_pub_url~v2.7456954878846683182",
              "id": "pending", // TikTok Social Post ID - see https://www.ayrshare.com/docs/apis/post/social-networks/tiktok
              "isVideo": true,
              "platform": "tiktok"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/twitter
              "status": "success",
              "id": "1288899996423983105", // X/Twitter Social Post ID
              "platform": "twitter",
              "postUrl": "https://x.com/handle/status/1288899996423983105"
          },
          {
              // Details at https://www.ayrshare.com/docs/apis/post/social-networks/youtube
              "status": "success",
              "id": "3oQeP-kTsbo", // YouTube Social Post ID
              "postUrl": "https://youtu.be/3oQeP-kTo",
              "platform": "youtube"
          }
      ],
      "id": "RhrbDtYh7hdSMc67zC8H"    // Ayrshare Post ID used for delete, analytics, comments, etc.
  }
  ```

  ```json 200: Success for Scheduled theme={"system"}
  {
    "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"
  }
  ```

  ```json 200: Success with Profile Key theme={"system"}
  {
    "status": "success",
    "posts": [
      {
        "status": "success",
        "errors": [],
        "postIds": [
          {
            "status": "success",
            "id": "1869166036466991888",
            "postUrl": "https://twitter.com/wondrouswaffles/status/1869",
            "platform": "twitter"
          },
          {
            "status": "success",
            "id": "106638148652344_601623445855888",
            "postUrl": "https://www.facebook.com/106638148652329/posts/6016",
            "platform": "facebook"
          }
        ],
        "id": "bVQotNtxgXAUmLtqmw2",
        "refId": "b68bdcabb379be2cf1186c1e595449804b232sa",
        "profileTitle": "The Best Profile",
        "post": "Formal education will make you a living. Self education will make you a fortune. - Jim Rohn"
      }
    ]
  }
  ```

  ```json 200: Success Scheduled Post and Profile Key theme={"system"}
  {
    "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"
      }
    ]
  }
  ```

  ```json 400: Bad Request theme={"system"}
  {
    "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. .../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.
  }
  ```

  ```json 400: Bad Request with Profile Key theme={"system"}
  {
      "status": "error",
      "posts": [
          {
              "status": "error",
              "errors": [
                  {
                      "action": "post",
                      "status": "error",
                      "code": 156,
                      "message": "Instagram is not linked.
                        Please confirm the linkage on the Social Accounts page in the dashboard. https://www.ayrshare.com/docs/help-center/overview",
                      "platform": "instagram"
                  }
              ],
              "postIds": [],
              "id": "ekftQJ0hFB1Fx6bnM33",
              "refId": "9abf1426d6ce9122effdeeddfdfdfd",
              "profileTitle": "Best Profile",
              "post": "The most common way people give up their power is by thinking they don't have any. - Alice Walker"
          }
      ]
  }
  ```

  ```javascript 500: Internal Server Error theme={"system"}
  {
      "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.
  }
  ```
</ResponseExample>