citedy-seo-agent

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}

• 30 credits

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. Async — poll GET /api/agent/gaps-status/{id}

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

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 article
• audio (bool, default false) — AI voice-over narration
• disable_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, 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.

List Articles

GET /api/agent/articles

• 0 credits

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 }
  ]
}

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"

1. POST /api/agent/autopilot with { "source_urls": ["https://example.com/ai-trends"], "size": "mini" }
2. Poll GET /api/agent/autopilot/{id} until done
3. 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"

1. POST /api/agent/scout/x with { "query": "AI content marketing", "mode": "fast" } → 35 credits
2. Pick the top trend from results
3. POST /api/agent/autopilot with { "topic": "<top trend>", "size": "standard" }
4. Poll until done, then adapt if user wants social posts

Reply to user:

Scanned X for "AI content marketing" — top 5 trends:

1. AI-generated video scripts outperform text posts (engagement +340%)
2. 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"

1. 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?"

1. 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