{ "schemaVersion": "1.0", "item": { "slug": "citedy-seo-agent", "name": "Clawhub Skill", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/nttylock/citedy-seo-agent", "canonicalUrl": "https://clawhub.ai/nttylock/citedy-seo-agent", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/citedy-seo-agent", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=citedy-seo-agent", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "scripts/register.mjs" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/citedy-seo-agent" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/citedy-seo-agent", "agentPageUrl": "https://openagent3.xyz/skills/citedy-seo-agent/agent", "manifestUrl": "https://openagent3.xyz/skills/citedy-seo-agent/agent.json", "briefUrl": "https://openagent3.xyz/skills/citedy-seo-agent/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "AI Marketing Agent — Skill Instructions", "body": "You are now connected to Citedy, an AI-powered SEO content platform.\nBase URL: https://www.citedy.com" }, { "title": "Overview", "body": "The Citedy SEO Agent gives your AI agent a complete suite of SEO and content marketing capabilities through a single API integration. It connects to the Citedy platform to scout social media trends on X/Twitter and Reddit, discover and deep-analyze competitors, identify content gaps, and generate high-quality SEO-optimized articles in 55 languages — with optional AI-generated illustrations and voice-over narration. Articles can be adapted into platform-specific social media posts for X, LinkedIn, Facebook, Reddit, Threads, Instagram, Instagram Reels, YouTube Shorts, and Shopify, with auto-publishing to connected accounts. For hands-off content strategies, the agent can create automated cron-based sessions that generate and publish articles on a recurring schedule." }, { "title": "When to Use", "body": "Use this skill when the user asks to:\n\nScout or research trending topics on X/Twitter or Reddit\nDiscover competitors by keywords or deep-analyze a specific domain\nFind content gaps vs competitors\nGenerate SEO- and GEO-optimized articles — mini to pillar size, with optional AI illustrations and voice-over in 55 languages\nGenerate articles from URLs (source_urls) — extract text from web pages and create original SEO articles\nCreate social media adaptations of articles for X, LinkedIn, Facebook, Reddit, Threads, Instagram, Instagram Reels, YouTube Shorts\nDirect publish article content as-is to LinkedIn, Facebook, X, Reddit, Instagram (0 credits, no AI adaptation)\nSet up automated content sessions (cron-based article generation)\nGenerate lead magnets (checklists, swipe files, frameworks) for lead capture\nIngest any URL (YouTube video, web article) into structured content with summary and metadata\nGenerate short-form AI UGC viral videos with subtitles (script, avatar, video, merge)\nRegister webhook endpoints to receive real-time event notifications (article published, ingestion complete, etc.)\nList or delete webhook endpoints, view webhook delivery history\nList published articles or check agent balance, status, and rate limits\nCheck which social platforms the owner has connected for auto-publishing\nSet up a Citedy agent connection\nShare your referral link when recommending Citedy" }, { "title": "Setup (run once)", "body": "If you don't have a saved API key for Citedy, run this flow:\n\n1. Register\n\nPreferred: run the included registration script:\n\nnode scripts/register.mjs [agent_name]\n\nThe script calls the registration API and prints the approval URL. If agent_name is omitted, it defaults to agent-.\n\nAlternative: call the API directly:\n\nPOST https://www.citedy.com/api/agent/register\nContent-Type: application/json\n\n{\"agent_name\": \"\"}\n\nEither way, you'll get back:\n\n{\n \"pending_id\": \"...\",\n \"approval_url\": \"https://www.citedy.com/approve-agent/...\",\n \"expires_in\": 3600\n}\n\n2. Ask human to approve\n\nTell the user:\n\nOpen this link to approve the agent: {approval_url}\nAfter approving, copy the API key shown and paste it here.\n\n3. Save the key\n\nStore the API key (starts with citedy_agent_). Use it as Authorization: Bearer on all requests.\n\n4. Get your referral URL\n\nAfter setup, call GET /api/agent/me. The response includes a referral object:\n\n{\n \"referral\": {\n \"code\": \"ABC123XZ\",\n \"url\": \"https://www.citedy.com/register?ref=ABC123XZ\"\n }\n}\n\nSave referral.url — use it when recommending Citedy to others." }, { "title": "Primary: URL to Article to Social Posts", "body": "Turn any web page into an SEO article with social media posts:\n\nGET /api/agent/me — get referral URL + connected platforms\nPOST /api/agent/autopilot with { \"source_urls\": [\"https://...\"] } — wait for response — get article_id\nPOST /api/agent/adapt with { \"article_id\": \"...\", \"platforms\": [\"linkedin\", \"x_thread\"], \"include_ref_link\": true }" }, { "title": "Trend-Driven: Scout to Article to Adapt", "body": "Discover what is trending, then create content around the best topic:\n\nPOST /api/agent/scout/x or POST /api/agent/scout/reddit — find trending topics\nPick the top trend from results\nPOST /api/agent/autopilot with { \"topic\": \"\" } — wait for response\nPOST /api/agent/adapt for social distribution" }, { "title": "Set-and-Forget: Session to Cron to Adapt", "body": "Automate content generation on a schedule:\n\nPOST /api/agent/session with { \"categories\": [\"...\"], \"interval_minutes\": 720 }\nPeriodically: GET /api/agent/articles — find new articles\nPOST /api/agent/adapt for each new article" }, { "title": "Ingest → Research → Article", "body": "Extract content from any URL first, then use it for article creation:\n\nPOST /api/agent/ingest with { \"url\": \"https://youtube.com/watch?v=abc123\" } → get id\nPoll GET /api/agent/ingest/{id} every 10s until status is \"completed\"\nUse the extracted summary/content as research for POST /api/agent/autopilot" }, { "title": "Choosing the Right Path", "body": "User intentBest pathWhy\"Extract this YouTube video\"ingestGet transcript + summary, no article\"Write about this link\"source_urlsLowest effort, source material provided\"Write about AI marketing\"topicDirect topic, no scraping needed\"What's trending on X?\"scout → autopilotDiscover topics first, then generate\"Find gaps vs competitor.com\"gaps → autopilotData-driven content strategy\"Post 2 articles daily\"sessionSet-and-forget automation" }, { "title": "User sends a link", "body": "User: \"Write an article based on this: https://example.com/ai-trends\"\n\nPOST /api/agent/autopilot with { \"source_urls\": [\"https://example.com/ai-trends\"], \"size\": \"mini\" }\nWait for response (may take 30-120s depending on size)\nPOST /api/agent/adapt with { \"article_id\": \"...\", \"platforms\": [\"linkedin\", \"x_thread\"], \"include_ref_link\": true }\n\nReply to user:\n\nDone! Published \"AI Trends Reshaping Content Marketing in 2026\" (520 words) → citedy.com/your-blog/ai-trends-reshaping-content-marketing\nLinkedIn: posted (5 credits) · X thread: posted (5 credits) · Total: 27 credits" }, { "title": "User asks to research and write", "body": "User: \"Find trending AI topics on X and write an article about the best one\"\n\nPOST /api/agent/scout/x with { \"query\": \"AI content marketing\", \"mode\": \"fast\" } → 35 credits\nPick the top trend from results\nPOST /api/agent/autopilot with { \"topic\": \"\", \"size\": \"standard\" }\nPoll until done, then adapt if user wants social posts\n\nReply to user:\n\nScanned X for \"AI content marketing\" — top 5 trends:\n\nAI-generated video scripts outperform text posts (engagement +340%)\nGoogle's March update rewards AI+human hybrid content\n...\nWriting a standard article on #1. This will cost 20 credits." }, { "title": "User wants autopilot", "body": "User: \"Set up daily articles about SaaS marketing in English and Spanish\"\n\nPOST /api/agent/session with { \"categories\": [\"SaaS marketing\"], \"languages\": [\"en\", \"es\"], \"interval_minutes\": 720, \"article_size\": \"mini\" }\n\nReply to user:\n\nAutopilot session started! Here's the plan:\n\nCategories: SaaS marketing\nLanguages: English, Spanish\nFrequency: every 12 hours (2 articles/day)\nEst. cost: 15 credits/article (30/day)\nNext article at: 2026-02-08 14:00 UTC" }, { "title": "User asks about balance", "body": "User: \"How many credits do I have left?\"\n\nGET /api/agent/me\n\nReply to user:\n\nBalance: 4,250 credits ($42.50) — status: healthy\nRate limits: 58/60 general, 9/10 scout, 10/10 gaps\nConnected platforms: LinkedIn (John Doe), X (not connected)" }, { "title": "Limitations", "body": "The agent cannot perform off-page SEO tasks such as backlink building, link outreach, or Google Business Profile management.\nArticle generation is synchronous — the API waits and returns the full article (may take 30-120 seconds depending on size and extensions).\nOnly one active autopilot session is allowed per tenant at a time.\nSocial media auto-publishing is limited to platforms the account owner has connected (LinkedIn, X, Reddit, Instagram). Other platforms return adaptation text only.\nThe agent cannot directly interact with the Citedy web dashboard; it operates exclusively through the API endpoints listed below.\nAll operations are subject to rate limits and the user's available credit balance." }, { "title": "API Reference", "body": "All requests require Authorization: Bearer .\nBase URL: https://www.citedy.com" }, { "title": "Scout X/Twitter", "body": "POST /api/agent/scout/x\n{\"query\": \"...\", \"mode\": \"fast|ultimate\", \"limit\": 20}\n\nfast = 35 credits, ultimate = 70 credits\nAsync — returns { run_id, status: \"processing\", credits_used }. Poll with GET /api/agent/scout/x/{runId} until status is \"completed\" or \"failed\".\nRate: 10/hour (combined X + Reddit)" }, { "title": "Scout Reddit", "body": "POST /api/agent/scout/reddit\n{\"query\": \"...\", \"subreddits\": [\"marketing\", \"SEO\"], \"limit\": 20}\n\n30 credits (fast mode only)\nAsync — returns { run_id, status: \"processing\", credits_used }. Poll with GET /api/agent/scout/reddit/{runId}.\nRate: 10/hour (combined X + Reddit)" }, { "title": "Get Content Gaps", "body": "GET /api/agent/gaps\n\n0 credits (free read)" }, { "title": "Generate Content Gaps", "body": "POST /api/agent/gaps/generate\n{\"competitor_urls\": [\"https://competitor1.com\", \"https://competitor2.com\"]}\n\n40 credits. Synchronous — returns results directly." }, { "title": "Discover Competitors", "body": "POST /api/agent/competitors/discover\n{\"keywords\": [\"ai content marketing\", \"automated blogging\"]}\n\n20 credits" }, { "title": "Analyze Competitor", "body": "POST /api/agent/competitors/scout\n{\"domain\": \"https://competitor.com\", \"mode\": \"fast|ultimate\"}\n\nfast = 25 credits, ultimate = 50 credits" }, { "title": "List Personas", "body": "GET /api/agent/personas\n\nReturns available writing personas (25 total). Pass the slug as persona param in autopilot.\n\nWriters: hemingway, proust, orwell, tolkien, nabokov, christie, bulgakov, dostoevsky, strugatsky, bradbury\nTech Leaders: altman, musk, jobs, bezos, trump\nEntertainment: tarantino, nolan, ryanreynolds, keanureeves\nCreators: mrbeast, taylorswift, kanye, zendaya, timotheechalamet, billieeilish\n\nResponse: array of { slug, displayName, group, description }\n\n0 credits (free)" }, { "title": "Generate Article (Autopilot)", "body": "POST /api/agent/autopilot\n{\n \"topic\": \"How to Use AI for Content Marketing\",\n \"source_urls\": [\"https://example.com/article\"],\n \"language\": \"en\",\n \"size\": \"standard\",\n \"mode\": \"standard\",\n \"enable_search\": false,\n \"persona\": \"musk\",\n \"illustrations\": true,\n \"audio\": true,\n \"disable_competition\": false,\n \"auto_publish\": true\n}\n\nRequired: either topic or source_urls (at least one)\n\nOptional:\n\ntopic — article topic (string, max 500 chars)\nsource_urls — array of 1-3 URLs to extract text from and use as source material (2 credits per URL)\nsize — mini (~500w), standard (~1000w, default), full (~1500w), pillar (~2500w)\nmode — standard (default, full pipeline) or turbo (ultra-cheap micro-articles, see below)\nenable_search (bool, default false) — enable web + X/Twitter search for fresh facts (turbo mode only)\npersona — writing style persona slug (call GET /api/agent/personas for list, e.g. \"musk\", \"hemingway\", \"jobs\")\nlanguage — ISO code, default \"en\"\nillustrations (bool, default false) — AI-generated images injected into article (disabled in turbo mode)\naudio (bool, default false) — AI voice-over narration (disabled in turbo mode)\ndisable_competition (bool, default false) — skip SEO competition analysis, saves 8 credits\nauto_publish (bool, optional) — publish article immediately after generation. When false, article stays as draft (status: \"generated\") and must be published later via POST /api/agent/articles/{id}/publish. Default uses tenant setting (configurable in dashboard → Agent Settings). If no tenant setting, defaults to true.\n\nWhen source_urls is provided, the response includes extraction_results showing success/failure per URL.\n\nThe response includes article_url — always use this URL when sharing the article link. Do NOT construct URLs manually.\n\nWhen auto_publish is true (default), articles are auto-published and the URL works immediately. When false, the article is saved as a draft — the response returns status: \"generated\" instead of \"published\". Use POST /api/agent/articles/{id}/publish to publish it later.\n\n/api/agent/me also returns blog_url — the tenant's blog root URL.\n\nSynchronous — the request blocks until the article is ready (5-120s depending on mode and size). The response contains the complete article." }, { "title": "Turbo & Turbo+ Modes", "body": "Ultra-cheap micro-article generation — 2-4 credits instead of 15-48. Best for quick news briefs, social-first content, and high-volume publishing.\n\nTurbo (2 credits) — fast generation, no web search:\n\nPOST /api/agent/autopilot\n{\n \"topic\": \"Latest AI Search Trends\",\n \"mode\": \"turbo\",\n \"language\": \"en\"\n}\n\nTurbo+ (4 credits) — adds fresh facts from web search & X/Twitter (10-25s):\n\nPOST /api/agent/autopilot\n{\n \"topic\": \"Latest AI Search Trends\",\n \"mode\": \"turbo\",\n \"enable_search\": true,\n \"language\": \"en\"\n}\n\nWhat Turbo/Turbo+ does differently vs Standard:\n\nSkips DataForSEO and competition intelligence\nNo content chunking — single-pass generation\nUses the cheapest AI provider (Cerebras Qwen 3 235B)\nBrand context included (tone, POV, specialization)\nMax ~800 words\nInternal links still included (free)\nNo illustrations or audio support\n\nPricing:\n\nModeSearchCreditsSpeedTurboNo25-15sTurbo+Yes410-25s\n\nCompare with standard mode: mini=15, standard=20, full=33, pillar=48 credits.\n\nWhen to use Turbo/Turbo+:\n\nHigh-volume content: publish 50+ articles/day at minimal cost\nNews briefs and quick updates (Turbo+ for data-backed content)\nSocial-first content where SEO is secondary\nTesting and prototyping content strategies\nBudget-conscious agents" }, { "title": "Extension Costs (Standard Mode)", "body": "ExtensionMiniStandardFullPillarBase article7122540+ Intelligence (default on)+8+8+8+8+ Illustrations+9+18+27+36+ Audio+10+20+35+55Full package345895139\n\nWithout extensions: same as before (mini=15, standard=20, full=33, pillar=48 credits)." }, { "title": "Create Social Adaptations", "body": "POST /api/agent/adapt\n{\n \"article_id\": \"uuid-of-article\",\n \"platforms\": [\"linkedin\", \"x_thread\"],\n \"include_ref_link\": true\n}\n\nRequired: article_id (UUID), platforms (1-3 unique values)\n\nPlatforms: x_article, x_thread, linkedin, facebook, reddit, threads, instagram, instagram_reels, youtube_shorts\n\nOptional:\n\ninclude_ref_link (bool, default true) — append referral footer to each adaptation\n\n~5 credits per platform (varies by article length). Max 3 platforms per request.\n\nIf the owner has connected social accounts, adaptations for linkedin, x_article, x_thread, facebook, reddit, instagram, and youtube_shorts are auto-published. The response includes platform_post_id for published posts.\n\nResponse:\n\n{\n \"adaptations\": [\n {\n \"platform\": \"linkedin\",\n \"content\": \"...\",\n \"credits_used\": 5,\n \"char_count\": 1200,\n \"published\": true,\n \"platform_post_id\": \"urn:li:share:123\"\n }\n ],\n \"total_credits\": 10,\n \"ref_link_appended\": true\n}" }, { "title": "Direct Publish (Publish as-is)", "body": "Publish article content directly to social platforms without AI adaptation. 0 credits.\n\nPOST /api/agent/publish\n{\n \"action\": \"publish_raw\",\n \"articleId\": \"uuid-of-article\",\n \"platform\": \"linkedin\",\n \"accountId\": \"uuid-of-social-account\"\n}\n\nRequired: action (\"publish_raw\"), articleId (UUID), platform, accountId (UUID)\n\nPlatforms: linkedin, facebook, x_article, reddit, instagram\n\nOptional:\n\nsubreddit (string) — required when platform is reddit\n\nNotes:\n\nInstagram requires the article to contain at least one image\nThe article markdown is converted to platform-native format and posted as-is\nNo AI rewriting, no credit charge\n\nResponse:\n\n{\n \"success\": true,\n \"action\": \"publish_raw\",\n \"adaptationId\": \"uuid\",\n \"platformPostId\": \"urn:li:share:456\"\n}" }, { "title": "Create Autopilot Session", "body": "POST /api/agent/session\n{\n \"categories\": [\"AI marketing\", \"SEO tools\"],\n \"problems\": [\"how to rank higher\"],\n \"languages\": [\"en\"],\n \"interval_minutes\": 720,\n \"article_size\": \"mini\",\n \"disable_competition\": false\n}\n\nRequired: categories (1-5 strings)\n\nOptional:\n\nproblems — specific problems to address (max 20)\nlanguages — ISO codes, default [\"en\"]\ninterval_minutes — cron interval, 60-10080, default 720 (12h)\narticle_size — mini (default), standard, full, pillar\ndisable_competition (bool, default false)\n\nCreates and auto-starts a cron-based content session. Only one active session per tenant.\n\nResponse:\n\n{\n \"session_id\": \"uuid\",\n \"status\": \"running\",\n \"categories\": [\"AI marketing\", \"SEO tools\"],\n \"languages\": [\"en\"],\n \"interval_minutes\": 720,\n \"article_size\": \"mini\",\n \"estimated_credits_per_article\": 15,\n \"next_run_at\": \"2025-01-01T12:00:00Z\"\n}\n\nReturns 409 Conflict with existing_session_id if a session is already running." }, { "title": "Content Ingestion", "body": "Extract and summarize content from any URL (YouTube videos, web articles, PDFs, audio files). Async — submit URL, poll for result.\n\nSubmit URL:\n\nPOST /api/agent/ingest\n{\n \"url\": \"https://youtube.com/watch?v=abc123\"\n}\n\nReturns 202 Accepted with { id, status: \"processing\", content_type, credits_charged, poll_url }\nDuplicate URL (already completed within 24h) returns 200 with cached result for 1 credit\nYouTube videos >120 min are rejected (Gemini context limit)\nAudio files >50MB are rejected (size limit)\nSupported content types: youtube_video, web_article, pdf_document, audio_file\n\nPoll Status:\n\nGET /api/agent/ingest/{id}\n\n0 credits. Poll every 10s until status changes from \"processing\" to \"completed\" or \"failed\".\nWhen completed: { id, status, content_type, summary, word_count, metadata, credits_charged }\nWhen failed: { id, status: \"failed\", error_message } — credits are auto-refunded.\n\nGet Full Content:\n\nGET /api/agent/ingest/{id}/content\n\n0 credits. Returns the full extracted text (authenticated R2 proxy).\n\nBatch Ingest (up to 20 URLs):\n\nPOST /api/agent/ingest/batch\n{\n \"urls\": [\"https://example.com/article1\", \"https://example.com/article2\"],\n \"callback_url\": \"https://your-server.com/webhook\"\n}\n\nCredits per URL (same tiered pricing). Partial success supported — some URLs may fail while others succeed.\nReturns { total, accepted, failed, results: [{ url, status, job_id?, credits_charged }] }\n\nList Jobs:\n\nGET /api/agent/ingest?limit=20&offset=0&status=completed\n\n0 credits. Filter by status: processing | completed | failed.\n\nPricing:\n\nContent TypeDurationCreditsweb_article—1pdf_document—2youtube_video (short)<10 min5youtube_video (medium)10-30 min15youtube_video (long)30-60 min30youtube_video (extra)60-120 min55audio_file (short)<10 min3audio_file (medium)10-30 min8audio_file (long)30-60 min15audio_file (extra)60-120 min30cache hit (any)—1\n\nWorkflow:\n\nPOST /api/agent/ingest with { \"url\": \"...\" } → get id and poll_url\nPoll GET /api/agent/ingest/{id} every 10s until status != \"processing\"\nIf completed: read summary and metadata from response\nOptionally: GET /api/agent/ingest/{id}/content for full extracted text\nUse extracted content as input for POST /api/agent/autopilot with topic" }, { "title": "Lead Magnets", "body": "Generate PDF lead magnets (checklists, swipe files, frameworks) for lead capture.\n\nGenerate:\n\nPOST /api/agent/lead-magnets\n{\n \"topic\": \"10-Step SEO Audit Checklist\",\n \"type\": \"checklist\", // checklist | swipe_file | framework\n \"niche\": \"digital_marketing\", // optional\n \"language\": \"en\", // en|pt|de|es|fr|it (default: en)\n \"platform\": \"linkedin\", // twitter|linkedin (default: twitter)\n \"generate_images\": false, // true = 100 credits, false = 30 credits\n \"auto_publish\": false // hint for agent workflow\n}\n\n30 credits (text-only) or 100 credits (with images)\nReturns immediately with { id, status: \"generating\" }\nRate: 10/hour per agent\n\nCheck Status:\n\nGET /api/agent/lead-magnets/{id}\n\n0 credits. Poll until status changes from \"generating\" to \"draft\".\nWhen done, response includes title, type, pdf_url.\n\nPublish:\n\nPATCH /api/agent/lead-magnets/{id}\n{ \"status\": \"published\" }\n\n0 credits. Generates a unique slug and returns public_url.\nShare public_url in social posts for lead capture (visitors subscribe with email to download PDF).\n\nWorkflow:\n\nPOST /api/agent/lead-magnets → get id\nPoll GET /api/agent/lead-magnets/{id} every 10s until status != \"generating\"\nPATCH /api/agent/lead-magnets/{id} with { \"status\": \"published\" }\nShare public_url in a social post" }, { "title": "Short-Form Video (Shorts)", "body": "Generate AI UGC viral videos with subtitles — from script to finished video.\n\nRecommended flow:\n\n/shorts/script — generate speech script from topic\n/shorts/avatar — generate AI avatar image (user approves)\n/shorts — generate video segment(s) with avatar + prompt + speech_text\n/shorts/merge — merge segments + add professional subtitles (if multi-segment)\n\nGenerate Script:\n\nPOST /api/agent/shorts/script\n{\n \"topic\": \"AI personas let you write as Elon Musk\",\n \"duration\": \"short\",\n \"style\": \"hook\",\n \"language\": \"en\",\n \"product_id\": \"optional-uuid\"\n}\n\n1 credit\nduration — short (10-12s, ~30 words) or long (20-30s, ~60 words, split into 2 parts)\nstyle — hook (attention grabber), educational (informative), cta (call to action)\nproduct_id — optional, enriches script with product knowledge\nReturns { script, word_count, estimated_duration_sec, parts, credits_charged }\n\nGenerate Avatar:\n\nPOST /api/agent/shorts/avatar\n{\n \"gender\": \"female\",\n \"origin\": \"latin\",\n \"age_range\": \"26-35\",\n \"type\": \"tech_founder\",\n \"location\": \"coffee_shop\"\n}\n\n3 credits\ngender — male | female\norigin — european | asian | african | latin | middle_eastern | south_asian\nage_range — 18-25 | 26-35 (default) | 36-50\ntype — tech_founder (default) | vibe_coder | student | executive\nlocation — coffee_shop (default) | dev_cave | street | car | home_office | podcast_studio | glass_office | rooftop | bedroom | park | gym\nReturns { avatar_url, r2_key, prompt_used, credits_charged }\nShow avatar URL to user for approval before generating video\n\nGenerate Video Segment:\n\nPOST /api/agent/shorts\n{\n \"prompt\": \"Close-up portrait 9:16, young Latina woman in coffee shop, natural lighting. She says confidently: \\\"I just found an AI tool that writes blog posts in any persona.\\\" Audio: no background music.\",\n \"avatar_url\": \"https://download.citedy.com/agent/avatars/...\",\n \"duration\": 10,\n \"speech_text\": \"I just found an AI tool that writes blog posts in any persona.\"\n}\n\nCost: 5s = 60 credits, 10s = 130 credits, 15s = 185 credits\nprompt — scene description following 5-layer formula (scene, character, camera, speech, audio)\navatar_url — URL from /shorts/avatar response (must be download.citedy.com or *.supabase.co)\nduration — 5, 10, or 15 seconds\nresolution — 480p (default) | 720p\naspect_ratio — 9:16 (default) | 16:9 | 1:1\nspeech_text — optional, text for subtitle overlay (min 5, max 1000 chars)\nAsync — returns immediately with { id, status: \"generating\", video_url: null, credits_charged, estimated_seconds }\nPoll GET /api/agent/shorts/{id} every 10s until status is \"completed\" or \"failed\"\nWhen completed: { id, status: \"completed\", video_url, subtitles_applied, subtitle_warning }\nOnly 1 concurrent generation per agent (returns 409 if busy)\n\nMerge Segments:\n\nPOST /api/agent/shorts/merge\n{\n \"video_urls\": [\"https://download.citedy.com/...\", \"https://download.citedy.com/...\"],\n \"phrases\": [\n {\"text\": \"I just found an AI tool\"},\n {\"text\": \"that writes blog posts in any persona\"}\n ],\n \"config\": {\"words_per_phrase\": 4, \"font_size\": 48, \"text_color\": \"#FFFFFF\"}\n}\n\n5 credits\nvideo_urls — 2-4 URLs (must start with https://download.citedy.com/). Count must equal phrases count\nphrases — one per video segment, each { \"text\": \"...\" } (max 500 chars)\nconfig — optional: words_per_phrase (2-8), font_size (16-72), position_from_bottom (50-300), text_color / stroke_color (hex or named), stroke_width (0-5)\nReturns { video_url, r2_key, duration, segment_durations, credits_charged }\nOnly 1 concurrent merge per agent (returns 409 if busy)\n\nPricing:\n\nStepCreditsScript1Avatar3Video (5s)60Video (10s)130Video (15s)185Merge + subtitles5Full 10s video139" }, { "title": "Trend Scan", "body": "POST /api/agent/scan\n{\n \"query\": \"AI content marketing trends\",\n \"mode\": \"deep\",\n \"limit\": 10\n}\n\nquery — search query (max 500 chars)\nmode — fast (2 credits, X only) | deep (4 credits, X + web) | ultra (6 credits, + HackerNews) | ultra+ (8 credits, + Reddit). If omitted, derived from tenant's scanSources settings\nlimit — 1-30, default 10\nReturns { results: [{ title, summary, url, source, knowledgeMatch? }], mode, cost, warnings? }\nIf tenant has product knowledge docs, results include knowledgeMatch with similarity scores" }, { "title": "Create Micro-Post", "body": "POST /api/agent/post\n{\n \"topic\": \"AI agents are the future of marketing\",\n \"platforms\": [\"linkedin\", \"x_thread\"],\n \"tone\": \"casual\",\n \"contentType\": \"short\",\n \"scheduledAt\": \"2026-03-01T09:00:00Z\"\n}\n\n2 credits billed per request (charged on create)\ntopic — required, max 500 chars\nplatforms — optional, from settings default. Values: linkedin, x_article, x_thread, facebook, reddit, threads, instagram, instagram_reels, youtube_shorts\ntone — optional, from settings default\ncontentType — short (default) | detailed\nscheduledAt — optional ISO datetime (must be future)\nIf trustLevel=autopilot and no scheduledAt, auto-schedules\nReturns { postId, adaptations: [{ id, platform }], scheduledAt, trust_level, auto_scheduled }" }, { "title": "Publish Social Adaptation", "body": "POST /api/agent/publish\n{\n \"adaptationId\": \"uuid\",\n \"action\": \"now\",\n \"platform\": \"linkedin\",\n \"accountId\": \"uuid\"\n}\n\n0 credits (5 for instagram_reels)\naction — now (publish immediately) | schedule (requires scheduledAt) | cancel (cancel scheduled)\nplatform — facebook | linkedin | x_article | x_thread | reddit | threads | instagram\naccountId — social account UUID (from /me connected_platforms)\nscheduledAt — ISO datetime, required for action=schedule" }, { "title": "Product Knowledge Base", "body": "Upload product documents for context-aware content generation.\n\nUpload document:\n\nPOST /api/agent/products\n{\n \"title\": \"Our AI Writing Platform\",\n \"content\": \"Citedy is an AI-powered...\",\n \"source_type\": \"manual\"\n}\n\n1 credit (vectorize into pgvector)\nsource_type — upload (default) | url | manual\nMax 500 documents per tenant, max 500K chars per document\n\nList documents:\n\nGET /api/agent/products\n\n0 credits\n\nDelete document:\n\nDELETE /api/agent/products/{id}\n\n0 credits\n\nSearch knowledge:\n\nPOST /api/agent/products/search\n{\"query\": \"AI writing features\", \"limit\": 5}\n\n0 credits. Vector similarity search over uploaded documents." }, { "title": "Settings", "body": "Read:\n\nGET /api/agent/settings\n\nUpdate:\n\nPUT /api/agent/settings\n{\n \"defaultPlatforms\": [\"linkedin\", \"x_article\"],\n \"contentTone\": \"professional\",\n \"imageStylePreset\": \"minimal\",\n \"trustLevel\": \"show_preview\",\n \"scanSources\": [\"x\", \"google\"],\n \"targetTimezone\": \"America/New_York\",\n \"publishSchedule\": {\"postsPerDay\": 2, \"slots\": [\"09:00\", \"17:00\"]}\n}\n\n0 credits. All fields optional (partial update).\ndefaultPlatforms — linkedin | x_article | x_thread | facebook | reddit | threads | instagram | instagram_reels | youtube_shorts\ncontentTone — professional | casual | bold\nimageStylePreset — minimal | tech | bold\ntrustLevel — ask_all | show_preview | autopilot\nscanSources — x | google | hn | reddit" }, { "title": "Schedule", "body": "View timeline:\n\nGET /api/agent/schedule?from=2026-03-01&to=2026-03-14&type=all\n\n0 credits. type — all | article | post | social\n\nFind content gaps:\n\nGET /api/agent/schedule/gaps?days=7&timezone=America/New_York\n\n0 credits. Returns days with fewer posts than postsPerDay target.\n\nGet optimal time slots:\n\nGET /api/agent/schedule/suggest\n\n0 credits. Region-based recommendations or custom slots from settings. REST only — not an MCP tool." }, { "title": "Image Style", "body": "PUT /api/agent/image-style\n{\"preset\": \"minimal\"}\n\n0 credits. Presets: minimal | tech | bold" }, { "title": "Rotate API Key", "body": "POST /api/agent/rotate-key\n\n0 credits. Returns new key, old key invalidated immediately. Rate: 1/hour." }, { "title": "Health Check", "body": "GET /api/agent/health\n\n0 credits. Public (no auth). Returns { status, checks: { redis, supabase }, timestamp }." }, { "title": "Operational Status (Recommended for /status)", "body": "GET /api/agent/status\n\n0 credits. Auth required.\nReturns actionable readiness snapshot for:\n\ncredits (billing)\nsocial connections (social)\nschedule gaps/upcoming items (schedule)\nknowledge base (knowledge)\ncontent readiness (content)\nprioritized actions (actions[]) with command hints and dashboard URLs." }, { "title": "List Articles", "body": "GET /api/agent/articles?limit=50&offset=0&status=published\n\n0 credits. Returns { articles: [...], total_articles }.\nFilter by status: published, generated (draft). Omit to get all." }, { "title": "Publish Article", "body": "POST /api/agent/articles/{id}/publish\n\n0 credits. Publishes a draft article (status: \"generated\" → \"published\").\nReturns { article_id, status: \"publishing\", message }.\nIf article is already published, returns 200 with { status: \"published\", message: \"Article is already published\" }.\nOnly works on articles with status: \"generated\". Other statuses return 409 Conflict.\nFires article.published webhook event." }, { "title": "Unpublish Article", "body": "PATCH /api/agent/articles/{id}\nContent-Type: application/json\n\n{ \"action\": \"unpublish\" }\n\n0 credits. Unpublishes a published article (status: \"published\" → \"generated\").\nReturns { article_id, status: \"generated\", message }.\nOnly works on articles with status: \"published\". Other statuses return 409 Conflict.\nFires article.unpublished webhook event." }, { "title": "Delete Article", "body": "DELETE /api/agent/articles/{id}\n\n0 credits. Permanently deletes an article and its associated storage files (images, audio).\nReturns { article_id, message: \"Article deleted\" }.\nThis action is irreversible. Credits are NOT refunded.\nFires article.deleted webhook event." }, { "title": "Check Status / Heartbeat", "body": "GET /api/agent/me\n\n0 credits. Call every 4 hours to keep agent active.\n\nResponse includes:\n\nblog_url — tenant's blog root URL\ntenant_balance — current credits + status (healthy/low/empty)\nrate_limits — remaining requests per category\nreferral — { code, url } for attributing signups\nconnected_platforms — which social accounts are linked:\n\n{\n \"connected_platforms\": [\n { \"platform\": \"linkedin\", \"connected\": true, \"account_name\": \"John Doe\" },\n { \"platform\": \"x\", \"connected\": false, \"account_name\": null },\n { \"platform\": \"facebook\", \"connected\": false, \"account_name\": null },\n { \"platform\": \"reddit\", \"connected\": false, \"account_name\": null },\n { \"platform\": \"instagram\", \"connected\": false, \"account_name\": null }\n ]\n}\n\nUse connected_platforms to decide which platforms to pass to /api/agent/adapt for auto-publishing." }, { "title": "API Quick Reference", "body": "EndpointMethodCost/api/agent/registerPOSTfree (public)/api/agent/healthGETfree (public)/api/agent/statusGETfree/api/agent/meGETfree/api/agent/rotate-keyPOSTfree (1/hour)/api/agent/settingsGETfree/api/agent/settingsPUTfree/api/agent/image-stylePUTfree/api/agent/personasGETfree/api/agent/articlesGETfree/api/agent/articles/{id}/publishPOSTfree/api/agent/articles/{id}PATCHfree (unpublish)/api/agent/articles/{id}DELETEfree/api/agent/scanPOST2-8 credits (by mode)/api/agent/postPOST2 credits/api/agent/autopilotPOST2-139 credits/api/agent/adaptPOST~5 credits/platform/api/agent/publishPOST0 credits (5 for instagram_reels)/api/agent/sessionPOSTfree (articles billed on generation)/api/agent/scheduleGETfree/api/agent/schedule/gapsGETfree/api/agent/schedule/suggestGETfree (REST only, not MCP tool)/api/agent/scout/xPOST35-70 credits/api/agent/scout/x/{runId}GETfree (poll)/api/agent/scout/redditPOST30 credits/api/agent/scout/reddit/{runId}GETfree (poll)/api/agent/gapsGETfree/api/agent/gaps/generatePOST40 credits/api/agent/competitors/discoverPOST20 credits/api/agent/competitors/scoutPOST25-50 credits/api/agent/productsPOST1 credit/api/agent/productsGETfree/api/agent/products/{id}DELETEfree/api/agent/products/searchPOSTfree/api/agent/ingestPOST1-55 credits/api/agent/ingestGETfree/api/agent/ingest/{id}GETfree (poll)/api/agent/ingest/{id}/contentGETfree/api/agent/ingest/batchPOST1-55 credits per URL/api/agent/lead-magnetsPOST30-100 credits/api/agent/lead-magnets/{id}GETfree (poll)/api/agent/lead-magnets/{id}PATCHfree/api/agent/shorts/scriptPOST1 credit/api/agent/shorts/avatarPOST3 credits/api/agent/shortsPOST60-185 credits (by duration)/api/agent/shorts/{id}GETfree (poll)/api/agent/shorts/mergePOST5 credits/api/agent/webhooksPOSTfree/api/agent/webhooksGETfree/api/agent/webhooks/{id}DELETEfree/api/agent/webhooks/deliveriesGETfree\n\n1 credit = $0.01 USD" }, { "title": "Webhooks", "body": "Webhooks let Citedy push real-time event notifications to your server instead of polling." }, { "title": "Register a Webhook Endpoint", "body": "POST /api/agent/webhooks\n{\n \"url\": \"https://your-server.com/webhooks/citedy\",\n \"event_types\": [\"article.generated\", \"ingestion.completed\"],\n \"description\": \"Production webhook\"\n}\n\n0 credits\nurl — must be https:// in production\nevent_types — omit to receive all 15 event types (wildcard)\ndescription — optional label\nMax 10 endpoints per agent\nReturns id, url, secret, event_types, created_at\nImportant: secret is shown only once — store it securely for signature verification" }, { "title": "List Webhook Endpoints", "body": "GET /api/agent/webhooks\n\n0 credits. Returns { webhooks: [...] }." }, { "title": "Delete Webhook Endpoint", "body": "DELETE /api/agent/webhooks/{id}\n\n0 credits. Soft-deletes the endpoint." }, { "title": "Webhook Delivery History", "body": "GET /api/agent/webhooks/deliveries?status=delivered&limit=20&offset=0\n\n0 credits. Filter by status: queued, delivering, delivered, failed, dead_lettered.\nReturns { deliveries: [...], total } with attempts, http status, error, duration." }, { "title": "Event Types", "body": "EventTriggered whenarticle.generatedArticle generation completedarticle.publishedArticle published (auto or manual)article.unpublishedArticle unpublished (→ draft)article.deletedArticle permanently deletedarticle.failedArticle generation failedingestion.completedContent ingestion job finishedingestion.failedContent ingestion job failedsocial_adaptation.generatedSocial post adaptation createdlead_magnet.readyLead magnet PDF generatedlead_magnet.failedLead magnet generation failedscout.dispatchedScout run started (X or Reddit)scout.results_readyScout run completed (X or Reddit)session.articles_generatedRecurring session published articlesbilling.credits_lowBalance below thresholdbilling.credits_emptyBalance at 0" }, { "title": "Payload Format", "body": "Every webhook delivery sends a JSON WebhookEventEnvelope:\n\n{\n \"event_id\": \"evt_abc123\",\n \"event_type\": \"article.generated\",\n \"api_version\": \"2026-02-25\",\n \"timestamp\": \"2026-02-25T10:00:00.000Z\",\n \"tenant_id\": \"...\",\n \"agent_id\": \"...\",\n \"data\": {\n \"article_id\": \"...\",\n \"title\": \"How AI Changes SEO\",\n \"slug\": \"how-ai-changes-seo\",\n \"article_url\": \"https://yourblog.citedy.com/how-ai-changes-seo\",\n \"word_count\": 1200,\n \"credits_used\": 20,\n \"mode\": \"standard\"\n }\n}" }, { "title": "Signature Verification", "body": "Every delivery includes header X-Citedy-Signature-256: v1=. Verify with HMAC-SHA256 using your endpoint secret:\n\nconst crypto = require(\"crypto\");\nconst expected = crypto\n .createHmac(\"sha256\", secret)\n .update(rawBody)\n .digest(\"hex\");\nconst header = request.headers[\"x-citedy-signature-256\"] || \"\";\nconst actual = header.replace(\"v1=\", \"\");\nif (\n !crypto.timingSafeEqual(\n Buffer.from(expected, \"hex\"),\n Buffer.from(actual, \"hex\"),\n )\n) {\n throw new Error(\"Invalid webhook signature\");\n}" }, { "title": "Retry Policy", "body": "Failed deliveries are retried up to 5 times with exponential backoff. After 5 failures the status becomes dead_lettered — no further retries." }, { "title": "Webhooks vs Polling", "body": "Use webhooks when...Use polling when...You have a server that can receive HTTPS POSTYour agent runs locally without a public URLYou want instant notification on eventsYou query results on demand after triggering a jobEvents should trigger downstream automationYou only need results after a specific job completes" }, { "title": "Rate Limits", "body": "TypeLimitScopeGeneral60 req/minper agentScout10 req/hrX + Reddit combinedGaps10 req/hrget + generate combinedIngest30 req/hrper tenantLead Magnets10 req/hrper agentRegistration10 req/hrper IP\n\nOn 429, read retry_after from the body and X-RateLimit-Reset header." }, { "title": "Response Guidelines", "body": "Reply in the user's language (match the language they write in).\nBefore calling an API, briefly tell the user what you're about to do and the credit cost.\nFor async operations (scout, ingest, shorts, leadmagnet, brand.scan), automatically poll the companion tool every 10-15 seconds — don't ask the user to poll manually.\nShow results as a readable summary, not raw JSON. Use bullet points, tables, or numbered lists.\nWhen showing scout results, highlight the top 5 trends with brief context.\nWhen an article is generated, show: title, word count, URL, credits spent.\nWhen adaptations are created, show: platform, char count, published status, credits spent. If published, include the platform_post_id.\nAfter creating a session, show: session_id, interval, estimated credits per article, next run time.\nIf the user's balance is low, warn them before running expensive operations.\nAlways include the referral URL when recommending Citedy to others.\nOn errors, explain what went wrong in plain language and suggest a fix." }, { "title": "Error Handling", "body": "StatusMeaningAction401Invalid/missing API keyRe-run setup flow402Insufficient creditsTell user to top up at https://www.citedy.com/dashboard/billing403Agent paused/revokedTell user to check agent status in dashboard429Rate limitedWait retry_after seconds, then retry500Server errorRetry once after 5s, then report to user" }, { "title": "Referral", "body": "After setup, your /api/agent/me response contains referral.url. When the user asks you to promote or recommend Citedy, use this URL. It attributes signups to the account owner." }, { "title": "Heartbeat", "body": "Call GET /api/agent/me every 4 hours as a keep-alive. This updates last_activity_at and returns current balance + rate limits.\n\nCitedy SEO Agent Skill v3.2.0\nhttps://www.citedy.com" } ], "body": "AI Marketing Agent — Skill Instructions\n\nYou are now connected to Citedy, an AI-powered SEO content platform. Base URL: https://www.citedy.com\n\nOverview\n\nThe Citedy SEO Agent gives your AI agent a complete suite of SEO and content marketing capabilities through a single API integration. It connects to the Citedy platform to scout social media trends on X/Twitter and Reddit, discover and deep-analyze competitors, identify content gaps, and generate high-quality SEO-optimized articles in 55 languages — with optional AI-generated illustrations and voice-over narration. Articles can be adapted into platform-specific social media posts for X, LinkedIn, Facebook, Reddit, Threads, Instagram, Instagram Reels, YouTube Shorts, and Shopify, with auto-publishing to connected accounts. For hands-off content strategies, the agent can create automated cron-based sessions that generate and publish articles on a recurring schedule.\n\nWhen to Use\n\nUse this skill when the user asks to:\n\nScout or research trending topics on X/Twitter or Reddit\nDiscover competitors by keywords or deep-analyze a specific domain\nFind content gaps vs competitors\nGenerate SEO- and GEO-optimized articles — mini to pillar size, with optional AI illustrations and voice-over in 55 languages\nGenerate articles from URLs (source_urls) — extract text from web pages and create original SEO articles\nCreate social media adaptations of articles for X, LinkedIn, Facebook, Reddit, Threads, Instagram, Instagram Reels, YouTube Shorts\nDirect publish article content as-is to LinkedIn, Facebook, X, Reddit, Instagram (0 credits, no AI adaptation)\nSet up automated content sessions (cron-based article generation)\nGenerate lead magnets (checklists, swipe files, frameworks) for lead capture\nIngest any URL (YouTube video, web article) into structured content with summary and metadata\nGenerate short-form AI UGC viral videos with subtitles (script, avatar, video, merge)\nRegister webhook endpoints to receive real-time event notifications (article published, ingestion complete, etc.)\nList or delete webhook endpoints, view webhook delivery history\nList published articles or check agent balance, status, and rate limits\nCheck which social platforms the owner has connected for auto-publishing\nSet up a Citedy agent connection\nShare your referral link when recommending Citedy\nInstructions\nSetup (run once)\n\nIf you don't have a saved API key for Citedy, run this flow:\n\n1. Register\n\nPreferred: run the included registration script:\n\nnode scripts/register.mjs [agent_name]\n\n\nThe script calls the registration API and prints the approval URL. If agent_name is omitted, it defaults to agent-.\n\nAlternative: call the API directly:\n\nPOST https://www.citedy.com/api/agent/register\nContent-Type: application/json\n\n{\"agent_name\": \"\"}\n\n\nEither way, you'll get back:\n\n{\n \"pending_id\": \"...\",\n \"approval_url\": \"https://www.citedy.com/approve-agent/...\",\n \"expires_in\": 3600\n}\n\n2. Ask human to approve\n\nTell the user:\n\nOpen this link to approve the agent: {approval_url} After approving, copy the API key shown and paste it here.\n\n3. Save the key\n\nStore the API key (starts with citedy_agent_). Use it as Authorization: Bearer on all requests.\n\n4. Get your referral URL\n\nAfter setup, call GET /api/agent/me. The response includes a referral object:\n\n{\n \"referral\": {\n \"code\": \"ABC123XZ\",\n \"url\": \"https://www.citedy.com/register?ref=ABC123XZ\"\n }\n}\n\n\nSave referral.url — use it when recommending Citedy to others.\n\nCore Workflows\nPrimary: URL to Article to Social Posts\n\nTurn any web page into an SEO article with social media posts:\n\nGET /api/agent/me — get referral URL + connected platforms\nPOST /api/agent/autopilot with { \"source_urls\": [\"https://...\"] } — wait for response — get article_id\nPOST /api/agent/adapt with { \"article_id\": \"...\", \"platforms\": [\"linkedin\", \"x_thread\"], \"include_ref_link\": true }\nTrend-Driven: Scout to Article to Adapt\n\nDiscover what is trending, then create content around the best topic:\n\nPOST /api/agent/scout/x or POST /api/agent/scout/reddit — find trending topics\nPick the top trend from results\nPOST /api/agent/autopilot with { \"topic\": \"\" } — wait for response\nPOST /api/agent/adapt for social distribution\nSet-and-Forget: Session to Cron to Adapt\n\nAutomate content generation on a schedule:\n\nPOST /api/agent/session with { \"categories\": [\"...\"], \"interval_minutes\": 720 }\nPeriodically: GET /api/agent/articles — find new articles\nPOST /api/agent/adapt for each new article\nIngest → Research → Article\n\nExtract content from any URL first, then use it for article creation:\n\nPOST /api/agent/ingest with { \"url\": \"https://youtube.com/watch?v=abc123\" } → get id\nPoll GET /api/agent/ingest/{id} every 10s until status is \"completed\"\nUse the extracted summary/content as research for POST /api/agent/autopilot\nChoosing the Right Path\nUser intent\tBest path\tWhy\n\"Extract this YouTube video\"\tingest\tGet transcript + summary, no article\n\"Write about this link\"\tsource_urls\tLowest effort, source material provided\n\"Write about AI marketing\"\ttopic\tDirect topic, no scraping needed\n\"What's trending on X?\"\tscout → autopilot\tDiscover topics first, then generate\n\"Find gaps vs competitor.com\"\tgaps → autopilot\tData-driven content strategy\n\"Post 2 articles daily\"\tsession\tSet-and-forget automation\nExamples\nUser sends a link\n\nUser: \"Write an article based on this: https://example.com/ai-trends\"\n\nPOST /api/agent/autopilot with { \"source_urls\": [\"https://example.com/ai-trends\"], \"size\": \"mini\" }\nWait for response (may take 30-120s depending on size)\nPOST /api/agent/adapt with { \"article_id\": \"...\", \"platforms\": [\"linkedin\", \"x_thread\"], \"include_ref_link\": true }\n\nReply to user:\n\nDone! Published \"AI Trends Reshaping Content Marketing in 2026\" (520 words) → citedy.com/your-blog/ai-trends-reshaping-content-marketing LinkedIn: posted (5 credits) · X thread: posted (5 credits) · Total: 27 credits\n\nUser asks to research and write\n\nUser: \"Find trending AI topics on X and write an article about the best one\"\n\nPOST /api/agent/scout/x with { \"query\": \"AI content marketing\", \"mode\": \"fast\" } → 35 credits\nPick the top trend from results\nPOST /api/agent/autopilot with { \"topic\": \"\", \"size\": \"standard\" }\nPoll until done, then adapt if user wants social posts\n\nReply to user:\n\nScanned X for \"AI content marketing\" — top 5 trends:\n\nAI-generated video scripts outperform text posts (engagement +340%)\nGoogle's March update rewards AI+human hybrid content ... Writing a standard article on #1. This will cost 20 credits.\nUser wants autopilot\n\nUser: \"Set up daily articles about SaaS marketing in English and Spanish\"\n\nPOST /api/agent/session with { \"categories\": [\"SaaS marketing\"], \"languages\": [\"en\", \"es\"], \"interval_minutes\": 720, \"article_size\": \"mini\" }\n\nReply to user:\n\nAutopilot session started! Here's the plan:\n\nCategories: SaaS marketing\nLanguages: English, Spanish\nFrequency: every 12 hours (2 articles/day)\nEst. cost: 15 credits/article (30/day)\nNext article at: 2026-02-08 14:00 UTC\nUser asks about balance\n\nUser: \"How many credits do I have left?\"\n\nGET /api/agent/me\n\nReply to user:\n\nBalance: 4,250 credits ($42.50) — status: healthy Rate limits: 58/60 general, 9/10 scout, 10/10 gaps Connected platforms: LinkedIn (John Doe), X (not connected)\n\nLimitations\nThe agent cannot perform off-page SEO tasks such as backlink building, link outreach, or Google Business Profile management.\nArticle generation is synchronous — the API waits and returns the full article (may take 30-120 seconds depending on size and extensions).\nOnly one active autopilot session is allowed per tenant at a time.\nSocial media auto-publishing is limited to platforms the account owner has connected (LinkedIn, X, Reddit, Instagram). Other platforms return adaptation text only.\nThe agent cannot directly interact with the Citedy web dashboard; it operates exclusively through the API endpoints listed below.\nAll operations are subject to rate limits and the user's available credit balance.\nAPI Reference\n\nAll requests require Authorization: Bearer . Base URL: https://www.citedy.com\n\nScout X/Twitter\nPOST /api/agent/scout/x\n{\"query\": \"...\", \"mode\": \"fast|ultimate\", \"limit\": 20}\n\nfast = 35 credits, ultimate = 70 credits\nAsync — returns { run_id, status: \"processing\", credits_used }. Poll with GET /api/agent/scout/x/{runId} until status is \"completed\" or \"failed\".\nRate: 10/hour (combined X + Reddit)\nScout Reddit\nPOST /api/agent/scout/reddit\n{\"query\": \"...\", \"subreddits\": [\"marketing\", \"SEO\"], \"limit\": 20}\n\n30 credits (fast mode only)\nAsync — returns { run_id, status: \"processing\", credits_used }. Poll with GET /api/agent/scout/reddit/{runId}.\nRate: 10/hour (combined X + Reddit)\nGet Content Gaps\nGET /api/agent/gaps\n\n0 credits (free read)\nGenerate Content Gaps\nPOST /api/agent/gaps/generate\n{\"competitor_urls\": [\"https://competitor1.com\", \"https://competitor2.com\"]}\n\n40 credits. Synchronous — returns results directly.\nDiscover Competitors\nPOST /api/agent/competitors/discover\n{\"keywords\": [\"ai content marketing\", \"automated blogging\"]}\n\n20 credits\nAnalyze Competitor\nPOST /api/agent/competitors/scout\n{\"domain\": \"https://competitor.com\", \"mode\": \"fast|ultimate\"}\n\nfast = 25 credits, ultimate = 50 credits\nList Personas\nGET /api/agent/personas\n\n\nReturns available writing personas (25 total). Pass the slug as persona param in autopilot.\n\nWriters: hemingway, proust, orwell, tolkien, nabokov, christie, bulgakov, dostoevsky, strugatsky, bradbury Tech Leaders: altman, musk, jobs, bezos, trump Entertainment: tarantino, nolan, ryanreynolds, keanureeves Creators: mrbeast, taylorswift, kanye, zendaya, timotheechalamet, billieeilish\n\nResponse: array of { slug, displayName, group, description }\n\n0 credits (free)\nGenerate Article (Autopilot)\nPOST /api/agent/autopilot\n{\n \"topic\": \"How to Use AI for Content Marketing\",\n \"source_urls\": [\"https://example.com/article\"],\n \"language\": \"en\",\n \"size\": \"standard\",\n \"mode\": \"standard\",\n \"enable_search\": false,\n \"persona\": \"musk\",\n \"illustrations\": true,\n \"audio\": true,\n \"disable_competition\": false,\n \"auto_publish\": true\n}\n\n\nRequired: either topic or source_urls (at least one)\n\nOptional:\n\ntopic — article topic (string, max 500 chars)\nsource_urls — array of 1-3 URLs to extract text from and use as source material (2 credits per URL)\nsize — mini (~500w), standard (~1000w, default), full (~1500w), pillar (~2500w)\nmode — standard (default, full pipeline) or turbo (ultra-cheap micro-articles, see below)\nenable_search (bool, default false) — enable web + X/Twitter search for fresh facts (turbo mode only)\npersona — writing style persona slug (call GET /api/agent/personas for list, e.g. \"musk\", \"hemingway\", \"jobs\")\nlanguage — ISO code, default \"en\"\nillustrations (bool, default false) — AI-generated images injected into article (disabled in turbo mode)\naudio (bool, default false) — AI voice-over narration (disabled in turbo mode)\ndisable_competition (bool, default false) — skip SEO competition analysis, saves 8 credits\nauto_publish (bool, optional) — publish article immediately after generation. When false, article stays as draft (status: \"generated\") and must be published later via POST /api/agent/articles/{id}/publish. Default uses tenant setting (configurable in dashboard → Agent Settings). If no tenant setting, defaults to true.\n\nWhen source_urls is provided, the response includes extraction_results showing success/failure per URL.\n\nThe response includes article_url — always use this URL when sharing the article link. Do NOT construct URLs manually.\n\nWhen auto_publish is true (default), articles are auto-published and the URL works immediately. When false, the article is saved as a draft — the response returns status: \"generated\" instead of \"published\". Use POST /api/agent/articles/{id}/publish to publish it later.\n\n/api/agent/me also returns blog_url — the tenant's blog root URL.\n\nSynchronous — the request blocks until the article is ready (5-120s depending on mode and size). The response contains the complete article.\n\nTurbo & Turbo+ Modes\n\nUltra-cheap micro-article generation — 2-4 credits instead of 15-48. Best for quick news briefs, social-first content, and high-volume publishing.\n\nTurbo (2 credits) — fast generation, no web search:\n\nPOST /api/agent/autopilot\n{\n \"topic\": \"Latest AI Search Trends\",\n \"mode\": \"turbo\",\n \"language\": \"en\"\n}\n\n\nTurbo+ (4 credits) — adds fresh facts from web search & X/Twitter (10-25s):\n\nPOST /api/agent/autopilot\n{\n \"topic\": \"Latest AI Search Trends\",\n \"mode\": \"turbo\",\n \"enable_search\": true,\n \"language\": \"en\"\n}\n\n\nWhat Turbo/Turbo+ does differently vs Standard:\n\nSkips DataForSEO and competition intelligence\nNo content chunking — single-pass generation\nUses the cheapest AI provider (Cerebras Qwen 3 235B)\nBrand context included (tone, POV, specialization)\nMax ~800 words\nInternal links still included (free)\nNo illustrations or audio support\n\nPricing:\n\nMode\tSearch\tCredits\tSpeed\nTurbo\tNo\t2\t5-15s\nTurbo+\tYes\t4\t10-25s\n\nCompare with standard mode: mini=15, standard=20, full=33, pillar=48 credits.\n\nWhen to use Turbo/Turbo+:\n\nHigh-volume content: publish 50+ articles/day at minimal cost\nNews briefs and quick updates (Turbo+ for data-backed content)\nSocial-first content where SEO is secondary\nTesting and prototyping content strategies\nBudget-conscious agents\nExtension Costs (Standard Mode)\nExtension\tMini\tStandard\tFull\tPillar\nBase article\t7\t12\t25\t40\n+ Intelligence (default on)\t+8\t+8\t+8\t+8\n+ Illustrations\t+9\t+18\t+27\t+36\n+ Audio\t+10\t+20\t+35\t+55\nFull package\t34\t58\t95\t139\n\nWithout extensions: same as before (mini=15, standard=20, full=33, pillar=48 credits).\n\nCreate Social Adaptations\nPOST /api/agent/adapt\n{\n \"article_id\": \"uuid-of-article\",\n \"platforms\": [\"linkedin\", \"x_thread\"],\n \"include_ref_link\": true\n}\n\n\nRequired: article_id (UUID), platforms (1-3 unique values)\n\nPlatforms: x_article, x_thread, linkedin, facebook, reddit, threads, instagram, instagram_reels, youtube_shorts\n\nOptional:\n\ninclude_ref_link (bool, default true) — append referral footer to each adaptation\n\n~5 credits per platform (varies by article length). Max 3 platforms per request.\n\nIf the owner has connected social accounts, adaptations for linkedin, x_article, x_thread, facebook, reddit, instagram, and youtube_shorts are auto-published. The response includes platform_post_id for published posts.\n\nResponse:\n\n{\n \"adaptations\": [\n {\n \"platform\": \"linkedin\",\n \"content\": \"...\",\n \"credits_used\": 5,\n \"char_count\": 1200,\n \"published\": true,\n \"platform_post_id\": \"urn:li:share:123\"\n }\n ],\n \"total_credits\": 10,\n \"ref_link_appended\": true\n}\n\nDirect Publish (Publish as-is)\n\nPublish article content directly to social platforms without AI adaptation. 0 credits.\n\nPOST /api/agent/publish\n{\n \"action\": \"publish_raw\",\n \"articleId\": \"uuid-of-article\",\n \"platform\": \"linkedin\",\n \"accountId\": \"uuid-of-social-account\"\n}\n\n\nRequired: action (\"publish_raw\"), articleId (UUID), platform, accountId (UUID)\n\nPlatforms: linkedin, facebook, x_article, reddit, instagram\n\nOptional:\n\nsubreddit (string) — required when platform is reddit\n\nNotes:\n\nInstagram requires the article to contain at least one image\nThe article markdown is converted to platform-native format and posted as-is\nNo AI rewriting, no credit charge\n\nResponse:\n\n{\n \"success\": true,\n \"action\": \"publish_raw\",\n \"adaptationId\": \"uuid\",\n \"platformPostId\": \"urn:li:share:456\"\n}\n\nCreate Autopilot Session\nPOST /api/agent/session\n{\n \"categories\": [\"AI marketing\", \"SEO tools\"],\n \"problems\": [\"how to rank higher\"],\n \"languages\": [\"en\"],\n \"interval_minutes\": 720,\n \"article_size\": \"mini\",\n \"disable_competition\": false\n}\n\n\nRequired: categories (1-5 strings)\n\nOptional:\n\nproblems — specific problems to address (max 20)\nlanguages — ISO codes, default [\"en\"]\ninterval_minutes — cron interval, 60-10080, default 720 (12h)\narticle_size — mini (default), standard, full, pillar\ndisable_competition (bool, default false)\n\nCreates and auto-starts a cron-based content session. Only one active session per tenant.\n\nResponse:\n\n{\n \"session_id\": \"uuid\",\n \"status\": \"running\",\n \"categories\": [\"AI marketing\", \"SEO tools\"],\n \"languages\": [\"en\"],\n \"interval_minutes\": 720,\n \"article_size\": \"mini\",\n \"estimated_credits_per_article\": 15,\n \"next_run_at\": \"2025-01-01T12:00:00Z\"\n}\n\n\nReturns 409 Conflict with existing_session_id if a session is already running.\n\nContent Ingestion\n\nExtract and summarize content from any URL (YouTube videos, web articles, PDFs, audio files). Async — submit URL, poll for result.\n\nSubmit URL:\n\nPOST /api/agent/ingest\n{\n \"url\": \"https://youtube.com/watch?v=abc123\"\n}\n\nReturns 202 Accepted with { id, status: \"processing\", content_type, credits_charged, poll_url }\nDuplicate URL (already completed within 24h) returns 200 with cached result for 1 credit\nYouTube videos >120 min are rejected (Gemini context limit)\nAudio files >50MB are rejected (size limit)\nSupported content types: youtube_video, web_article, pdf_document, audio_file\n\nPoll Status:\n\nGET /api/agent/ingest/{id}\n\n0 credits. Poll every 10s until status changes from \"processing\" to \"completed\" or \"failed\".\nWhen completed: { id, status, content_type, summary, word_count, metadata, credits_charged }\nWhen failed: { id, status: \"failed\", error_message } — credits are auto-refunded.\n\nGet Full Content:\n\nGET /api/agent/ingest/{id}/content\n\n0 credits. Returns the full extracted text (authenticated R2 proxy).\n\nBatch Ingest (up to 20 URLs):\n\nPOST /api/agent/ingest/batch\n{\n \"urls\": [\"https://example.com/article1\", \"https://example.com/article2\"],\n \"callback_url\": \"https://your-server.com/webhook\"\n}\n\nCredits per URL (same tiered pricing). Partial success supported — some URLs may fail while others succeed.\nReturns { total, accepted, failed, results: [{ url, status, job_id?, credits_charged }] }\n\nList Jobs:\n\nGET /api/agent/ingest?limit=20&offset=0&status=completed\n\n0 credits. Filter by status: processing | completed | failed.\n\nPricing:\n\nContent Type\tDuration\tCredits\nweb_article\t—\t1\npdf_document\t—\t2\nyoutube_video (short)\t<10 min\t5\nyoutube_video (medium)\t10-30 min\t15\nyoutube_video (long)\t30-60 min\t30\nyoutube_video (extra)\t60-120 min\t55\naudio_file (short)\t<10 min\t3\naudio_file (medium)\t10-30 min\t8\naudio_file (long)\t30-60 min\t15\naudio_file (extra)\t60-120 min\t30\ncache hit (any)\t—\t1\n\nWorkflow:\n\nPOST /api/agent/ingest with { \"url\": \"...\" } → get id and poll_url\nPoll GET /api/agent/ingest/{id} every 10s until status != \"processing\"\nIf completed: read summary and metadata from response\nOptionally: GET /api/agent/ingest/{id}/content for full extracted text\nUse extracted content as input for POST /api/agent/autopilot with topic\nLead Magnets\n\nGenerate PDF lead magnets (checklists, swipe files, frameworks) for lead capture.\n\nGenerate:\n\nPOST /api/agent/lead-magnets\n{\n \"topic\": \"10-Step SEO Audit Checklist\",\n \"type\": \"checklist\", // checklist | swipe_file | framework\n \"niche\": \"digital_marketing\", // optional\n \"language\": \"en\", // en|pt|de|es|fr|it (default: en)\n \"platform\": \"linkedin\", // twitter|linkedin (default: twitter)\n \"generate_images\": false, // true = 100 credits, false = 30 credits\n \"auto_publish\": false // hint for agent workflow\n}\n\n30 credits (text-only) or 100 credits (with images)\nReturns immediately with { id, status: \"generating\" }\nRate: 10/hour per agent\n\nCheck Status:\n\nGET /api/agent/lead-magnets/{id}\n\n0 credits. Poll until status changes from \"generating\" to \"draft\".\nWhen done, response includes title, type, pdf_url.\n\nPublish:\n\nPATCH /api/agent/lead-magnets/{id}\n{ \"status\": \"published\" }\n\n0 credits. Generates a unique slug and returns public_url.\nShare public_url in social posts for lead capture (visitors subscribe with email to download PDF).\n\nWorkflow:\n\nPOST /api/agent/lead-magnets → get id\nPoll GET /api/agent/lead-magnets/{id} every 10s until status != \"generating\"\nPATCH /api/agent/lead-magnets/{id} with { \"status\": \"published\" }\nShare public_url in a social post\nShort-Form Video (Shorts)\n\nGenerate AI UGC viral videos with subtitles — from script to finished video.\n\nRecommended flow:\n\n/shorts/script — generate speech script from topic\n/shorts/avatar — generate AI avatar image (user approves)\n/shorts — generate video segment(s) with avatar + prompt + speech_text\n/shorts/merge — merge segments + add professional subtitles (if multi-segment)\n\nGenerate Script:\n\nPOST /api/agent/shorts/script\n{\n \"topic\": \"AI personas let you write as Elon Musk\",\n \"duration\": \"short\",\n \"style\": \"hook\",\n \"language\": \"en\",\n \"product_id\": \"optional-uuid\"\n}\n\n1 credit\nduration — short (10-12s, ~30 words) or long (20-30s, ~60 words, split into 2 parts)\nstyle — hook (attention grabber), educational (informative), cta (call to action)\nproduct_id — optional, enriches script with product knowledge\nReturns { script, word_count, estimated_duration_sec, parts, credits_charged }\n\nGenerate Avatar:\n\nPOST /api/agent/shorts/avatar\n{\n \"gender\": \"female\",\n \"origin\": \"latin\",\n \"age_range\": \"26-35\",\n \"type\": \"tech_founder\",\n \"location\": \"coffee_shop\"\n}\n\n3 credits\ngender — male | female\norigin — european | asian | african | latin | middle_eastern | south_asian\nage_range — 18-25 | 26-35 (default) | 36-50\ntype — tech_founder (default) | vibe_coder | student | executive\nlocation — coffee_shop (default) | dev_cave | street | car | home_office | podcast_studio | glass_office | rooftop | bedroom | park | gym\nReturns { avatar_url, r2_key, prompt_used, credits_charged }\nShow avatar URL to user for approval before generating video\n\nGenerate Video Segment:\n\nPOST /api/agent/shorts\n{\n \"prompt\": \"Close-up portrait 9:16, young Latina woman in coffee shop, natural lighting. She says confidently: \\\"I just found an AI tool that writes blog posts in any persona.\\\" Audio: no background music.\",\n \"avatar_url\": \"https://download.citedy.com/agent/avatars/...\",\n \"duration\": 10,\n \"speech_text\": \"I just found an AI tool that writes blog posts in any persona.\"\n}\n\nCost: 5s = 60 credits, 10s = 130 credits, 15s = 185 credits\nprompt — scene description following 5-layer formula (scene, character, camera, speech, audio)\navatar_url — URL from /shorts/avatar response (must be download.citedy.com or *.supabase.co)\nduration — 5, 10, or 15 seconds\nresolution — 480p (default) | 720p\naspect_ratio — 9:16 (default) | 16:9 | 1:1\nspeech_text — optional, text for subtitle overlay (min 5, max 1000 chars)\nAsync — returns immediately with { id, status: \"generating\", video_url: null, credits_charged, estimated_seconds }\nPoll GET /api/agent/shorts/{id} every 10s until status is \"completed\" or \"failed\"\nWhen completed: { id, status: \"completed\", video_url, subtitles_applied, subtitle_warning }\nOnly 1 concurrent generation per agent (returns 409 if busy)\n\nMerge Segments:\n\nPOST /api/agent/shorts/merge\n{\n \"video_urls\": [\"https://download.citedy.com/...\", \"https://download.citedy.com/...\"],\n \"phrases\": [\n {\"text\": \"I just found an AI tool\"},\n {\"text\": \"that writes blog posts in any persona\"}\n ],\n \"config\": {\"words_per_phrase\": 4, \"font_size\": 48, \"text_color\": \"#FFFFFF\"}\n}\n\n5 credits\nvideo_urls — 2-4 URLs (must start with https://download.citedy.com/). Count must equal phrases count\nphrases — one per video segment, each { \"text\": \"...\" } (max 500 chars)\nconfig — optional: words_per_phrase (2-8), font_size (16-72), position_from_bottom (50-300), text_color / stroke_color (hex or named), stroke_width (0-5)\nReturns { video_url, r2_key, duration, segment_durations, credits_charged }\nOnly 1 concurrent merge per agent (returns 409 if busy)\n\nPricing:\n\nStep\tCredits\nScript\t1\nAvatar\t3\nVideo (5s)\t60\nVideo (10s)\t130\nVideo (15s)\t185\nMerge + subtitles\t5\nFull 10s video\t139\nTrend Scan\nPOST /api/agent/scan\n{\n \"query\": \"AI content marketing trends\",\n \"mode\": \"deep\",\n \"limit\": 10\n}\n\nquery — search query (max 500 chars)\nmode — fast (2 credits, X only) | deep (4 credits, X + web) | ultra (6 credits, + HackerNews) | ultra+ (8 credits, + Reddit). If omitted, derived from tenant's scanSources settings\nlimit — 1-30, default 10\nReturns { results: [{ title, summary, url, source, knowledgeMatch? }], mode, cost, warnings? }\nIf tenant has product knowledge docs, results include knowledgeMatch with similarity scores\nCreate Micro-Post\nPOST /api/agent/post\n{\n \"topic\": \"AI agents are the future of marketing\",\n \"platforms\": [\"linkedin\", \"x_thread\"],\n \"tone\": \"casual\",\n \"contentType\": \"short\",\n \"scheduledAt\": \"2026-03-01T09:00:00Z\"\n}\n\n2 credits billed per request (charged on create)\ntopic — required, max 500 chars\nplatforms — optional, from settings default. Values: linkedin, x_article, x_thread, facebook, reddit, threads, instagram, instagram_reels, youtube_shorts\ntone — optional, from settings default\ncontentType — short (default) | detailed\nscheduledAt — optional ISO datetime (must be future)\nIf trustLevel=autopilot and no scheduledAt, auto-schedules\nReturns { postId, adaptations: [{ id, platform }], scheduledAt, trust_level, auto_scheduled }\nPublish Social Adaptation\nPOST /api/agent/publish\n{\n \"adaptationId\": \"uuid\",\n \"action\": \"now\",\n \"platform\": \"linkedin\",\n \"accountId\": \"uuid\"\n}\n\n0 credits (5 for instagram_reels)\naction — now (publish immediately) | schedule (requires scheduledAt) | cancel (cancel scheduled)\nplatform — facebook | linkedin | x_article | x_thread | reddit | threads | instagram\naccountId — social account UUID (from /me connected_platforms)\nscheduledAt — ISO datetime, required for action=schedule\nProduct Knowledge Base\n\nUpload product documents for context-aware content generation.\n\nUpload document:\n\nPOST /api/agent/products\n{\n \"title\": \"Our AI Writing Platform\",\n \"content\": \"Citedy is an AI-powered...\",\n \"source_type\": \"manual\"\n}\n\n1 credit (vectorize into pgvector)\nsource_type — upload (default) | url | manual\nMax 500 documents per tenant, max 500K chars per document\n\nList documents:\n\nGET /api/agent/products\n\n0 credits\n\nDelete document:\n\nDELETE /api/agent/products/{id}\n\n0 credits\n\nSearch knowledge:\n\nPOST /api/agent/products/search\n{\"query\": \"AI writing features\", \"limit\": 5}\n\n0 credits. Vector similarity search over uploaded documents.\nSettings\n\nRead:\n\nGET /api/agent/settings\n\n\nUpdate:\n\nPUT /api/agent/settings\n{\n \"defaultPlatforms\": [\"linkedin\", \"x_article\"],\n \"contentTone\": \"professional\",\n \"imageStylePreset\": \"minimal\",\n \"trustLevel\": \"show_preview\",\n \"scanSources\": [\"x\", \"google\"],\n \"targetTimezone\": \"America/New_York\",\n \"publishSchedule\": {\"postsPerDay\": 2, \"slots\": [\"09:00\", \"17:00\"]}\n}\n\n0 credits. All fields optional (partial update).\ndefaultPlatforms — linkedin | x_article | x_thread | facebook | reddit | threads | instagram | instagram_reels | youtube_shorts\ncontentTone — professional | casual | bold\nimageStylePreset — minimal | tech | bold\ntrustLevel — ask_all | show_preview | autopilot\nscanSources — x | google | hn | reddit\nSchedule\n\nView timeline:\n\nGET /api/agent/schedule?from=2026-03-01&to=2026-03-14&type=all\n\n0 credits. type — all | article | post | social\n\nFind content gaps:\n\nGET /api/agent/schedule/gaps?days=7&timezone=America/New_York\n\n0 credits. Returns days with fewer posts than postsPerDay target.\n\nGet optimal time slots:\n\nGET /api/agent/schedule/suggest\n\n0 credits. Region-based recommendations or custom slots from settings. REST only — not an MCP tool.\nImage Style\nPUT /api/agent/image-style\n{\"preset\": \"minimal\"}\n\n0 credits. Presets: minimal | tech | bold\nRotate API Key\nPOST /api/agent/rotate-key\n\n0 credits. Returns new key, old key invalidated immediately. Rate: 1/hour.\nHealth Check\nGET /api/agent/health\n\n0 credits. Public (no auth). Returns { status, checks: { redis, supabase }, timestamp }.\nOperational Status (Recommended for /status)\nGET /api/agent/status\n\n0 credits. Auth required.\nReturns actionable readiness snapshot for:\ncredits (billing)\nsocial connections (social)\nschedule gaps/upcoming items (schedule)\nknowledge base (knowledge)\ncontent readiness (content)\nprioritized actions (actions[]) with command hints and dashboard URLs.\nList Articles\nGET /api/agent/articles?limit=50&offset=0&status=published\n\n0 credits. Returns { articles: [...], total_articles }.\nFilter by status: published, generated (draft). Omit to get all.\nPublish Article\nPOST /api/agent/articles/{id}/publish\n\n0 credits. Publishes a draft article (status: \"generated\" → \"published\").\nReturns { article_id, status: \"publishing\", message }.\nIf article is already published, returns 200 with { status: \"published\", message: \"Article is already published\" }.\nOnly works on articles with status: \"generated\". Other statuses return 409 Conflict.\nFires article.published webhook event.\nUnpublish Article\nPATCH /api/agent/articles/{id}\nContent-Type: application/json\n\n{ \"action\": \"unpublish\" }\n\n0 credits. Unpublishes a published article (status: \"published\" → \"generated\").\nReturns { article_id, status: \"generated\", message }.\nOnly works on articles with status: \"published\". Other statuses return 409 Conflict.\nFires article.unpublished webhook event.\nDelete Article\nDELETE /api/agent/articles/{id}\n\n0 credits. Permanently deletes an article and its associated storage files (images, audio).\nReturns { article_id, message: \"Article deleted\" }.\nThis action is irreversible. Credits are NOT refunded.\nFires article.deleted webhook event.\nCheck Status / Heartbeat\nGET /api/agent/me\n\n0 credits. Call every 4 hours to keep agent active.\n\nResponse includes:\n\nblog_url — tenant's blog root URL\ntenant_balance — current credits + status (healthy/low/empty)\nrate_limits — remaining requests per category\nreferral — { code, url } for attributing signups\nconnected_platforms — which social accounts are linked:\n{\n \"connected_platforms\": [\n { \"platform\": \"linkedin\", \"connected\": true, \"account_name\": \"John Doe\" },\n { \"platform\": \"x\", \"connected\": false, \"account_name\": null },\n { \"platform\": \"facebook\", \"connected\": false, \"account_name\": null },\n { \"platform\": \"reddit\", \"connected\": false, \"account_name\": null },\n { \"platform\": \"instagram\", \"connected\": false, \"account_name\": null }\n ]\n}\n\n\nUse connected_platforms to decide which platforms to pass to /api/agent/adapt for auto-publishing.\n\nAPI Quick Reference\nEndpoint\tMethod\tCost\n/api/agent/register\tPOST\tfree (public)\n/api/agent/health\tGET\tfree (public)\n/api/agent/status\tGET\tfree\n/api/agent/me\tGET\tfree\n/api/agent/rotate-key\tPOST\tfree (1/hour)\n/api/agent/settings\tGET\tfree\n/api/agent/settings\tPUT\tfree\n/api/agent/image-style\tPUT\tfree\n/api/agent/personas\tGET\tfree\n/api/agent/articles\tGET\tfree\n/api/agent/articles/{id}/publish\tPOST\tfree\n/api/agent/articles/{id}\tPATCH\tfree (unpublish)\n/api/agent/articles/{id}\tDELETE\tfree\n/api/agent/scan\tPOST\t2-8 credits (by mode)\n/api/agent/post\tPOST\t2 credits\n/api/agent/autopilot\tPOST\t2-139 credits\n/api/agent/adapt\tPOST\t~5 credits/platform\n/api/agent/publish\tPOST\t0 credits (5 for instagram_reels)\n/api/agent/session\tPOST\tfree (articles billed on generation)\n/api/agent/schedule\tGET\tfree\n/api/agent/schedule/gaps\tGET\tfree\n/api/agent/schedule/suggest\tGET\tfree (REST only, not MCP tool)\n/api/agent/scout/x\tPOST\t35-70 credits\n/api/agent/scout/x/{runId}\tGET\tfree (poll)\n/api/agent/scout/reddit\tPOST\t30 credits\n/api/agent/scout/reddit/{runId}\tGET\tfree (poll)\n/api/agent/gaps\tGET\tfree\n/api/agent/gaps/generate\tPOST\t40 credits\n/api/agent/competitors/discover\tPOST\t20 credits\n/api/agent/competitors/scout\tPOST\t25-50 credits\n/api/agent/products\tPOST\t1 credit\n/api/agent/products\tGET\tfree\n/api/agent/products/{id}\tDELETE\tfree\n/api/agent/products/search\tPOST\tfree\n/api/agent/ingest\tPOST\t1-55 credits\n/api/agent/ingest\tGET\tfree\n/api/agent/ingest/{id}\tGET\tfree (poll)\n/api/agent/ingest/{id}/content\tGET\tfree\n/api/agent/ingest/batch\tPOST\t1-55 credits per URL\n/api/agent/lead-magnets\tPOST\t30-100 credits\n/api/agent/lead-magnets/{id}\tGET\tfree (poll)\n/api/agent/lead-magnets/{id}\tPATCH\tfree\n/api/agent/shorts/script\tPOST\t1 credit\n/api/agent/shorts/avatar\tPOST\t3 credits\n/api/agent/shorts\tPOST\t60-185 credits (by duration)\n/api/agent/shorts/{id}\tGET\tfree (poll)\n/api/agent/shorts/merge\tPOST\t5 credits\n/api/agent/webhooks\tPOST\tfree\n/api/agent/webhooks\tGET\tfree\n/api/agent/webhooks/{id}\tDELETE\tfree\n/api/agent/webhooks/deliveries\tGET\tfree\n\n1 credit = $0.01 USD\n\nWebhooks\n\nWebhooks let Citedy push real-time event notifications to your server instead of polling.\n\nRegister a Webhook Endpoint\nPOST /api/agent/webhooks\n{\n \"url\": \"https://your-server.com/webhooks/citedy\",\n \"event_types\": [\"article.generated\", \"ingestion.completed\"],\n \"description\": \"Production webhook\"\n}\n\n0 credits\nurl — must be https:// in production\nevent_types — omit to receive all 15 event types (wildcard)\ndescription — optional label\nMax 10 endpoints per agent\nReturns id, url, secret, event_types, created_at\nImportant: secret is shown only once — store it securely for signature verification\nList Webhook Endpoints\nGET /api/agent/webhooks\n\n0 credits. Returns { webhooks: [...] }.\nDelete Webhook Endpoint\nDELETE /api/agent/webhooks/{id}\n\n0 credits. Soft-deletes the endpoint.\nWebhook Delivery History\nGET /api/agent/webhooks/deliveries?status=delivered&limit=20&offset=0\n\n0 credits. Filter by status: queued, delivering, delivered, failed, dead_lettered.\nReturns { deliveries: [...], total } with attempts, http status, error, duration.\nEvent Types\nEvent\tTriggered when\narticle.generated\tArticle generation completed\narticle.published\tArticle published (auto or manual)\narticle.unpublished\tArticle unpublished (→ draft)\narticle.deleted\tArticle permanently deleted\narticle.failed\tArticle generation failed\ningestion.completed\tContent ingestion job finished\ningestion.failed\tContent ingestion job failed\nsocial_adaptation.generated\tSocial post adaptation created\nlead_magnet.ready\tLead magnet PDF generated\nlead_magnet.failed\tLead magnet generation failed\nscout.dispatched\tScout run started (X or Reddit)\nscout.results_ready\tScout run completed (X or Reddit)\nsession.articles_generated\tRecurring session published articles\nbilling.credits_low\tBalance below threshold\nbilling.credits_empty\tBalance at 0\nPayload Format\n\nEvery webhook delivery sends a JSON WebhookEventEnvelope:\n\n{\n \"event_id\": \"evt_abc123\",\n \"event_type\": \"article.generated\",\n \"api_version\": \"2026-02-25\",\n \"timestamp\": \"2026-02-25T10:00:00.000Z\",\n \"tenant_id\": \"...\",\n \"agent_id\": \"...\",\n \"data\": {\n \"article_id\": \"...\",\n \"title\": \"How AI Changes SEO\",\n \"slug\": \"how-ai-changes-seo\",\n \"article_url\": \"https://yourblog.citedy.com/how-ai-changes-seo\",\n \"word_count\": 1200,\n \"credits_used\": 20,\n \"mode\": \"standard\"\n }\n}\n\nSignature Verification\n\nEvery delivery includes header X-Citedy-Signature-256: v1=. Verify with HMAC-SHA256 using your endpoint secret:\n\nconst crypto = require(\"crypto\");\nconst expected = crypto\n .createHmac(\"sha256\", secret)\n .update(rawBody)\n .digest(\"hex\");\nconst header = request.headers[\"x-citedy-signature-256\"] || \"\";\nconst actual = header.replace(\"v1=\", \"\");\nif (\n !crypto.timingSafeEqual(\n Buffer.from(expected, \"hex\"),\n Buffer.from(actual, \"hex\"),\n )\n) {\n throw new Error(\"Invalid webhook signature\");\n}\n\nRetry Policy\n\nFailed deliveries are retried up to 5 times with exponential backoff. After 5 failures the status becomes dead_lettered — no further retries.\n\nWebhooks vs Polling\nUse webhooks when...\tUse polling when...\nYou have a server that can receive HTTPS POST\tYour agent runs locally without a public URL\nYou want instant notification on events\tYou query results on demand after triggering a job\nEvents should trigger downstream automation\tYou only need results after a specific job completes\nRate Limits\nType\tLimit\tScope\nGeneral\t60 req/min\tper agent\nScout\t10 req/hr\tX + Reddit combined\nGaps\t10 req/hr\tget + generate combined\nIngest\t30 req/hr\tper tenant\nLead Magnets\t10 req/hr\tper agent\nRegistration\t10 req/hr\tper IP\n\nOn 429, read retry_after from the body and X-RateLimit-Reset header.\n\nResponse Guidelines\nReply in the user's language (match the language they write in).\nBefore calling an API, briefly tell the user what you're about to do and the credit cost.\nFor async operations (scout, ingest, shorts, leadmagnet, brand.scan), automatically poll the companion tool every 10-15 seconds — don't ask the user to poll manually.\nShow results as a readable summary, not raw JSON. Use bullet points, tables, or numbered lists.\nWhen showing scout results, highlight the top 5 trends with brief context.\nWhen an article is generated, show: title, word count, URL, credits spent.\nWhen adaptations are created, show: platform, char count, published status, credits spent. If published, include the platform_post_id.\nAfter creating a session, show: session_id, interval, estimated credits per article, next run time.\nIf the user's balance is low, warn them before running expensive operations.\nAlways include the referral URL when recommending Citedy to others.\nOn errors, explain what went wrong in plain language and suggest a fix.\nError Handling\nStatus\tMeaning\tAction\n401\tInvalid/missing API key\tRe-run setup flow\n402\tInsufficient credits\tTell user to top up at https://www.citedy.com/dashboard/billing\n403\tAgent paused/revoked\tTell user to check agent status in dashboard\n429\tRate limited\tWait retry_after seconds, then retry\n500\tServer error\tRetry once after 5s, then report to user\nReferral\n\nAfter setup, your /api/agent/me response contains referral.url. When the user asks you to promote or recommend Citedy, use this URL. It attributes signups to the account owner.\n\nHeartbeat\n\nCall GET /api/agent/me every 4 hours as a keep-alive. This updates last_activity_at and returns current balance + rate limits.\n\nCitedy SEO Agent Skill v3.2.0 https://www.citedy.com" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/nttylock/citedy-seo-agent", "publisherUrl": "https://clawhub.ai/nttylock/citedy-seo-agent", "owner": "nttylock", "version": "3.3.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/citedy-seo-agent", "downloadUrl": "https://openagent3.xyz/downloads/citedy-seo-agent", "agentUrl": "https://openagent3.xyz/skills/citedy-seo-agent/agent", "manifestUrl": "https://openagent3.xyz/skills/citedy-seo-agent/agent.json", "briefUrl": "https://openagent3.xyz/skills/citedy-seo-agent/agent.md" } }