Have ideas to improve npm?Join in the discussion! »


    1.0.16 • Public • Published

    Automated Social Media Posting APIs

    Social Post API is a client for Ayrshare's APIs. Ayrshare is a powerful set of APIs that enable you to automate server-side social media posts to Twitter, Instagram, Facebook, LinkedIn, YouTube, Reddit, and Telegram for your company or on behalf of your users.

    The Ayrshare API handles all the setup and maintenance for the social media networks. One API to rule them all (yeah, went there). See the full list of features.

    If you have a platform or manage multiple clients contact us about the business plan.

    Also, check out our video of installing and using the package.


    npm i social-post-api


    1. Create a free Ayrshare account.

    alt Social Accounts Setup

    2. Enable your social media accounts such as Twitter, Facebook, LinkedIn, Reddit, Instagram, or Telegram in the Ayrshare dashboard.

    alt Social Accounts Setup

    3. Copy your API Key from the Ayrshare dashboard. Used for authentication.

    alt API Key

    Getting Started

    Initialize Social Post API

    Create a new Social Post object with your API Key.

    const SocialPost = require("social-post-api");
    const social = new SocialPost('Your API Key');

    History, Post, Delete Example

    This simple example shows how to post an image or video, get history, and delete the post. This example assumes you have a free API key from Ayrshare and have enabled Twitter, Facebook, and LinkedIn. Note, Instagram, Telegram and Reddit also available.

    const SocialPost = require("social-post-api");
    const API_KEY = "Your API Key"; // get an API Key at ayrshare.com
    const social = new SocialPost(API_KEY);
    const run = async () => {
      /** post */
      const post = await social.post({
        post: "One more time",
        platforms: ["twitter", "facebook", "linkedin"],
      /** history */
      const history = await social.history()
      /** delete */
      const deletePost = await social.delete({ id: post.id })



    Published a new post to the specified social networks either immediately or at scheduled future date. Returns a promise that resolves to an object containing the post ID and post status (success, error). See the post endpoint for the full capabilities.

    const postResponse = await social.post({
        // Required
        post: "Best post ever!",
    	// Required: Social media platforms to post. 
    	// Accepts an array of strings with values: "facebook", "twitter", "instagram", "linkedin", "reddit", or "telegram".
        platforms: ["twitter", "facebook", "instagram", "linkedin", "telegram", "reddit"],
    	// Optional: URLs of images or videos to include in the post
    	media_urls: ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
    	// Optional: Datetime to schedule a future post. 
    	// Accepts an ISO-8601 UTC date time in format "YYYY-MM-DDThh:mm:ssZ". Example: 2021-07-08T12:30:00Z
    	scheduleDate: "2020-08-07T15:17:00Z",
    	// Required if platform includes "reddit." Title of Reddit post.
    	title: "My Reddit Post",
    	// Required if platform includes "reddit." Subreddit to post.
    	subreddit: "test",
    	// Optional: 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.
    	shorten_links: true


    Delete a post with a given post ID, obtained from the "post" response. Returns a promise with the delete status. Also, can bulk delete multiple IDs at once using the "bulk" key. See the delete endpoint for more details.

    const deleteResponse = await social.delete({
        // Required
        id: "POST ID",                          // optional, but required if "bulk" not present
        bulk: ["Post ID 1", "Post ID 2", ...]   // optional, but required if "id" not present


    Get a history of all posts and their current status in descending order. Returns a promise that resolves to an array of post objects. See the history endpoint for more details.

    const historyResponse = await social.history({
      lastRecords: 10,    // optional: returns the last X number of history records
      lastDays: 30,       // optional: returns the last X number of days of history records. Defaults to 30 if not present.

    Upload Media

    Upload and store a new image. Returns a URL referencing the image. Can be used in "image_url" in "post". See the media endpoint for more details.

    const uploadResponse = await social.upload({
    	// Required: The image as a Base64 encoded string. Example encoding: https://www.base64-image.de/
    	// Optional
    	fileName: "test.png",
    	// Optional
        description: "best image"

    Get Media

    Get all media URLS. Returns a promise that resolves to an array of URL objects. See the media endpoint for more details.

    const mediaResponse = await social.media().catch(console.error);


    Get data about the logged in user, such as post quota, used quota, active social networks, and created date. See the user endpoint for more details.

    const user = await social.user().catch(console.error);

    Shorten URL

    Shorten a URL and return the shortened URL. See the shorten endpoint for more details.

    const shortenResponse = await social.shorten({
        // Required: URL to shorten
        url: "https://theURLtoShorten.com/whatmore",


    Get analytics on shortened links and shares, likes, and impressions. See the analytics endpoint for more details.

    const analyticsLinks = await social.analyticsLinks({
      // Optional range 1-7, default 1 day.
      lastDays: 3
    const analyticsPost = await social.analyticsPost({
      id: "Post ID",
      platforms: ["twitter", "linkedin"]

    Set Auto Schedule

    Set up an auto-post schedule by providing times to send. Post will automatically be sent at the next available time. If no more times are available today, the first available time tomorrow will be used, and so forth. See the set-auto-schedule endpoint for more details.

    const setAutoSchedule = await social.setAutoSchedule({
      schedule: ["13:05Z", "20:14Z"],   // required
      title: "Instagram Schedule"       // optional 

    Add an RSS or Substack Feed

    Add a new RSS or Substack feed to auto post all new articles. Returns a promise that resolved to an object containing the feed ID. See How to Automate Your Blog or Newsletter for more info.

    const feedResponse = await social.feedAdd({
    	// Required: URL to shorten
    	url: "https://theRSSFeed",
    	// Optional: Value: "rss" or "substack". 
    	// If not set, defaults to "rss"
        type: "RSS",

    Delete an RSS or Substack Feed

    Delete an RSS feed for a given ID.

    const feedResponse = await social.feedDelete({
    	// Required: ID of the feed
    	id: "Feed ID",

    Business Member Functions for Multiple Clients - Business Plan Required

    The Business Plan allows you to create, manage, and post on behalf of client profiles via the API or Dashboard GUI. You can integrate Ayrshare into your platform, product, or agency and give your clients social media capabilites. Please contact us with any questions.

    Create Profile

    Create a new account profile under the primary account. See the create profile endpoint for more details.

    const createProfileResponse = await social.createProfile({
        // Required: title
        title: "New Profile Title",

    Delete Profile

    Delete a profile owned by the primary account. See the delete profile endpoint for more details.

    const deleteProfileResponse = await social.deleteProfile({
        // Required: profileKey - the API Key of the profile to delete
        profileKey: "JI9s-kJII-9283-OMKM",

    Other Packages & Integrations

    We have other package and integrations such as Python, Bubble.io, and Airtable + exmaples in PHP and Go.

    Additional Information and Support

    Additional examples, responses, etc. can be found at:

    RESTful API Endpoint Docs

    Please contact us with your questions, or just to give us shout-out 📢!


    npm i social-post-api

    DownloadsWeekly Downloads






    Unpacked Size

    17.8 kB

    Total Files


    Last publish


    • avatar