> ## 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.

# Ayrshare API Overview

> Powerful Social APIs that enable you to send social media posts and get analytics effortlessly. For developers and businesses of all sizes.

The Social Media REST API provides developers with programmatic access to multiple social networks through a single unified interface.
Through Ayrshare's social API, you can manage social media activities including creating and deleting posts, retrieving analytics, engaging with comments and reviews, managing direct messages, creating Facebook ads, and performing other social media actions across platforms.

The API currently supports 13 major social networks: Bluesky, Facebook, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Telegram, Threads, TikTok, X (formerly Twitter), and YouTube.
By integrating with this API, developers can automate social media management tasks across all these platforms simultaneously.

API calls request and response data are in JSON format, which allow for easy parsing and processing in most programming languages.

If you are on the Business or Enterprise Plan, see the [Business Plan Overview](/multiple-users/business-plan-overview) and [/profiles API endpoint](/apis/profiles/overview).

## Key Functionality

<ul class="custom-bullets">
  <li>[13 social networks supported](/introduction#which-social-networks-are-supported).</li>
  <li>Secure API access using your unique API Key.</li>
  <li>Scheduled posting to connected social media platforms.</li>
  <li>Automated posting based on predefined schedules.</li>
  <li>Support for image and video content, including Reels, Stories, and Spotlight.</li>
  <li>Delete posts on linked social networks.</li>
  <li>Comprehensive post engagement analytics (likes, shares, etc.).</li>
  <li>Social account metrics, including follower count and demographic data.</li>
  <li>Comment management: view, add, and delete post comments.</li>
  <li>Optional link shortening for all or specific URLs in posts.</li>
  <li>Unsplash integration: add specific images or randomly select based on keywords.</li>
  <li>Automatic hashtag generation option using relevant keywords.</li>
  <li>Post history tracking, including non-Ayrshare posts.</li>
  <li>Review management: retrieve, reply to, and delete review responses.</li>
  <li>RSS feed integration for automated content posting.</li>
  <li>Media library: upload and store photos and videos for use in posts.</li>
  <li>[Social Post Verification System](/testing/post-verification) to keep your social accounts safe.</li>
</ul>

## Business Plan

[Business Plan features](/multiple-users/business-plan-overview) for managing multiple users and clients:

<ul class="custom-bullets">
  <li>Enable users to link their own social media accounts to your platform.</li>
  <li>Secure single sign-on using OAuth for quick account linking.</li>
  <li>Create and remove user profiles programmatically through the API.</li>
  <li>Access advanced user analytics.</li>
  <li>Webhook support for real-time updates.</li>
  <li>Direct message management across supported platforms.</li>
  <li>Create Facebook ads from existing posts.</li>
</ul>

Contact us to learn more about the [Business Plan](https://www.ayrshare.com/business-plan-for-multiple-users/).

## Ads API

The [Ads API](/apis/ads/overview) allows you to create Facebook ads from existing posts.

<ul class="custom-bullets">
  <li>Boost posts to reach more people.</li>
  <li>Manage ads and track performance.</li>
  <li>Analyze ad spend and optimize campaigns.</li>
</ul>

<Card title="Ads API" icon="code" href="/apis/ads/overview" horizontal>
  Explore the Ads API
</Card>

## Messages API

A unified [Messaging API](/apis/messages/overview) to engage users in conversations across the major social media channels: Facebook, Instagram, and X.

<ul class="custom-bullets">
  <li>Sending text, image, and video messages.</li>
  <li>Retrieving complete conversation histories.</li>
  <li>Setting up automated message responses.</li>

  <li>
    Receiving real-time updates via webhooks for messages received, message reactions, read
    receipts.
  </li>
</ul>

This API simplifies user engagement by centralizing messaging operations for multiple social media channels. Learn more...

<Card title="Messages API" icon="code" href="/apis/messages/overview" horizontal>
  Explore the unified messaging API
</Card>

## Max Pack

Get even more capabilities with the [Max Pack add-on](/additional/maxpack):

<Card title="Max Pack" icon="link" href="/additional/maxpack" horizontal>
  Unlock advanced features like AI-powered content generation, enhanced analytics, and expanded
  platform support with our Max Pack add-on.
</Card>

## Watch How to Use the Social API

If you're building in Node.js, check out this video on how to connect and publish posts to X and Facebook.

<div class="video-container">
  <iframe width="560" height="315" src="https://www.youtube.com/embed/OMtj2h6sW6U" title="How to Use Ayrshare's Social API" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />
</div>

## Social API Demo

If you use Node.js see the social API demo code to get started building your own social API integration.

<Card title="Social API Demo" icon="github" href="https://github.com/ayrshare/social-api-demo" horizontal>
  Explore our Node.js demo code to jumpstart your social API integration
</Card>

## Base URL

The base URL for the Ayrshare API is the same for all endpoints.

`https://api.ayrshare.com/api`

## Authorization

Ayrshare authenticates API requests via an Authorization token passed in the HTTP header. Please be sure to send `Bearer` with the API Key. The API Key can be found in the Ayrshare Dashboard by switching to your Primary Profile.

If you are a Business or Enterprise user, you can create User Profiles with Profile Keys to manage multiple clients. The Profile Key is used in the header of your requests.
The API Key must also be used in the header of your requests for User Profiles.

<Tip>
  Premium plans should only use the API Key in the header of their requests. Business and Enterprise
  plans should use the Profile Key in the header of their requests when interacting on behalf of a
  User Profile.
</Tip>

### API Key Format

`Authorization: Bearer API_KEY` replacing API\_KEY with your Primary Profile API Key, which can be [found in the Ayrshare Dashboard](/quickstart#get-your-api-key).

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -H "Authorization: Bearer API_KEY" \
       -X GET https://api.ayrshare.com/api
  ```

  ```javascript JavaScript theme={"system"}
  headers: {"Authorization": "Bearer API_KEY"}
  ```

  ```python Python theme={"system"}
  headers = {"Authorization": "Bearer API_KEY"}
  ```

  ```php PHP theme={"system"}
  $headers = ["Authorization" => "Bearer API_KEY"];
  ```

  ```go Go theme={"system"}
  headers := map[string]string{"Authorization": "Bearer API_KEY"}
  ```

  ```ruby Ruby theme={"system"}
  headers = {"Authorization": "Bearer API_KEY"}
  ```

  ```java Java theme={"system"}
  headers = {"Authorization": "Bearer API_KEY"}
  ```

  ```csharp C# theme={"system"}
  headers = {"Authorization": "Bearer API_KEY"}
  ```

  ```rust Rust theme={"system"}
  headers = {"Authorization": "Bearer API_KEY"}
  ```
</CodeGroup>

<Note>
  Obtain your secret API Key in the Ayrshare dashboard under the API Key page found in the left navigation panel.

  For example, if your API Key is 2MPXPKQ-S03M5LS-GR5RX5G-AZCK8EA

  Your header should include:

  `Authorization: Bearer 2MPXPKQ-S03M5LS-GR5RX5G-AZCK8EA`
</Note>

### Profile Key Format

A Profile Key is used to interact on behalf of a User Profile.
This is only available for Business or Enterprise plans.

`Profile-Key: PROFILE_KEY` replacing PROFILE\_KEY with a user's [Profile Key](/multiple-users/manage-user-profiles#get-the-profile-key).

**Including a Profile Key in the header is required to interact on behalf of a User Profile**.

A missing Primary Profile API Key or using the Profile Key in place of the API Key in the header will result in an error.

Here's how to structure the headers for API requests:

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -H "Authorization: Bearer API_KEY" \ 
       -H "Profile-Key: PROFILE_KEY" \
       -X GET https://api.ayrshare.com/api
  ```

  ```javascript JavaScript theme={"system"}
  headers: {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY"
  }
  ```

  ```python Python theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY"
  }
  ```

  ```php PHP theme={"system"}
  $headers = [
    "Authorization" => "Bearer API_KEY",
    "Profile-Key" => "PROFILE_KEY"
  ];
  ```

  ```go Go theme={"system"}
  headers := map[string]string{
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY"
  }
  ```

  ```ruby Ruby theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY"
  }
  ```

  ```java Java theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY"
  }
  ```

  ```csharp C# theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY"
  }
  ```

  ```rust Rust theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY"
  }
  ```
</CodeGroup>

<Note>
  [Find the Profile Key](/multiple-users/manage-user-profiles#get-the-profile-key) in the Ayrshare Dashboard under the Profile Key page found in the left navigation panel.
  Switch to the Profile you want to use in the User Profile page.
  Additionally, the Profile Key is returned in the response of the [Create a User Profile](/apis/profiles/create-profile) endpoint.

  You can then use the Profile Key in the header of your requests:

  For example, if your Profile Key is `AX1XGG-9jK3M5LS-GR5RX5G-LLCK8EA`

  Your header should include both the API and Profile Key:

  `Authorization: Bearer 2MPXPKQ-S03M5LS-GR5RX5G-AZCK8EA`

  `Profile-Key: AX1XGG-9jK3M5LS-GR5RX5G-LLCK8EA`
</Note>

### X/Twitter BYO Credentials

Starting March 31, 2026, all X/Twitter operations through Ayrshare require your own OAuth 1.0a credentials. After linking your X account via OAuth, pass these 2 headers alongside your `Authorization` (and optional `Profile-Key`) headers for any request that targets X/Twitter:

| Header                        | Description                                      |
| ----------------------------- | ------------------------------------------------ |
| `X-Twitter-OAuth1-Api-Key`    | Your OAuth 1.0a API Key (Consumer Key)           |
| `X-Twitter-OAuth1-Api-Secret` | Your OAuth 1.0a API Key Secret (Consumer Secret) |

These headers are required after March 31, 2026. Requests to X/Twitter endpoints without valid BYO credentials will be rejected.

See the [X BYO Key Setup Guide](/dashboard/connect-social-accounts/x-twitter-byo-keys) for step-by-step instructions, code examples, and troubleshooting.

## Content Type

The Content Type should always be set as `Content-Type: "application/json"` unless the endpoint specifically specifies otherwise.

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -H "Authorization: Bearer API_KEY" \ 
       -H "Profile-Key: PROFILE_KEY" \ # Optional
       -H "Content-Type: application/json" \
       -X GET https://api.ayrshare.com/api
  ```

  ```javascript JavaScript theme={"system"}
  headers: {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json"
  }
  ```

  ```python Python theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", # Optional
    "Content-Type": "application/json"
  }
  ```

  ```php PHP theme={"system"}
  $headers = [
    "Authorization" => "Bearer API_KEY",
    "Profile-Key" => "PROFILE_KEY", # Optional
    "Content-Type" => "application/json"
  ];
  ```

  ```go Go theme={"system"}
  headers := map[string]string{
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json"
  }
  ```

  ```ruby Ruby theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", # Optional
    "Content-Type": "application/json"
  }
  ```

  ```java Java theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json"
  }
  ```

  ```csharp C# theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json"
  }
  ```

  ```rust Rust theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json"
  }
  ```
</CodeGroup>

## Compression

Ayrshare supports compression for all API requests.
To enable compression, set the `Accept-Encoding` header to `deflate, gzip, br`.

```bash theme={"system"}
  Accept-Encoding: "deflate, gzip, br"
```

This is recommended for calling larger responses such as the [/history endpoint](/apis/history/overview).

<ul class="custom-bullets">
  <li>Only responses over 1024 bytes (1KB) are compressed.</li>

  <li>
    The order of compress used: Brotli (br) first, then gzip, then deflate. Brotli is the most
    efficient compression algorithm.
  </li>

  <li>
    The response header contains the content encoding used. For example: `content-encoding: br` if
    Brotli was used.
  </li>

  <li>
    Learn more about compression and the benefits of using compression in the [Ayrshare
    Blog](https://www.ayrshare.com/http-compression-in-node-js-a-dive-into-gzip-deflate-and-brotli/).
  </li>
</ul>

<Tip>Don't forget to properly uncompress the response using the content encoding.</Tip>

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -H "Authorization: Bearer API_KEY" \ 
       -H "Profile-Key: PROFILE_KEY" \ # Optional
       -H "Content-Type: application/json" \
       -H "Accept-Encoding: deflate, gzip, br" \ 
       -X GET https://api.ayrshare.com/api
  ```

  ```javascript JavaScript theme={"system"}
  headers: {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json",
    "Accept-Encoding": "deflate, gzip, br"
  }
  ```

  ```python Python theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", # Optional
    "Content-Type": "application/json",
    "Accept-Encoding": "deflate, gzip, br"
  }
  ```

  ```php PHP theme={"system"}
  $headers = [
    "Authorization" => "Bearer API_KEY",
    "Profile-Key" => "PROFILE_KEY", # Optional
    "Content-Type" => "application/json",
    "Accept-Encoding" => "deflate, gzip, br"
  ];
  ```

  ```go Go theme={"system"}
  headers := map[string]string{
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json",
    "Accept-Encoding": "deflate, gzip, br"
  }
  ```

  ```ruby Ruby theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", # Optional
    "Content-Type": "application/json",
    "Accept-Encoding": "deflate, gzip, br"
  }
  ```

  ```java Java theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json",
    "Accept-Encoding": "deflate, gzip, br"
  }
  ```

  ```csharp C# theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json",
    "Accept-Encoding": "deflate, gzip, br"
  }
  ```

  ```rust Rust theme={"system"}
  headers = {
    "Authorization": "Bearer API_KEY",
    "Profile-Key": "PROFILE_KEY", // Optional
    "Content-Type": "application/json",
    "Accept-Encoding": "deflate, gzip, br"
  }
  ```
</CodeGroup>

## ID Types

There are several types of IDs returned, which can be used in various endpoints:

### Ayrshare Post ID

This ID is generated by Ayrshare and returned from the
[/post endpoint](/apis/post/post) in the `id` field. This ID makes it easy
to get analytics on the post across social networks, add comments to the
post, delete the post, etc. This is the ID you will use most often.

### Social Post ID

Each social network assigns their own unique ID to posts and comments.
These IDs are returned in the `postIds` field of the /post or /comments endpoints.
You can use these IDs, or ones you get directly from the social networks, to retrieve data, such as with the [analytics social post ID](/apis/analytics/social-by-id).

### Ayrshare Comment ID

This ID is generated by Ayrshare and returned from the
[/comments endpoint](/apis/comments/post-comment) in the `id` field. This ID makes it easy
to get analytics on the comment across social networks, add replies to the
comment, delete the comment, etc. This is the ID you will use most often.

This is often used if you want to get details on a particular comment published via Ayrshare.

### Social Comment ID

Each social network assigns their own unique ID to comments.
These IDs are returned in the `commentId` field of the [GET /comments endpoint](/apis/comments/get-comments).

This is often used if you want to get details on a particular comment published outside of Ayrshare.

## Error Codes

Errors will return with [standard HTTP status codes](https://tools.ietf.org/html/rfc2616#section-10).

For more information:

<Card title="HTTP Status Codes" icon="link" horizontal href="/errors/errors-http">
  Learn more about HTTP status codes
</Card>

Detailed Errors are in the REST API response specific for each type of call.

For more information:

<Card title="Ayrshare Error Codes" icon="link" horizontal href="/errors/errors-ayrshare">
  Learn more about Ayrshare-specific error codes
</Card>

## Timestamp Format

Ayrshare uses Zulu Time, also known as UTC (Coordinated Universal Time) or an ISO 8601 formatted date string, for a precise and unambiguous time references across different time zones.

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.

You can convert the UTC format to your local time in the programming language of your choice. For example in JavaScript:

```javascript theme={"system"}
const convertToLocalTime = (isoString) => {
  // Create a new Date object from the ISO string
  const date = new Date(isoString);

  // Extract local time components
  const localDate = date.toLocaleDateString();
  const localTime = date.toLocaleTimeString();

  // Combine the local date and time
  const localDateTime = `${localDate} ${localTime}`;

  return localDateTime;
};
```

## Postman

You can use Postman to test your REST API calls.

<Card title="Postman" icon="link" horizontal href="/testing/postman">
  Learn how to use Postman with our API
</Card>

## Random Posts, Images, and Videos

Check out the [quick start guide](/quickstart#publish-test-posts) on how to send random posts, images, or videos when testing.

## Packages

We have both Node.js & Python packages, Bubble.io, Airtable, and Make guides available to make the RESTful calls easier.

<CardGroup cols={2}>
  <Card title="Node NPM Package" icon="cube" iconType="duotone" href="/packages-guides/nodejs" horizontal>
    Integrate using our NodeJS package
  </Card>

  <Card title="Python PyPI Package" icon="cube" iconType="duotone" href="/packages-guides/python" horizontal>
    Integrate using our Python package
  </Card>

  <Card title="Airtable Guide" icon="book-open" iconType="duotone" href="/packages-guides/airtable" horizontal>
    Learn how to use Ayrshare with Airtable
  </Card>

  <Card title="Bubble Plugin & Guide" icon="cube" iconType="duotone" href="/packages-guides/bubble" horizontal>
    Learn how to use Ayrshare with Bubble.io
  </Card>

  <Card title="Make Guide" icon="book-open" iconType="duotone" href="/packages-guides/make" horizontal>
    Learn how to use Ayrshare with Make
  </Card>

  <Card title="Notion Guide" icon="book-open" iconType="duotone" href="/packages-guides/notion" horizontal>
    Learn how to use Ayrshare with Notion
  </Card>

  <Card title="FlutterFlow Guide" icon="book-open" iconType="duotone" href="/packages-guides/flutterflow" horizontal>
    Learn how to use Ayrshare with FlutterFlow
  </Card>

  <Card title="Retool Guide" icon="book-open" iconType="duotone" href="/packages-guides/retool" horizontal>
    Learn how to use Ayrshare with Retool
  </Card>
</CardGroup>