Ayrshare API

Proxy endpoints for Ayrshare social media scheduling and analytics.

Overview

Configuration

Set your Ayrshare API key:

AYRSHARE_API_KEY=your_api_key_here

Endpoints

Schedule Post

Schedule a social media post across platforms.

POST /ayrshare/schedule

Request Body:

{
  "post": "Check out our latest episode! 🎙️",
  "platforms": ["twitter", "facebook", "linkedin"],
  "scheduleDate": "2026-02-10T15:00:00.000Z",
  "mediaUrls": ["https://example.com/image.jpg"],
  "hashtags": ["podcast", "newepisode"],
  "shortenLinks": true
}

Parameters:

Field	Type	Required	Description
post	string	✅	Post content
platforms	array	✅	Target platforms
scheduleDate	string	No	ISO date (immediate if omitted)
mediaUrls	array	No	Media URLs to attach
hashtags	array	No	Hashtags to append
shortenLinks	boolean	No	Shorten URLs

Response:

{
  "success": true,
  "id": "ayr_123456",
  "posts": [
    {
      "platform": "twitter",
      "status": "scheduled",
      "postId": null
    },
    {
      "platform": "facebook",
      "status": "scheduled",
      "postId": null
    }
  ]
}

---

Delete Post

Cancel a scheduled post or delete a published post.

POST /ayrshare/delete

Request Body:

{
  "id": "ayr_123456"
}

Response:

{
  "success": true,
  "message": "Post deleted successfully"
}

---

Get Post History

Retrieve history of scheduled and published posts.

GET /ayrshare/history

Query Parameters:

Parameter	Type	Description
limit	number	Max posts to return (default: 50)
status	string	Filter: scheduled, published, error
platform	string	Filter by platform

Example Request:

curl "http://localhost:3100/ayrshare/history?limit=10&status=published"

Response:

{
  "success": true,
  "data": [
    {
      "id": "ayr_123456",
      "post": "Check out our latest episode!",
      "platforms": ["twitter"],
      "status": "published",
      "publishedAt": "2026-02-05T15:00:00.000Z",
      "analytics": {
        "likes": 45,
        "comments": 12,
        "shares": 8
      }
    }
  ]
}

---

Get Analytics

Get analytics for posts or platforms.

GET /ayrshare/analytics

Query Parameters:

Parameter	Type	Description
platform	string	Platform to get analytics for
postId	string	Specific post ID
startDate	string	Start date
endDate	string	End date

Example Request:

curl "http://localhost:3100/ayrshare/analytics?platform=twitter"

Response:

{
  "success": true,
  "platform": "twitter",
  "analytics": {
    "followers": 45230,
    "following": 1250,
    "impressions": 156420,
    "engagement": 8920,
    "engagementRate": 5.7
  }
}

---

Sync Posts

Sync post status from Ayrshare to EspoCRM.

POST /ayrshare/sync

Description: Fetches all posts from Ayrshare and updates corresponding SocialPost records in EspoCRM.

Response:

{
  "success": true,
  "synced": 15,
  "updated": 3,
  "errors": 0
}

---

Platform Identifiers

Platform	Ayrshare ID	Notes
X/Twitter	twitter
Facebook	facebook	Page posting
Instagram	instagram	Business account
LinkedIn	linkedin	Personal or company
YouTube	youtube	Community posts
TikTok	tiktok	Video required
Pinterest	pinterest	Image required

Implementation Details

Schedule Helper

// helpers/ayrshare/schedule.js
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://app.ayrshare.com/api',
  headers: {
    'Authorization': `Bearer ${process.env.AYRSHARE_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

export async function schedulePost(data) {
  const response = await client.post('/post', {
    post: data.post,
    platforms: data.platforms,
    scheduleDate: data.scheduleDate,
    mediaUrls: data.mediaUrls || [],
    shortenLinks: data.shortenLinks ?? true,
  });
  
  return response.data;
}

export async function deletePost(id) {
  const response = await client.delete(`/post/${id}`);
  return response.data;
}

Route Implementation

// routes/ayrshare.js
import { Router } from 'express';
import { schedulePost, deletePost, getHistory, getAnalytics } from '../helpers/ayrshare/index.js';

const router = Router();

router.post('/schedule', async (req, res) => {
  try {
    const result = await schedulePost(req.body);
    res.json({ success: true, ...result });
  } catch (error) {
    res.status(500).json({ 
      success: false, 
      error: error.response?.data?.message || error.message 
    });
  }
});

router.post('/delete', async (req, res) => {
  try {
    await deletePost(req.body.id);
    res.json({ success: true, message: 'Post deleted' });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

router.get('/history', async (req, res) => {
  try {
    const data = await getHistory(req.query);
    res.json({ success: true, data });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

router.get('/analytics', async (req, res) => {
  try {
    const data = await getAnalytics(req.query);
    res.json({ success: true, ...data });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

export default router;

Webhook Integration

When a SocialPost is created in EspoCRM with status "Scheduled":

Error Handling

Ayrshare errors are passed through:

{
  "success": false,
  "error": "Invalid API key",
  "code": "AUTH_ERROR"
}

Common Errors:

Error	Cause	Solution
AUTH_ERROR	Invalid API key	Check AYRSHARE_API_KEY
RATE_LIMIT	Too many requests	Wait and retry
INVALID_MEDIA	Media URL inaccessible	Check media URL
PLATFORM_ERROR	Platform-specific issue	Check platform connection

Rate Limits

Ayrshare has rate limits per plan. The Bridge respects these:

• Free: 10 posts/day
• Premium: 100 posts/day
• Business: 500 posts/day

Related

• SocialPost Entity
• Social Workflow
• Analytics API