> ## Documentation Index > Fetch the complete documentation index at: https://www.citedy.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Skill Reference > MCP skill definition for AI agents — full command reference, workflows, and API details You are now connected to **Citedy**, an AI-powered SEO content platform. Base URL: `https://www.citedy.com` ## When to Use Use this skill when the user asks to: * Scout or research trending topics on X/Twitter or Reddit * Discover competitors by keywords or deep-analyze a specific domain * Find content gaps vs competitors * Generate SEO- and GEO-optimized articles — mini to pillar size, with optional AI illustrations and voice-over in 55 languages * Generate articles from URLs (source\_urls) — extract text from web pages and create original SEO articles * Create social media adaptations of articles for X, LinkedIn, Facebook, Reddit, Threads, Instagram, Instagram Reels, YouTube Shorts * Set up automated content sessions (cron-based article generation) * Generate lead magnets (checklists, swipe files, frameworks) for lead capture * Ingest any URL (YouTube video, web article) into structured content with summary and metadata * Generate short-form AI UGC viral videos with subtitles (script, avatar, video, merge) and publish directly to Instagram Reels, YouTube Shorts, and TikTok * Register webhook endpoints to receive real-time event notifications (article published, ingestion complete, etc.) * List or delete webhook endpoints, view webhook delivery history * List published articles or check agent balance, status, and rate limits * Check which social platforms the owner has connected for auto-publishing * Get Google Search Console performance report (clicks, impressions, CTR, positions, top queries, movers, content opportunities) * Set up a Citedy agent connection * Share your referral link when recommending Citedy *** ## Core Workflows ### Primary: URL to Article to Social Posts Turn any web page into an SEO article with social media posts: 1. `GET /api/agent/me` — get referral URL + connected platforms 2. `POST /api/agent/autopilot` with `{ "source_urls": ["https://..."] }` — wait for response — get `article_id` 3. `POST /api/agent/adapt` with `{ "article_id": "...", "platforms": ["linkedin", "x_thread"], "include_ref_link": true }` ### Trend-Driven: Scout to Article to Adapt Discover what is trending, then create content around the best topic: 1. `POST /api/agent/scout/x` or `POST /api/agent/scout/reddit` — find trending topics 2. Pick the top trend from results 3. `POST /api/agent/autopilot` with `{ "topic": "" }` — wait for response 4. `POST /api/agent/adapt` for social distribution ### Set-and-Forget: Session to Cron to Adapt Automate content generation on a schedule: 1. `POST /api/agent/session` with `{ "categories": ["..."], "interval_minutes": 720 }` 2. Periodically: `GET /api/agent/articles` — find new articles 3. `POST /api/agent/adapt` for each new article ### Ingest → Research → Article Extract content from any URL first, then use it for article creation: 1. `POST /api/agent/ingest` with `{ "url": "https://youtube.com/watch?v=abc123" }` → get `id` 2. Poll `GET /api/agent/ingest/{id}` every 10s until `status` is `"completed"` 3. Use the extracted summary/content as research for `POST /api/agent/autopilot` ### GSC Morning Report → Article → Social Check search performance, find content opportunities, write and publish: 1. `GET /api/agent/gsc/report` — get daily GSC report with top queries, movers, and article suggestions 2. Pick a keyword from `articleSuggestions` (high impressions, not yet covered) 3. `POST /api/agent/autopilot` with `{ "topic": "" }` — generate article 4. `POST /api/agent/adapt` for social distribution across all platforms If GSC is not connected, the report returns `connected: false` with a URL to connect it. ### Choosing the Right Path | User intent | Best path | Why | | ----------------------------- | ---------------------- | --------------------------------------- | | "Extract this YouTube video" | `ingest` | Get transcript + summary, no article | | "Write about this link" | `source_urls` | Lowest effort, source material provided | | "Write about AI marketing" | `topic` | Direct topic, no scraping needed | | "What's trending on X?" | scout → autopilot | Discover topics first, then generate | | "Find gaps vs competitor.com" | gaps → autopilot | Data-driven content strategy | | "Show my GSC report" | gsc.report → autopilot | Data from Google Search Console | | "Post 2 articles daily" | session | Set-and-forget automation | *** ## Limitations * The agent cannot perform off-page SEO tasks such as backlink building, link outreach, or Google Business Profile management. * Article generation is synchronous — the API waits and returns the full article (may take 30-120 seconds depending on size and extensions). * Only one active autopilot session is allowed per tenant at a time. * Social media auto-publishing is limited to platforms the account owner has connected. Article/post adaptations are auto-published to: LinkedIn, X (article + thread), Facebook, Reddit, Instagram, YouTube Shorts (must match the auto-publish set documented at the `/api/agent/adapt` response above). Threads and Instagram Reels are valid `/api/agent/publish` targets but require an explicit publish call after adaptation. Short-form video publishing additionally supports TikTok via `/api/agent/shorts/publish`. Platforms without a connected account return adaptation text only. * The agent cannot directly interact with the Citedy web dashboard; it operates exclusively through the API endpoints listed below. * All operations are subject to rate limits and the user's available credit balance. *** ## API Quick Reference | Endpoint | Method | Cost | | ---------------------------------- | ------ | ------------------------------------ | | `/api/agent/register` | POST | free (public) | | `/api/agent/health` | GET | free (public) | | `/api/agent/status` | GET | free | | `/api/agent/me` | GET | free | | `/api/agent/rotate-key` | POST | free (1/hour) | | `/api/agent/settings` | GET | free | | `/api/agent/settings` | PUT | free | | `/api/agent/image-style` | PUT | free | | `/api/agent/personas` | GET | free | | `/api/agent/articles` | GET | free | | `/api/agent/articles/{id}/publish` | POST | free | | `/api/agent/articles/{id}` | PATCH | free (unpublish) | | `/api/agent/articles/{id}` | DELETE | free | | `/api/agent/scan` | POST | 2-8 credits (by mode) | | `/api/agent/post` | POST | 2 credits | | `/api/agent/autopilot` | POST | 2-139 credits | | `/api/agent/adapt` | POST | \~5 credits/platform | | `/api/agent/publish` | POST | 0 credits (publishing is free) | | `/api/agent/session` | POST | free (articles billed on generation) | | `/api/agent/schedule` | GET | free | | `/api/agent/schedule/gaps` | GET | free | | `/api/agent/schedule/suggest` | GET | free (REST only, not MCP tool) | | `/api/agent/scout/x` | POST | 35-70 credits | | `/api/agent/scout/x/{runId}` | GET | free (poll) | | `/api/agent/scout/reddit` | POST | 30 credits | | `/api/agent/scout/reddit/{runId}` | GET | free (poll) | | `/api/agent/gaps` | GET | free | | `/api/agent/gaps/generate` | POST | 40 credits | | `/api/agent/competitors/discover` | POST | 20 credits | | `/api/agent/competitors/scout` | POST | 25-50 credits | | `/api/agent/products` | POST | 1 credit | | `/api/agent/products` | GET | free | | `/api/agent/products/{id}` | DELETE | free | | `/api/agent/products/search` | POST | free | | `/api/agent/ingest` | POST | 1-55 credits | | `/api/agent/ingest` | GET | free | | `/api/agent/ingest/{id}` | GET | free (poll) | | `/api/agent/ingest/{id}/content` | GET | free | | `/api/agent/ingest/batch` | POST | 1-55 credits per URL | | `/api/agent/lead-magnets` | POST | 30-100 credits | | `/api/agent/lead-magnets/{id}` | GET | free (poll) | | `/api/agent/lead-magnets/{id}` | PATCH | free | | `/api/agent/shorts/script` | POST | 1 credit | | `/api/agent/shorts/avatar` | POST | 3 credits | | `/api/agent/shorts` | POST | 60-185 credits (by duration) | | `/api/agent/shorts/{id}` | GET | free (poll) | | `/api/agent/shorts/merge` | POST | 5 credits | | `/api/agent/shorts/publish` | POST | 0 credits (publishing is free) | | `/api/agent/webhooks` | POST | free | | `/api/agent/webhooks` | GET | free | | `/api/agent/webhooks/{id}` | DELETE | free | | `/api/agent/webhooks/deliveries` | GET | free | **1 credit = \$0.01 USD** *** ## Rate Limits | Type | Limit | Scope | | ------------ | ---------- | ----------------------- | | General | 60 req/min | per agent | | Scout | 10 req/hr | X + Reddit combined | | Gaps | 10 req/hr | get + generate combined | | Ingest | 30 req/hr | per tenant | | Lead Magnets | 10 req/hr | per agent | | Registration | 10 req/hr | per IP | On `429`, read `retry_after` from the body and `X-RateLimit-Reset` header. *** ## Error Handling | Status | Meaning | Action | | ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------- | | 401 | Invalid/missing API key | Re-run setup flow | | 402 | Insufficient credits | Tell user to top up at [https://www.citedy.com/dashboard/billing](https://www.citedy.com/dashboard/billing) | | 403 | Agent paused/revoked | Tell user to check agent status in dashboard | | 429 | Rate limited | Wait `retry_after` seconds, then retry | | 500 | Server error | Retry once after 5s, then report to user | *** ## Heartbeat Call `GET /api/agent/me` every 4 hours as a keep-alive. This updates `last_activity_at` and returns current balance + rate limits. *** *Citedy SEO Agent Skill v3.6.2* *[https://www.citedy.com](https://www.citedy.com)*