post

Ayrshare MCP — Posts

The validate/write/read/lifecycle tools for individual social posts: validate, create or schedule, fetch, update, and retry. All operate on the profile selected by the optional profileKey argument or the connection's Profile-Key header (the argument wins when both are set).

• API base (REST endpoints the tools wrap): https://api.ayrshare.com/api
• Platform enum (the only valid values, verbatim): twitter, facebook, instagram, linkedin, tiktok, youtube, pinterest, reddit, telegram, gmb, bluesky, snapchat, threads — full table with notes in references/platforms.md.

Function table

Tool	Purpose	Method + Endpoint	Required inputs	Optional inputs
mcp__ayrshare__validate_post	Dry-run a post: check platform-specific issues (char limits, unsupported media) WITHOUT publishing	POST /validate/post	post (text), platforms (array of enum)	mediaUrls, scheduleDate (ISO 8601), and the full content/scheduling/platform-options surface — see references/create-post-schema.md
mcp__ayrshare__create_post	Create or schedule a post	POST /post	post (text), platforms (array of enum)	mediaUrls, scheduleDate (ISO 8601), and the full content/scheduling/platform-options surface — see references/create-post-schema.md
mcp__ayrshare__get_post	Fetch a post's details/status	GET /post/:id	id	— (none)
mcp__ayrshare__update_post	Update a PENDING post (edit/approve/reschedule)	PATCH /post	id + at least one of the optional fields	scheduleDate, approved (bool), notes (string), disableComments (bool; on update, Instagram/LinkedIn only, and disabling on LinkedIn deletes existing comments), scheduledPause (bool), youTubeOptions (object; reuses the create-side schema where title is required, so re-send the existing title even when changing only visibility/description/categoryId)
mcp__ayrshare__retry_post	Retry a post in status error, once, if the error was retryable	PUT /post/retry	id	— (none)

Full create_post/validate_post input schema and example payloads are in references/create-post-schema.md and references/examples.md.

Auth note

The Business API key (Authorization: Bearer <key>) is configured when the MCP server is installed. See ../getting-started/SKILL.md for installation and the full auth model; don't re-derive it here. Profile scoping is the optional profileKey tool argument or the Profile-Key connection header (the argument wins when both are set). To act as a different client profile, pass its profileKey on the call or reconfigure the connection's Profile-Key; with neither, calls act under the account's primary/Business profile.

Usage guidance

• Sequencing is mandatory: validate → confirm → create. Always call mcp__ayrshare__validate_post first to dry-run the content/platforms for issues (character limits, unsupported media) without publishing. Surface any issues and ask how to proceed. Then show the user a summary (content, platforms, scheduled time) and get explicit confirmation. Only then call mcp__ayrshare__create_post. On any per-platform failure in the result, call mcp__ayrshare__explain_error and surface the plain-language explanation.
• Publishing vs scheduling is one tool: mcp__ayrshare__create_post. Omit scheduleDate to post immediately; include it (ISO 8601, a future time) to schedule. There is no separate "schedule" tool. create_post is synchronous and returns per-platform postIds.
• Editing is primarily for PENDING posts (scheduled, awaiting approval). Use mcp__ayrshare__update_post with the returned id and at least one editable field: scheduleDate (reschedule), approved (approve), notes, disableComments, scheduledPause, or youTubeOptions. Two update_post gotchas worth knowing up front: youTubeOptions reuses the create-side schema, so title is required even for a visibility-only change (re-send the existing title or the call returns a 400); and disableComments on update applies only to Instagram and LinkedIn, where disabling on LinkedIn deletes existing comments.
• Inspecting before acting: when the user references a prior post and you're unsure of its state (scheduled, live, error), call mcp__ayrshare__get_post with the id first to read its status, then decide between update or retry.
• Retry is narrow: mcp__ayrshare__retry_post re-attempts a post in status error, ONCE, and only if the error was retryable. It is not a generic "send again" — to recover a failure, use retry_post, NOT a second create_post. See Gotchas.
• Attaching media: put image/video URLs in mediaUrls. Validate them first — sequencing in Gotchas, full media workflow in ../media/SKILL.md.
• Capture the id returned by create_post. Get/update/retry all key off it; without it you can't manage the post later.

Gotchas

• Always validate before posting. The repo's social-manager agent enforces mcp__ayrshare__validate_post → confirm → mcp__ayrshare__create_post. Skipping validation lets avoidable per-platform rejections (over-limit text, unsupported media) reach publish time.
• Profile scoping: profileKey argument or Profile-Key header. Each post tool takes an optional profileKey argument (it wins over the Profile-Key connection header). With neither set, every call acts under the account's primary/Business profile. To target a client profile, pass its profileKey on the call or set the connection header. (Shared rule, see getting-started.)
• Invalid platforms enum value. platforms accepts only the 13 values listed above. Common misses: x or X instead of twitter; google, google_business, or googlebusiness instead of gmb; fb/ig/li shorthands. One bad value rejects the call — see references/platforms.md.
• scheduleDate must be ISO 8601. e.g. 2026-06-05T14:30:00Z. Omit the field entirely to post now — do not pass an empty string or a human phrase like "Friday". Convert relative dates to an absolute ISO timestamp yourself before calling.
• Media must exist and verify before you reference it. A mediaUrls entry that is unreachable or the wrong format fails the post. Check media first via ../media/SKILL.md (mcp__ayrshare__validate_media, which HEAD-checks a URL is reachable and reports its content type), then pass the confirmed URLs into create_post.
• Advanced fields are first-class typed inputs — there is no generic passthrough. create_post/validate_post accept far more than post/platforms/mediaUrls/scheduleDate: firstComment, autoSchedule, autoRepost, autoHashtag, unsplash, disableComments, shortenLinks, requiresApproval, notes, idempotencyKey, and 12 per-platform option objects (e.g. youTubeOptions.title, required for YouTube; redditOptions.title + subreddit, required for Reddit). Set them directly as top-level fields. There is no passthrough/escape-hatch field — unknown keys are dropped. Full list in references/create-post-schema.md.
• retry_post is error-only and one-shot. It re-attempts a post in status error, exactly once, and only if the error was retryable. It is not a way to duplicate a successful post. Calling it on a non-error post won't behave like "post again". Check status with mcp__ayrshare__get_post if unsure.
• On failure, explain — don't auto-retry. When any post tool errors, call mcp__ayrshare__explain_error to translate the API error to plain language, then surface it. Never auto-retry create/update on a 4xx (bad input, wrong key, missing permission) — retrying a write can duplicate a post. A 429 gets at most one retry after a short delay. (Mirror of the global retry-safety rule — full version in getting-started.)