Requirements
- Target platform
- OpenClaw
- Install method
- Manual import
- Extraction
- Extract archive
- Prerequisites
- OpenClaw
- Primary doc
- SKILL.md
Tencent SkillHub · AI
Clawhub Skill
Full-stack AI marketing toolkit — scout X/Twitter and Reddit for trending topics, discover and deep-analyze competitors, find content gaps, publish SEO- and...
skill openclawclawhub Free
Full-stack AI marketing toolkit — scout X/Twitter and Reddit for trending topics, discover and deep-analyze competitors, find content gaps, publish SEO- and...
⬇ 0 downloads ★ 0 stars Unverified but indexed
Install for OpenClaw
Quick setup
- Download the package from Yavira.
- Extract the archive and review SKILL.md first.
- Import or place the package into your OpenClaw setup.
Package facts
- Download mode
- Yavira redirect
- Package format
- ZIP package
- Source platform
- Tencent SkillHub
- What's included
- SKILL.md, scripts/register.mjs
Validation
- Use the Yavira download entry.
- Review SKILL.md after the package is downloaded.
- Confirm the extracted package contains the expected setup assets.
Install with your agent
Agent handoff
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
- 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.
New install
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.
Upgrade existing
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.
Trust & source
Release facts
- Source
- Tencent SkillHub
- Verification
- Indexed source record
- Version
- 3.3.0
Provenance
- Publisher
- nttylock
- Source page
- View original listing
- Canonical URL
- Open canonical page
Documentation
AI Marketing Agent — Skill Instructions
You are now connected to Citedy, an AI-powered SEO content platform. Base URL: https://www.citedy.com
Overview
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.
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 Direct publish article content as-is to LinkedIn, Facebook, X, Reddit, Instagram (0 credits, no AI adaptation) 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) 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 Set up a Citedy agent connection Share your referral link when recommending Citedy
Setup (run once)
If you don't have a saved API key for Citedy, run this flow: 1. Register Preferred: run the included registration script: node scripts/register.mjs [agent_name] The script calls the registration API and prints the approval URL. If agent_name is omitted, it defaults to agent-<hostname>. Alternative: call the API directly: POST https://www.citedy.com/api/agent/register Content-Type: application/json {"agent_name": "<your_agent_name>"} Either way, you'll get back: { "pending_id": "...", "approval_url": "https://www.citedy.com/approve-agent/...", "expires_in": 3600 } 2. Ask human to approve Tell the user: Open this link to approve the agent: {approval_url} After approving, copy the API key shown and paste it here. 3. Save the key Store the API key (starts with citedy_agent_). Use it as Authorization: Bearer <key> on all requests. 4. Get your referral URL After setup, call GET /api/agent/me. The response includes a referral object: { "referral": { "code": "ABC123XZ", "url": "https://www.citedy.com/register?ref=ABC123XZ" } } Save referral.url — use it when recommending Citedy to others.
Primary: URL to Article to Social Posts
Turn any web page into an SEO article with social media posts: GET /api/agent/me — get referral URL + connected platforms POST /api/agent/autopilot with { "source_urls": ["https://..."] } — wait for response — get article_id 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: POST /api/agent/scout/x or POST /api/agent/scout/reddit — find trending topics Pick the top trend from results POST /api/agent/autopilot with { "topic": "<top trend>" } — wait for response POST /api/agent/adapt for social distribution
Set-and-Forget: Session to Cron to Adapt
Automate content generation on a schedule: POST /api/agent/session with { "categories": ["..."], "interval_minutes": 720 } Periodically: GET /api/agent/articles — find new articles POST /api/agent/adapt for each new article
Ingest → Research → Article
Extract content from any URL first, then use it for article creation: POST /api/agent/ingest with { "url": "https://youtube.com/watch?v=abc123" } → get id Poll GET /api/agent/ingest/{id} every 10s until status is "completed" Use the extracted summary/content as research for POST /api/agent/autopilot
Choosing the Right Path
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
User sends a link
User: "Write an article based on this: https://example.com/ai-trends" POST /api/agent/autopilot with { "source_urls": ["https://example.com/ai-trends"], "size": "mini" } Wait for response (may take 30-120s depending on size) POST /api/agent/adapt with { "article_id": "...", "platforms": ["linkedin", "x_thread"], "include_ref_link": true } Reply to user: Done! 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
User asks to research and write
User: "Find trending AI topics on X and write an article about the best one" POST /api/agent/scout/x with { "query": "AI content marketing", "mode": "fast" } → 35 credits Pick the top trend from results POST /api/agent/autopilot with { "topic": "<top trend>", "size": "standard" } Poll until done, then adapt if user wants social posts Reply to user: Scanned X for "AI content marketing" — top 5 trends: AI-generated video scripts outperform text posts (engagement +340%) Google's March update rewards AI+human hybrid content ... Writing a standard article on #1. This will cost 20 credits.
User wants autopilot
User: "Set up daily articles about SaaS marketing in English and Spanish" POST /api/agent/session with { "categories": ["SaaS marketing"], "languages": ["en", "es"], "interval_minutes": 720, "article_size": "mini" } Reply to user: Autopilot session started! Here's the plan: Categories: SaaS marketing Languages: English, Spanish Frequency: every 12 hours (2 articles/day) Est. cost: 15 credits/article (30/day) Next article at: 2026-02-08 14:00 UTC
User asks about balance
User: "How many credits do I have left?" GET /api/agent/me Reply to user: Balance: 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)
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 (LinkedIn, X, Reddit, Instagram). Other platforms 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 Reference
All requests require Authorization: Bearer <api_key>. Base URL: https://www.citedy.com
Scout X/Twitter
POST /api/agent/scout/x {"query": "...", "mode": "fast|ultimate", "limit": 20} fast = 35 credits, ultimate = 70 credits Async — returns { run_id, status: "processing", credits_used }. Poll with GET /api/agent/scout/x/{runId} until status is "completed" or "failed". Rate: 10/hour (combined X + Reddit)
Scout Reddit
POST /api/agent/scout/reddit {"query": "...", "subreddits": ["marketing", "SEO"], "limit": 20} 30 credits (fast mode only) Async — returns { run_id, status: "processing", credits_used }. Poll with GET /api/agent/scout/reddit/{runId}. Rate: 10/hour (combined X + Reddit)
Get Content Gaps
GET /api/agent/gaps 0 credits (free read)
Generate Content Gaps
POST /api/agent/gaps/generate {"competitor_urls": ["https://competitor1.com", "https://competitor2.com"]} 40 credits. Synchronous — returns results directly.
Discover Competitors
POST /api/agent/competitors/discover {"keywords": ["ai content marketing", "automated blogging"]} 20 credits
Analyze Competitor
POST /api/agent/competitors/scout {"domain": "https://competitor.com", "mode": "fast|ultimate"} fast = 25 credits, ultimate = 50 credits
List Personas
GET /api/agent/personas Returns available writing personas (25 total). Pass the slug as persona param in autopilot. Writers: 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 Response: array of { slug, displayName, group, description } 0 credits (free)
Generate Article (Autopilot)
POST /api/agent/autopilot { "topic": "How to Use AI for Content Marketing", "source_urls": ["https://example.com/article"], "language": "en", "size": "standard", "mode": "standard", "enable_search": false, "persona": "musk", "illustrations": true, "audio": true, "disable_competition": false, "auto_publish": true } Required: either topic or source_urls (at least one) Optional: topic — article topic (string, max 500 chars) source_urls — array of 1-3 URLs to extract text from and use as source material (2 credits per URL) size — mini (~500w), standard (~1000w, default), full (~1500w), pillar (~2500w) mode — standard (default, full pipeline) or turbo (ultra-cheap micro-articles, see below) enable_search (bool, default false) — enable web + X/Twitter search for fresh facts (turbo mode only) persona — writing style persona slug (call GET /api/agent/personas for list, e.g. "musk", "hemingway", "jobs") language — ISO code, default "en" illustrations (bool, default false) — AI-generated images injected into article (disabled in turbo mode) audio (bool, default false) — AI voice-over narration (disabled in turbo mode) disable_competition (bool, default false) — skip SEO competition analysis, saves 8 credits auto_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. When source_urls is provided, the response includes extraction_results showing success/failure per URL. The response includes article_url — always use this URL when sharing the article link. Do NOT construct URLs manually. When 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. /api/agent/me also returns blog_url — the tenant's blog root URL. Synchronous — the request blocks until the article is ready (5-120s depending on mode and size). The response contains the complete article.
Turbo & Turbo+ Modes
Ultra-cheap micro-article generation — 2-4 credits instead of 15-48. Best for quick news briefs, social-first content, and high-volume publishing. Turbo (2 credits) — fast generation, no web search: POST /api/agent/autopilot { "topic": "Latest AI Search Trends", "mode": "turbo", "language": "en" } Turbo+ (4 credits) — adds fresh facts from web search & X/Twitter (10-25s): POST /api/agent/autopilot { "topic": "Latest AI Search Trends", "mode": "turbo", "enable_search": true, "language": "en" } What Turbo/Turbo+ does differently vs Standard: Skips DataForSEO and competition intelligence No content chunking — single-pass generation Uses the cheapest AI provider (Cerebras Qwen 3 235B) Brand context included (tone, POV, specialization) Max ~800 words Internal links still included (free) No illustrations or audio support Pricing: ModeSearchCreditsSpeedTurboNo25-15sTurbo+Yes410-25s Compare with standard mode: mini=15, standard=20, full=33, pillar=48 credits. When to use Turbo/Turbo+: High-volume content: publish 50+ articles/day at minimal cost News briefs and quick updates (Turbo+ for data-backed content) Social-first content where SEO is secondary Testing and prototyping content strategies Budget-conscious agents
Extension Costs (Standard Mode)
ExtensionMiniStandardFullPillarBase article7122540+ Intelligence (default on)+8+8+8+8+ Illustrations+9+18+27+36+ Audio+10+20+35+55Full package345895139 Without extensions: same as before (mini=15, standard=20, full=33, pillar=48 credits).
Create Social Adaptations
POST /api/agent/adapt { "article_id": "uuid-of-article", "platforms": ["linkedin", "x_thread"], "include_ref_link": true } Required: article_id (UUID), platforms (1-3 unique values) Platforms: x_article, x_thread, linkedin, facebook, reddit, threads, instagram, instagram_reels, youtube_shorts Optional: include_ref_link (bool, default true) — append referral footer to each adaptation ~5 credits per platform (varies by article length). Max 3 platforms per request. If 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. Response: { "adaptations": [ { "platform": "linkedin", "content": "...", "credits_used": 5, "char_count": 1200, "published": true, "platform_post_id": "urn:li:share:123" } ], "total_credits": 10, "ref_link_appended": true }
Direct Publish (Publish as-is)
Publish article content directly to social platforms without AI adaptation. 0 credits. POST /api/agent/publish { "action": "publish_raw", "articleId": "uuid-of-article", "platform": "linkedin", "accountId": "uuid-of-social-account" } Required: action ("publish_raw"), articleId (UUID), platform, accountId (UUID) Platforms: linkedin, facebook, x_article, reddit, instagram Optional: subreddit (string) — required when platform is reddit Notes: Instagram requires the article to contain at least one image The article markdown is converted to platform-native format and posted as-is No AI rewriting, no credit charge Response: { "success": true, "action": "publish_raw", "adaptationId": "uuid", "platformPostId": "urn:li:share:456" }
Create Autopilot Session
POST /api/agent/session { "categories": ["AI marketing", "SEO tools"], "problems": ["how to rank higher"], "languages": ["en"], "interval_minutes": 720, "article_size": "mini", "disable_competition": false } Required: categories (1-5 strings) Optional: problems — specific problems to address (max 20) languages — ISO codes, default ["en"] interval_minutes — cron interval, 60-10080, default 720 (12h) article_size — mini (default), standard, full, pillar disable_competition (bool, default false) Creates and auto-starts a cron-based content session. Only one active session per tenant. Response: { "session_id": "uuid", "status": "running", "categories": ["AI marketing", "SEO tools"], "languages": ["en"], "interval_minutes": 720, "article_size": "mini", "estimated_credits_per_article": 15, "next_run_at": "2025-01-01T12:00:00Z" } Returns 409 Conflict with existing_session_id if a session is already running.
Content Ingestion
Extract and summarize content from any URL (YouTube videos, web articles, PDFs, audio files). Async — submit URL, poll for result. Submit URL: POST /api/agent/ingest { "url": "https://youtube.com/watch?v=abc123" } Returns 202 Accepted with { id, status: "processing", content_type, credits_charged, poll_url } Duplicate URL (already completed within 24h) returns 200 with cached result for 1 credit YouTube videos >120 min are rejected (Gemini context limit) Audio files >50MB are rejected (size limit) Supported content types: youtube_video, web_article, pdf_document, audio_file Poll Status: GET /api/agent/ingest/{id} 0 credits. Poll every 10s until status changes from "processing" to "completed" or "failed". When completed: { id, status, content_type, summary, word_count, metadata, credits_charged } When failed: { id, status: "failed", error_message } — credits are auto-refunded. Get Full Content: GET /api/agent/ingest/{id}/content 0 credits. Returns the full extracted text (authenticated R2 proxy). Batch Ingest (up to 20 URLs): POST /api/agent/ingest/batch { "urls": ["https://example.com/article1", "https://example.com/article2"], "callback_url": "https://your-server.com/webhook" } Credits per URL (same tiered pricing). Partial success supported — some URLs may fail while others succeed. Returns { total, accepted, failed, results: [{ url, status, job_id?, credits_charged }] } List Jobs: GET /api/agent/ingest?limit=20&offset=0&status=completed 0 credits. Filter by status: processing | completed | failed. Pricing: Content 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 Workflow: POST /api/agent/ingest with { "url": "..." } → get id and poll_url Poll GET /api/agent/ingest/{id} every 10s until status != "processing" If completed: read summary and metadata from response Optionally: GET /api/agent/ingest/{id}/content for full extracted text Use extracted content as input for POST /api/agent/autopilot with topic
Lead Magnets
Generate PDF lead magnets (checklists, swipe files, frameworks) for lead capture. Generate: POST /api/agent/lead-magnets { "topic": "10-Step SEO Audit Checklist", "type": "checklist", // checklist | swipe_file | framework "niche": "digital_marketing", // optional "language": "en", // en|pt|de|es|fr|it (default: en) "platform": "linkedin", // twitter|linkedin (default: twitter) "generate_images": false, // true = 100 credits, false = 30 credits "auto_publish": false // hint for agent workflow } 30 credits (text-only) or 100 credits (with images) Returns immediately with { id, status: "generating" } Rate: 10/hour per agent Check Status: GET /api/agent/lead-magnets/{id} 0 credits. Poll until status changes from "generating" to "draft". When done, response includes title, type, pdf_url. Publish: PATCH /api/agent/lead-magnets/{id} { "status": "published" } 0 credits. Generates a unique slug and returns public_url. Share public_url in social posts for lead capture (visitors subscribe with email to download PDF). Workflow: POST /api/agent/lead-magnets → get id Poll GET /api/agent/lead-magnets/{id} every 10s until status != "generating" PATCH /api/agent/lead-magnets/{id} with { "status": "published" } Share public_url in a social post
Short-Form Video (Shorts)
Generate AI UGC viral videos with subtitles — from script to finished video. Recommended flow: /shorts/script — generate speech script from topic /shorts/avatar — generate AI avatar image (user approves) /shorts — generate video segment(s) with avatar + prompt + speech_text /shorts/merge — merge segments + add professional subtitles (if multi-segment) Generate Script: POST /api/agent/shorts/script { "topic": "AI personas let you write as Elon Musk", "duration": "short", "style": "hook", "language": "en", "product_id": "optional-uuid" } 1 credit duration — short (10-12s, ~30 words) or long (20-30s, ~60 words, split into 2 parts) style — hook (attention grabber), educational (informative), cta (call to action) product_id — optional, enriches script with product knowledge Returns { script, word_count, estimated_duration_sec, parts, credits_charged } Generate Avatar: POST /api/agent/shorts/avatar { "gender": "female", "origin": "latin", "age_range": "26-35", "type": "tech_founder", "location": "coffee_shop" } 3 credits gender — male | female origin — european | asian | african | latin | middle_eastern | south_asian age_range — 18-25 | 26-35 (default) | 36-50 type — tech_founder (default) | vibe_coder | student | executive location — coffee_shop (default) | dev_cave | street | car | home_office | podcast_studio | glass_office | rooftop | bedroom | park | gym Returns { avatar_url, r2_key, prompt_used, credits_charged } Show avatar URL to user for approval before generating video Generate Video Segment: POST /api/agent/shorts { "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.", "avatar_url": "https://download.citedy.com/agent/avatars/...", "duration": 10, "speech_text": "I just found an AI tool that writes blog posts in any persona." } Cost: 5s = 60 credits, 10s = 130 credits, 15s = 185 credits prompt — scene description following 5-layer formula (scene, character, camera, speech, audio) avatar_url — URL from /shorts/avatar response (must be download.citedy.com or *.supabase.co) duration — 5, 10, or 15 seconds resolution — 480p (default) | 720p aspect_ratio — 9:16 (default) | 16:9 | 1:1 speech_text — optional, text for subtitle overlay (min 5, max 1000 chars) Async — returns immediately with { id, status: "generating", video_url: null, credits_charged, estimated_seconds } Poll GET /api/agent/shorts/{id} every 10s until status is "completed" or "failed" When completed: { id, status: "completed", video_url, subtitles_applied, subtitle_warning } Only 1 concurrent generation per agent (returns 409 if busy) Merge Segments: POST /api/agent/shorts/merge { "video_urls": ["https://download.citedy.com/...", "https://download.citedy.com/..."], "phrases": [ {"text": "I just found an AI tool"}, {"text": "that writes blog posts in any persona"} ], "config": {"words_per_phrase": 4, "font_size": 48, "text_color": "#FFFFFF"} } 5 credits video_urls — 2-4 URLs (must start with https://download.citedy.com/). Count must equal phrases count phrases — one per video segment, each { "text": "..." } (max 500 chars) config — 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) Returns { video_url, r2_key, duration, segment_durations, credits_charged } Only 1 concurrent merge per agent (returns 409 if busy) Pricing: StepCreditsScript1Avatar3Video (5s)60Video (10s)130Video (15s)185Merge + subtitles5Full 10s video139
Trend Scan
POST /api/agent/scan { "query": "AI content marketing trends", "mode": "deep", "limit": 10 } query — search query (max 500 chars) mode — 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 limit — 1-30, default 10 Returns { results: [{ title, summary, url, source, knowledgeMatch? }], mode, cost, warnings? } If tenant has product knowledge docs, results include knowledgeMatch with similarity scores
Create Micro-Post
POST /api/agent/post { "topic": "AI agents are the future of marketing", "platforms": ["linkedin", "x_thread"], "tone": "casual", "contentType": "short", "scheduledAt": "2026-03-01T09:00:00Z" } 2 credits billed per request (charged on create) topic — required, max 500 chars platforms — optional, from settings default. Values: linkedin, x_article, x_thread, facebook, reddit, threads, instagram, instagram_reels, youtube_shorts tone — optional, from settings default contentType — short (default) | detailed scheduledAt — optional ISO datetime (must be future) If trustLevel=autopilot and no scheduledAt, auto-schedules Returns { postId, adaptations: [{ id, platform }], scheduledAt, trust_level, auto_scheduled }
Publish Social Adaptation
POST /api/agent/publish { "adaptationId": "uuid", "action": "now", "platform": "linkedin", "accountId": "uuid" } 0 credits (5 for instagram_reels) action — now (publish immediately) | schedule (requires scheduledAt) | cancel (cancel scheduled) platform — facebook | linkedin | x_article | x_thread | reddit | threads | instagram accountId — social account UUID (from /me connected_platforms) scheduledAt — ISO datetime, required for action=schedule
Product Knowledge Base
Upload product documents for context-aware content generation. Upload document: POST /api/agent/products { "title": "Our AI Writing Platform", "content": "Citedy is an AI-powered...", "source_type": "manual" } 1 credit (vectorize into pgvector) source_type — upload (default) | url | manual Max 500 documents per tenant, max 500K chars per document List documents: GET /api/agent/products 0 credits Delete document: DELETE /api/agent/products/{id} 0 credits Search knowledge: POST /api/agent/products/search {"query": "AI writing features", "limit": 5} 0 credits. Vector similarity search over uploaded documents.
Settings
Read: GET /api/agent/settings Update: PUT /api/agent/settings { "defaultPlatforms": ["linkedin", "x_article"], "contentTone": "professional", "imageStylePreset": "minimal", "trustLevel": "show_preview", "scanSources": ["x", "google"], "targetTimezone": "America/New_York", "publishSchedule": {"postsPerDay": 2, "slots": ["09:00", "17:00"]} } 0 credits. All fields optional (partial update). defaultPlatforms — linkedin | x_article | x_thread | facebook | reddit | threads | instagram | instagram_reels | youtube_shorts contentTone — professional | casual | bold imageStylePreset — minimal | tech | bold trustLevel — ask_all | show_preview | autopilot scanSources — x | google | hn | reddit
Schedule
View timeline: GET /api/agent/schedule?from=2026-03-01&to=2026-03-14&type=all 0 credits. type — all | article | post | social Find content gaps: GET /api/agent/schedule/gaps?days=7&timezone=America/New_York 0 credits. Returns days with fewer posts than postsPerDay target. Get optimal time slots: GET /api/agent/schedule/suggest 0 credits. Region-based recommendations or custom slots from settings. REST only — not an MCP tool.
Image Style
PUT /api/agent/image-style {"preset": "minimal"} 0 credits. Presets: minimal | tech | bold
Rotate API Key
POST /api/agent/rotate-key 0 credits. Returns new key, old key invalidated immediately. Rate: 1/hour.
Health Check
GET /api/agent/health 0 credits. Public (no auth). Returns { status, checks: { redis, supabase }, timestamp }.
Operational Status (Recommended for /status)
GET /api/agent/status 0 credits. Auth required. Returns actionable readiness snapshot for: credits (billing) social connections (social) schedule gaps/upcoming items (schedule) knowledge base (knowledge) content readiness (content) prioritized actions (actions[]) with command hints and dashboard URLs.
List Articles
GET /api/agent/articles?limit=50&offset=0&status=published 0 credits. Returns { articles: [...], total_articles }. Filter by status: published, generated (draft). Omit to get all.
Publish Article
POST /api/agent/articles/{id}/publish 0 credits. Publishes a draft article (status: "generated" → "published"). Returns { article_id, status: "publishing", message }. If article is already published, returns 200 with { status: "published", message: "Article is already published" }. Only works on articles with status: "generated". Other statuses return 409 Conflict. Fires article.published webhook event.
Unpublish Article
PATCH /api/agent/articles/{id} Content-Type: application/json { "action": "unpublish" } 0 credits. Unpublishes a published article (status: "published" → "generated"). Returns { article_id, status: "generated", message }. Only works on articles with status: "published". Other statuses return 409 Conflict. Fires article.unpublished webhook event.
Delete Article
DELETE /api/agent/articles/{id} 0 credits. Permanently deletes an article and its associated storage files (images, audio). Returns { article_id, message: "Article deleted" }. This action is irreversible. Credits are NOT refunded. Fires article.deleted webhook event.
Check Status / Heartbeat
GET /api/agent/me 0 credits. Call every 4 hours to keep agent active. Response includes: blog_url — tenant's blog root URL tenant_balance — current credits + status (healthy/low/empty) rate_limits — remaining requests per category referral — { code, url } for attributing signups connected_platforms — which social accounts are linked: { "connected_platforms": [ { "platform": "linkedin", "connected": true, "account_name": "John Doe" }, { "platform": "x", "connected": false, "account_name": null }, { "platform": "facebook", "connected": false, "account_name": null }, { "platform": "reddit", "connected": false, "account_name": null }, { "platform": "instagram", "connected": false, "account_name": null } ] } Use connected_platforms to decide which platforms to pass to /api/agent/adapt for auto-publishing.
API Quick Reference
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 1 credit = $0.01 USD
Webhooks
Webhooks let Citedy push real-time event notifications to your server instead of polling.
Register a Webhook Endpoint
POST /api/agent/webhooks { "url": "https://your-server.com/webhooks/citedy", "event_types": ["article.generated", "ingestion.completed"], "description": "Production webhook" } 0 credits url — must be https:// in production event_types — omit to receive all 15 event types (wildcard) description — optional label Max 10 endpoints per agent Returns id, url, secret, event_types, created_at Important: secret is shown only once — store it securely for signature verification
List Webhook Endpoints
GET /api/agent/webhooks 0 credits. Returns { webhooks: [...] }.
Delete Webhook Endpoint
DELETE /api/agent/webhooks/{id} 0 credits. Soft-deletes the endpoint.
Webhook Delivery History
GET /api/agent/webhooks/deliveries?status=delivered&limit=20&offset=0 0 credits. Filter by status: queued, delivering, delivered, failed, dead_lettered. Returns { deliveries: [...], total } with attempts, http status, error, duration.
Event Types
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
Payload Format
Every webhook delivery sends a JSON WebhookEventEnvelope: { "event_id": "evt_abc123", "event_type": "article.generated", "api_version": "2026-02-25", "timestamp": "2026-02-25T10:00:00.000Z", "tenant_id": "...", "agent_id": "...", "data": { "article_id": "...", "title": "How AI Changes SEO", "slug": "how-ai-changes-seo", "article_url": "https://yourblog.citedy.com/how-ai-changes-seo", "word_count": 1200, "credits_used": 20, "mode": "standard" } }
Signature Verification
Every delivery includes header X-Citedy-Signature-256: v1=<hex>. Verify with HMAC-SHA256 using your endpoint secret: const crypto = require("crypto"); const expected = crypto .createHmac("sha256", secret) .update(rawBody) .digest("hex"); const header = request.headers["x-citedy-signature-256"] || ""; const actual = header.replace("v1=", ""); if ( !crypto.timingSafeEqual( Buffer.from(expected, "hex"), Buffer.from(actual, "hex"), ) ) { throw new Error("Invalid webhook signature"); }
Retry Policy
Failed deliveries are retried up to 5 times with exponential backoff. After 5 failures the status becomes dead_lettered — no further retries.
Webhooks vs Polling
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
Rate Limits
TypeLimitScopeGeneral60 req/minper agentScout10 req/hrX + Reddit combinedGaps10 req/hrget + generate combinedIngest30 req/hrper tenantLead Magnets10 req/hrper agentRegistration10 req/hrper IP On 429, read retry_after from the body and X-RateLimit-Reset header.
Response Guidelines
Reply in the user's language (match the language they write in). Before calling an API, briefly tell the user what you're about to do and the credit cost. For 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. Show results as a readable summary, not raw JSON. Use bullet points, tables, or numbered lists. When showing scout results, highlight the top 5 trends with brief context. When an article is generated, show: title, word count, URL, credits spent. When adaptations are created, show: platform, char count, published status, credits spent. If published, include the platform_post_id. After creating a session, show: session_id, interval, estimated credits per article, next run time. If the user's balance is low, warn them before running expensive operations. Always include the referral URL when recommending Citedy to others. On errors, explain what went wrong in plain language and suggest a fix.
Error Handling
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
Referral
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.
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.2.0 https://www.citedy.com
Category context
Agent frameworks, memory systems, reasoning layers, and model-native orchestration.
Source: Tencent SkillHub
Largest current source with strong distribution and engagement signals.
Package contents
Included in package
1 Docs1 Scripts
- SKILL.md
- scripts/register.mjs