---
title: "Install Ayrshare using AI"
description: "Paste one prompt into Claude Code, Codex, Cursor or Gemini CLI and your coding assistant integrates the Ayrshare social media API for you, safely."
canonical: https://www.ayrshare.com/install/
lastModified: 2026-10-12
pageType: ai-agent
---

# Install Ayrshare using AI

> Paste one prompt into Claude Code, Codex, Cursor or Gemini CLI and your coding assistant integrates the Ayrshare social media API for you, safely.

## Install Ayrshare using AI

One API for posting, scheduling, analytics, comments and DMs across 14+ social networks. Your coding assistant can do the integration. This page is the brief you hand it.

[Start your 28-day free trial](https://billing.ayrshare.com/b/9B6bJ15Oidr9fz615u1Nu0h)
[Read the docs](/docs)

Already have a plan? Skip the trial. Useful links: [Dashboard](https://app.ayrshare.com), [Docs](/docs), [API Explorer](https://apiexplorer.ayrshare.com), [Pricing](/pricing/).

## For humans

**One prompt and the AI takes over.**

Open your project in Claude Code, Codex, Cursor, Gemini CLI, or whichever assistant you use, and paste this:

```text
Read https://www.ayrshare.com/install and integrate Ayrshare into this project.
```

It will ask what you're building, walk you through adding your API key, and show you Ayrshare in action in less than 10 minutes.

_Everything below is written for the assistant, but it's the same document either way: read it and you'll know exactly what the assistant is about to do to your codebase._

## For the AI assistant

**Read all of it before you touch a file.**

### 01 · Capability gate

You need to read files, write files, and run shell commands in this project. If you can only do one of those, stop and say so. A partial integration that looks finished is worse than no integration.

### 02 · Ask brand or platform before anything else

Your first message to the user is this question: are you posting for your own brand, or building social into a product your customers use?

Ask it even if you think you can tell from the codebase. Don't infer it, don't offer a default, and don't start work without an answer. It decides whether User Profiles exist at all, and adding them later means reworking every call.

|  | Your own brand | Social inside their product |
| --- | --- | --- |
| What it is | They post, schedule and measure across their company's own accounts. | They're adding social publishing to a SaaS their own customers use. |
| What it needs | One API key, no profiles, post directly. Premium is built for this. | A User Profile per customer, a Profile Key on every call, and a linking page the customer completes. Launch and up. |

Both use the same API and the same key. The second is the first plus a layer.

> **Explain what a profile is before they answer.** A profile is a brand, not an account: one profile covers that brand on every network. Pearl Bank on Instagram, LinkedIn and TikTok is one profile with three networks connected, not three profiles. People undercount what they're getting, so say it plainly: they're counting brands, not logins.

### 03 · Install the docs MCP, and keep it

Do this before you write code. It needs no authentication, and it means every Ayrshare question you or the user ask from now on is answered from the live documentation instead of whatever you were trained on. Use only its search and retrieval tools. It also exposes a `submit_feedback` tool that sends a message to the docs team. Don't call it unless the user asks you to.

```bash
# Claude Code
claude mcp add --transport http ayrshare https://www.ayrshare.com/docs/mcp
```

It's a standard HTTP MCP server. Most other clients take the same URL in an `mcp.json`:

```json
{ "mcpServers": { "Ayrshare MCP": { "url": "https://www.ayrshare.com/docs/mcp" } } }
```

Cursor uses `.cursor/mcp.json`, VS Code uses `.vscode/mcp.json`, and Codex uses its own config. Remote MCP support, config location, approval prompts and whether a restart is needed all vary by client and version, so check the [MCP docs](/docs/additional/mcp-server) for yours rather than assuming. If your client can't reach a remote MCP server at all, skip this step and cite [the docs](/docs) directly instead. Don't fake it from memory.

Once it's working, **ask** before recording it anywhere persistent. Writing it into `CLAUDE.md`, a Cursor rules file or a committed config changes the project's instructions for everyone and makes a third-party remote service available to future sessions. That's the user's call, not yours. If they say yes, prefer project-local config over anything global, and tell them the one line to delete to undo it.

### 04 · Walk them through the API key

Don't assume the key is already in the project. Ask for it, then set it up with them.

Their key arrived in the **integration package emailed to the address they signed up with**. If that inbox isn't theirs, or the key needs rotating, it's managed at [app.ayrshare.com](https://app.ayrshare.com). Warn them that regenerating invalidates the old key before they click.

Use whatever this project already uses for server-side secrets: a secret manager, the platform's environment config, or an untracked `.env`. Don't assume `.env` is right; look first. If it is `.env`, confirm `.env` is already in `.gitignore` before anything is written, and add the variable name (not the value) to `.env.example` if the project keeps one.

> **The key is server-side only, with no exceptions.** Never ask the user to paste it into the chat. Have them put it in the secret store themselves and tell you when it's there. Never put it in client-side code, a `NEXT_PUBLIC_*` or `VITE_*` variable, a mobile app bundle, a test fixture, a log line, an error message, a screenshot or any tracked file. An Ayrshare key that reaches a browser is a key that posts to the user's accounts from anyone's browser. Calls go from their server; the client talks to their server.

### 05 · Confirm the account can do what's being asked (read only)

Call `GET /api/user` with the key. It returns the plan, the connected networks, and the monthly post quota where the plan has one. Read it back to the user before planning anything. Profiles need a Launch plan or above, so if they picked the platform path on a plan that can't carry it, say so now rather than after the code is written.

If they need to pick a plan, there are two answers for an install: **Premium** for one brand, **Launch** for a platform or product. Business and Enterprise add more volume later, and moving up is a billing change, not a rewrite. Reassure them on the thing they're actually worried about: the feature set is the same across plans, Launch is the entry-level Business tier rather than a cut-down one, and nothing built on the trial has to be rebuilt. The single add-on is Max Pack (AI generation, longer JWT expiry with email links, link shortening with analytics, image resize and alt text), included with Enterprise. Send them to the [pricing page](/pricing/) for current numbers. Never quote figures from memory.

### 06 · Ask: API or MCP?

There are two ways in, and the user picks. Put the question to them in one line rather than choosing silently.

- **REST API:** direct HTTPS calls from your own code, using whatever HTTP client the project already has. This is what almost everyone wants. It's the whole surface, it runs in production, and it adds no dependency.
- **Action MCP:** Ayrshare exposed as MCP tools your assistant calls directly, authenticated with a Bearer token. Right for driving social accounts from inside an agent. It's not a substitute for the REST integration in a shipped product, and it's not the same thing as the docs MCP from step 03, which everyone keeps either way.

Then read `package.json`, the lockfile and the framework config so the code you write matches the project's existing conventions. Don't add a dependency the project doesn't already use.

### 07 · Platform path only: get the profile model right (skip if own brand)

Create one User Profile per customer and store the Profile Key against your own user record. Every later call carries that key, not the account key.

Then settle the multi-tenant questions before writing the code, because an integration can look completely correct and still be wrong on every one of them:

- **Authorization.** Which of their users may act for which profile, and where that check happens: on their server, on every request, before the Profile Key is chosen. Never let a client supply the Profile Key or the profile id; derive it server-side from the signed-in session. That single mistake lets any customer post as any other.
- **Isolation.** Profile Keys are credentials. Store them where the account key lives, never in client-reachable state, never in logs, and never in a response body.
- **Linking.** Who triggers the linking URL, how long it lives, where the user lands afterwards, and what the UI shows while nothing is connected yet.
- **Offboarding.** What happens when their customer cancels or asks to be deleted: which profile is deleted, which links are revoked, what's kept and for how long. Decide it now; it's far harder to add later than to build in.
- **Call surface.** Which service is allowed to call Ayrshare at all. One server-side path, not scattered call sites.

> **Profile titles must be unique within your account.** Creating a second profile with a title that already exists is rejected, not silently de-duplicated. Most integrations make the title unique by appending something to an email. That title is also what the account-linking page shows by default, as "Social Accounts for <title>", so set `topHeader` to the clean heading your user should actually see, or `hideTopHeader` to drop it entirely.

### 08 · Write the plan before the code

Show the user the files you intend to create or change, the environment variables you'll add, and the endpoints you'll call. Wait for a yes. Never write a key into a tracked file.

### 09 · Prove it works by reading, not posting

Do not make a live post as the first milestone. A post is public and permanent, it lands in front of a real audience, and it stalls the user on "what do I even post right now?" That question has ended more integrations than any API error.

Build this instead. It takes minutes and it ends with something the user didn't have before:

1. Ask before linking anything. Connecting a social account is a real authorization on a real account, so it needs an explicit yes, not an assumption. Then link one account. Offer Facebook, Instagram, TikTok, YouTube and LinkedIn first, because that's where most people already have an audience, but present them as the common choices, not the only supported ones. Every network works equally well, and the rest are often exactly why someone picked Ayrshare.
1. Call `GET /api/history/{platform}`, paginating to about 100 posts. Fewer is fine; it's a demo, not a backfill.
1. Rank them and print the top five.

Say out loud what you're ranking on, because "engagement" isn't one number. Pick the fields the platform actually returned (likes plus comments plus shares, say), name them in the output, and don't invent a weighted score the user can't check. Ask for the minimum data the report needs; there's no reason to pull a full archive to show five rows.

If there's no usable history (a brand-new account, a network that returns nothing, analytics not available on the plan), don't force it. Say so, and fall back to reading what _is_ there: the connected account's profile and follower count via `GET /api/user`, or the network's capabilities from the docs MCP. A short honest read beats a made-up chart.

Use the per-platform history endpoint, not `/api/history`. The plain one returns only posts sent through Ayrshare, which for a new user is an empty array. The per-platform one returns posts and their analytics whether they were made through Ayrshare or posted directly on the network, so it works on day one against content they published long before they'd heard of us.

The output is "here are your five best-performing posts", worked out from their own live data. That proves auth, the account connection and the analytics path in one pass, and it hands them an answer rather than a green tick. Nothing is published and nothing has to be decided. Post only when the user asks, and only on an explicit yes.

**Then offer two next moves, and let them pick.** Both keep the no-pressure shape, and either one is a better second impression than a test post.

**Read and reply to comments on their top post.** Pull them with `GET /api/comments` and offer to reply with `POST /api/comments/reply`. This is the first time they write anything through Ayrshare, and it lands on their own existing content as a reply rather than a broadcast, so the stakes are low and the value is obvious.

_A reply is still a public post under their name. Before sending, show the exact text, the account it posts from, and the post and comment it answers. Then get one explicit yes, right before the call. Not a yes from earlier in the conversation, and never a batch of replies approved in one go._

**Show what they can post on that network.** Ask the docs MCP you installed in step 03 what the connected network supports (carousels, reels, stories, scheduling, first comment, alt text, whatever applies) and list it. No calls, no commitment, and it answers the question they're actually holding: what can I build with this?

> **Check `status` before you rank anything.** Getting history takes several calls behind the scenes. If one fails part-way, you still get the posts fetched so far and `status: "partial"` instead of `"success"`. Ranking a partial set produces a confident, wrong top five with no error anywhere. Treat partial as "this page is incomplete" and retry. Partial responses are never cached, so a retry re-reads from the platform.

> **X needs the user's own credentials.** Since 31 March 2026 every X operation requires them, passed as `X-Twitter-OAuth1-Api-Key` and `X-Twitter-OAuth1-Api-Secret` headers. Say the reassuring part too, and say it precisely: the app is owned by the Ayrshare account holder (the person building this integration), and there is exactly one of them. The same consumer key and secret go on every X-bound request for every sub-profile. Their end users authorize that app through the normal OAuth linking flow and never create a developer app of their own.

### 10 · Add scheduling, analytics and webhooks only if asked

Each is a separate endpoint and a separate decision.

Webhooks are the one to be careful with, because they mean standing up a public endpoint. If the project has no public route today, say so and stop. Don't create an internet-facing route just to satisfy the integration. If they do want one, it needs all of this, not some of it: verify the signature against the _raw_ request body before parsing it (most frameworks hand you a re-serialized body, which will not match); reject anything with a stale or missing timestamp so a captured request can't be replayed; treat the delivery id as an idempotency key, because retries and duplicates are normal; cap the accepted request size; and keep the signing secret in the same place as the API key, rotatable without a redeploy. Return quickly and do the work in the background. A slow handler becomes a retry storm.

### 11 · Rate limits: nothing runs in an open-ended loop

This is the one step where ordinary sloppiness has a consequence you can't fix later. A runaway retry costs more than quota: the network can suspend the account the user just connected, and nothing on the Ayrshare side reverses that. Treat every limit below as a hard constraint in the code you write, not a note in a comment.

**There are two ceilings, and they're independent.** Ayrshare allows 300 API requests per 5-minute window, and every response carries `x-ratelimit-max` and `x-ratelimit-count`. Read them rather than discovering the limit by hitting it. Separately, each network caps posting on its own: Instagram 50 posts per rolling 24 hours, LinkedIn 150 per day, TikTok 15 videos per day and 6 photos per minute. Ask the docs MCP for the current numbers for the networks this project actually uses instead of hardcoding what you remember.

**Both ceilings are per user, not per account.** The Ayrshare rate limit is counted per User Profile, and each network's posting cap applies to that profile's own connected account. A platform with 500 customers has 500 separate budgets, not one shared pool. So scale doesn't use up the limit, and there's no reason to build a global throttle across your whole customer base. It also means fairness has to be tracked per profile: a per-user counter and a per-user backoff, so one busy tenant can't stall everyone else behind a single global queue. That's not an argument against global safety controls. A production service still wants bounded worker concurrency, a circuit breaker that trips on a provider outage, and a ceiling on total spend and total in-flight calls. Per-profile limits for fairness, bounded global controls for safety; the mistake is using a single global throttle as the fairness mechanism. It cuts the other way too: one profile going over doesn't hurt the others, but that profile alone is the one that gets suspended.

**Those caps are ceilings, not targets.** Nobody should design toward them. Posting less almost always performs better than posting more. Engagement per post falls off fast, and an account that publishes at the limit every day looks automated to both the audience and the network's own spam filters. If an integration is regularly nearing a daily cap, treat that as a sign the design is wrong, say so, and ask what the user is actually trying to achieve. The exception is a platform whose volume is spread across many customers' own accounts, a few posts each. That isn't one account at the limit; it's hundreds nowhere near it. Everyone else is better served by fewer, better-scheduled posts.

**For someone just testing, the right shape is one post to a couple of networks, once or twice a day.** That's enough to see publishing, scheduling and analytics work end to end, and it stays far inside every cap. Rapid-fire test posts to one account are exactly the pattern that gets flagged, and they're also the posts a real audience sees. If the user wants to exercise the API harder than that, point them at the read endpoints and the [API Explorer](https://apiexplorer.ayrshare.com) instead of the publish path.

**Every loop gets a bound.** A fixed maximum attempt count, exponential backoff with jitter, a bounded batch size on any queue drain, and an explicit stop condition on any poll. No `while (true)`, no failure path that re-queues its own job, and no scheduled task that can fire again before the previous run finished.

**A 429 is a stop signal, not a cue to try sooner.** Honor `Retry-After` when it's there (Ayrshare passes Instagram's through on the error's `details` field), and otherwise back off from a minute upward. Never retry a 429 immediately, and never fan the retry out across profiles in parallel.

**Only retry what can succeed on a retry, and never retry a write blind.** A rejected post (unsupported media, missing permission, expired token) fails the same way every time; retrying it spends quota and reads as abuse, so surface those to the user instead. Timeouts and 5xx errors are retryable for _reads_. For anything that publishes, a timeout is ambiguous: the network may have accepted the post and lost the response, and retrying then double-posts to a real audience. Before resending a call that changes something, reconcile first: check `GET /api/history/{platform}` or the post id for the thing you were trying to create, and only resend if it genuinely isn't there. Where the endpoint supports an idempotency or reference key, use it. When in doubt, stop and ask the user rather than risk a duplicate.

Where the API gives you the count, use it: Instagram's post response includes `usedQuota`, the posts used in the current rolling 24 hours. Stop short of the ceiling rather than discovering it. And when you do refuse to send something, fail with a message that names the network and the limit, so the user knows it's a cap and not a bug.

> **The failure mode is a suspended account, not a failed request.** Repeatedly going over the Ayrshare rate limit can get the User Profile suspended, and the networks are less forgiving still. If you're unsure whether a pattern is aggressive, it is. Slow it down. The [rate limit docs](/docs/errors/errors-http#user-profile-rate-limits) and the [recommended posting limits](/docs/testing/post-verification#recommended-posting-limits) are the reference.

### 12 · Verify against live evidence

Show the user real API responses, not your summary of them: the history payload with their actual post IDs and analytics, and any published posts on the networks themselves. If something failed, re-run it in the [API Explorer](https://apiexplorer.ayrshare.com) and keep the Session ID. Support asks for it first.

### 13 · Point them at what's next

Once something is working, say two things before you stop.

**Link more networks.** They connected one to get going. Every extra one makes the same report they just saw more useful, because the top-five list gets better the more of their content it can see. Frame it that way rather than as setup admin.

**Send them to the** [**dashboard**](https://app.ayrshare.com)**.** It's where they'll manage keys, watch usage against quota, and see profiles once they have them. A developer who has only ever seen the API doesn't know it exists, and finds out the hard way when something needs changing.

## Rules

Non-negotiable, for any assistant running this.

- **Replacing an existing integration is a normal path, not an edge case.** Plenty of projects arrive here with direct Facebook, LinkedIn or X code already in place. Keep the old path until the new one is proven. But "side by side" means the Ayrshare path runs in shadow, doing reads and dry runs only, or behind an explicit routing switch that sends each post down exactly one path. Two live publishing paths post everything twice. Verify, cut over, then remove the old code.
- **Permission before changes.** Show what changes and wait. This applies to config files as much as source code.
- **Keys never land in a tracked file.** Environment variables only, and check that the ignore file already covers them before you write.
- **Post to real accounts only with a clear yes.** A test post is a real post. It appears on a real profile, in front of real followers.
- **Nothing runs unbounded.** Every retry, queue and poll has a hard ceiling and a backoff. Over-posting or hammering a rate limit can get the user's social account suspended, and no later code change undoes that.
- **Say when something is degraded.** If a network is connected but its token is stale, or a feature needs a higher plan, the integration still ships. It just has to say so out loud.

Questions the docs don't answer? Ask the [docs MCP](/docs/additional/mcp-server) first. For anything else, send support an [API Explorer](https://apiexplorer.ayrshare.com) session ID along with your question.

## Hand your assistant the brief

One prompt. Your coding assistant reads this page and builds the integration, with you approving every step.

[Start your 28-day free trial](https://billing.ayrshare.com/b/9B6bJ15Oidr9fz615u1Nu0h)
[Read the docs](/docs)