Full-stack AI marketing toolkit — scout X/Twitter and Reddit for trending topics, discover and deep-analyze competitors, find content gaps, publish SEO- and GEO-optimized articles with AI illustrations and voice-over in 55 languages, create social media adaptations for X, LinkedIn, Facebook, Reddit, Threads, Instagram, Instagram Reels, YouTube Shorts, and Shopify, generate lead magnets (checklists, swipe files, frameworks), ingest any URL (YouTube videos, web articles, PDFs, audio files) into structured content, ultra-cheap turbo articles from 2 credits, generate short-form AI UGC viral videos with subtitles, and run fully automated content autopilot. Powered by Citedy.
Full-stack AI marketing toolkit — scout X/Twitter and Reddit for trending topics, discover and deep-analyze competitors, find content gaps, publish SEO- and GEO-optimized articles with AI illustrations and voice-over in 55 languages, create social media adaptations for X, LinkedIn, Facebook, Reddit, Threads, Instagram, Instagram Reels, YouTube Shorts, and Shopify, generate lead magnets (checklists, swipe files, frameworks), ingest any URL (YouTube videos, web articles, PDFs, audio files) into structured content, ultra-cheap turbo articles from 2 credits, generate short-form AI UGC viral videos with subtitles, and run fully automated content autopilot. Powered by Citedy.
API keys (prefixed citedy_agent_) are stored in the user's local agent
configuration. Keys authenticate only against Citedy API endpoints
(www.citedy.com/api/agent/*). All traffic is TLS-encrypted. Keys can
be revoked by the account owner at any time from the Citedy dashboard.
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)
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"]}
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:
Mode
Search
Credits
Speed
Turbo
No
2
5-15s
Turbo+
Yes
4
10-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)
Extension
Mini
Standard
Full
Pillar
Base article
7
12
25
40
+ Intelligence (default on)
+8
+8
+8
+8
+ Illustrations
+9
+18
+27
+36
+ Audio
+10
+20
+35
+55
Full package
34
58
95
139
Without extensions: same as before (mini=15, standard=20, full=33, pillar=48 credits).
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.
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)
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."
}
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)
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 POST
Your agent runs locally without a public URL
You want instant notification on events
You query results on demand after triggering a job
Events should trigger downstream automation
You only need results after a specific job completes
Rate Limits
Type
Limit
Scope
General
60 req/min
per agent
Scout
10 req/hr
X + Reddit combined
Gaps
10 req/hr
get + generate combined
Ingest
30 req/hr
per tenant
Lead Magnets
10 req/hr
per agent
Registration
10 req/hr
per IP
On 429, read retry_after from the body and X-RateLimit-Reset header.
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.
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.
