| name | Citedy SEO Agent |
| description | Give your AI agent SEO superpowers — scout X/Reddit trends, discover and analyze competitors, find content gaps, publish optimized articles with AI illustrations and voice-over in 55 languages, create social media adaptations, and run automated content sessions. |
Citedy SEO Agent — Skill Instructions
You are now connected to Citedy, an AI-powered SEO content platform.
Base URL: https://www.citedy.com
When to Activate
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
- set up automated content sessions (cron-based article generation)
- 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.
Commands
All requests require Authorization: Bearer <api_key>.
Scout X/Twitter
POST /api/agent/scout/x
{"query": "...", "mode": "fast|ultimate", "limit": 20}
fast = 35 credits, ultimate = 70 credits
Scout Reddit
POST /api/agent/scout/reddit
{"subreddits": ["marketing", "SEO"], "query": "...", "limit": 20}
Get Content Gaps
GET /api/agent/gaps
Generate Content Gaps
POST /api/agent/gaps/generate
{"competitor_urls": ["https://competitor1.com", "https://competitor2.com"]}
- 40 credits. Async — poll
GET /api/agent/gaps-status/{id}
Discover Competitors
POST /api/agent/competitors/discover
{"keywords": ["ai content marketing", "automated blogging"]}
Analyze Competitor
POST /api/agent/competitors/scout
{"domain": "https://competitor.com", "mode": "fast|ultimate"}
fast = 25 credits, ultimate = 50 credits
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",
"illustrations": true,
"audio": true,
"disable_competition": false
}
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)language — ISO code, default "en"illustrations (bool, default false) — AI-generated images injected into articleaudio (bool, default false) — AI voice-over narrationdisable_competition (bool, default false) — skip SEO competition analysis, saves 8 credits
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. Articles are auto-published and the URL works immediately.
/api/agent/me also returns blog_url — the tenant's blog root URL.
Async — poll GET /api/agent/autopilot/{id}
Extension Costs
| 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).
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
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, and x_thread 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
}
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, pillardisable_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.
List Articles
GET /api/agent/articles
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 URLtenant_balance — current credits + status (healthy/low/empty)rate_limits — remaining requests per categoryreferral — { code, url } for attributing signupsconnected_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 }
]
}
Use connected_platforms to decide which platforms to pass to /api/agent/adapt for auto-publishing.
Workflows
Primary: URL → Article → Adapt
Turn any web page into an SEO article with social media posts:
1. GET /api/agent/me → get referral URL + connected platforms
2. POST /api/agent/autopilot { "source_urls": ["https://..."] } → poll until done → get article_id
3. POST /api/agent/adapt { "article_id": "...", "platforms": ["linkedin", "x_thread"], "include_ref_link": true }
Set-and-Forget: Session → Cron → Adapt
Automate content generation on a schedule:
1. POST /api/agent/session { "categories": ["..."], "interval_minutes": 720 }
2. Periodically: GET /api/agent/articles → find new articles
3. POST /api/agent/adapt for each new article
Examples
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" }- Poll
GET /api/agent/autopilot/{id} until done
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)
Choosing the right path
| User intent | Best path | Why |
|---|
| "Write about this link" | source_urls | Lowest effort, source material provided |
| "Write about AI marketing" | topic | Direct topic, no scraping needed |
| "What's trending on X?" | scout → autopilot | Discover topics first, then generate |
| "Find gaps vs competitor.com" | gaps → autopilot | Data-driven content strategy |
| "Post 2 articles daily" | session | Set-and-forget automation |
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.
API Quick Reference
| Endpoint | Method | Cost |
|---|
/api/agent/register | POST | free |
/api/agent/me | GET | free |
/api/agent/scout/x | POST | 35-70 credits |
/api/agent/scout/reddit | POST | 30 credits |
/api/agent/gaps | GET | free |
/api/agent/gaps/generate | POST | 40 credits |
/api/agent/gaps-status/{id} | GET | free |
/api/agent/competitors/discover | POST | 20 credits |
/api/agent/competitors/scout | POST | 25-50 credits |
/api/agent/autopilot | POST | 7-139 credits |
/api/agent/autopilot/{id} | GET | free |
/api/agent/adapt | POST | ~5 credits/platform |
/api/agent/session | POST | free (articles billed on generation) |
/api/agent/articles | GET | free |
1 credit = $0.01 USD
Rate Limits
| Type | Limit | Scope |
|---|
| General | 60 req/min | per agent |
| Scout | 10 req/hr | X + Reddit combined |
| Gaps | 10 req/hr | get + generate combined |
| 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 (autopilot, gaps/generate), automatically poll 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
| Status | Meaning | Action |
|---|
| 401 | Invalid/missing API key | Re-run setup flow |
| 402 | Insufficient credits | Tell user to top up at https://www.citedy.com/dashboard/billing |
| 403 | Agent paused/revoked | Tell user to check agent status in dashboard |
| 429 | Rate limited | Wait retry_after seconds, then retry |
| 500 | Server error | Retry once after 5s, then report to user |
Citedy SEO Agent Skill v2.1.0
