# Citedy Agentic Interface

This file is machine-oriented and generated automatically.
Do not edit manually. Regenerate with `npm run agentic-docs:generate`.

## Canonical Endpoints

- REST base: `https://www.citedy.com`
- MCP endpoint: `https://mcp.citedy.com/mcp`
- Skill file: `https://www.citedy.com/skill.md`
- Human API portal: `https://www.citedy.com/developer`

## Authentication

- Header: `Authorization: Bearer <citedy_agent_...>`
- Content type: `application/json`

## Snapshot

- API: **Citedy Agent API** (version `1.0.0`)
- REST operations in OpenAPI: **68**
- MCP tools: **58**
- Agent action templates: **69**

## Quickstart: REST

```bash
curl -X POST https://www.citedy.com/api/agent/autopilot \
  -H "Authorization: Bearer citedy_agent_..." \
  -H "Content-Type: application/json" \
  -d '{"topic":"MCP adoption 2026","size":"standard"}'
```

## Quickstart: MCP

```json
{
  "mcpServers": {
    "citedy": {
      "url": "https://mcp.citedy.com/mcp",
      "headers": { "Authorization": "Bearer citedy_agent_..." }
    }
  }
}
```

## Operational Playbooks

| Command | Goal | Tools |
|---|---|---|
| `/status` | Return actionable operational readiness with concrete fix links. | `agent.status`, `agent.me` |
| `/gaps` | Generate and retrieve fresh content gap opportunities. | `gaps.generate`, `gaps.list` |
| `/write` | Generate an article, poll until it finishes, then create social adaptations. | `article.generate`, `article.get`, `adapt.generate` |
| `/shorts` | Generate shorts and poll until final video URL is ready. | `shorts.generate`, `shorts.get` |
| `/knowledge` | Load product knowledge and verify readiness impact. | `products.create`, `products.search`, `agent.status` |

### /status

Return actionable operational readiness with concrete fix links.

1. Call `agent.status` (`GET /api/agent/status`) - Fetch the single operational snapshot (billing, socials, knowledge, schedule, actions).
2. Call `agent.me` (`GET /api/agent/me`) - Optionally enrich with limits and referral metadata.
   Optional step.
Output checklist:
- summary.operational_status, ready_to_create, ready_to_publish
- billing.credits_available + billing.status + topup_url
- social.connected_count + connect_url
- knowledge.documents_count + add_documents_url
- schedule.scheduled_7d + calendar_url
- prioritized actions[] with url

### /gaps

Generate and retrieve fresh content gap opportunities.

1. Call `gaps.generate` (`POST /api/agent/gaps/generate`) - Start gap generation from competitor URLs.

   Input example:

```json
{
  "competitor_urls": [
    "https://example-competitor.com",
    "https://another-competitor.com"
  ]
}
```

2. Call `gaps.list` (`GET /api/agent/gaps`) - Read saved gap results for summarization.
Output checklist:
- top opportunities with score/priority
- short rationale per opportunity
- suggested next command (/write or article.generate)

### /write

Generate an article, poll until it finishes, then create social adaptations.

1. Call `article.generate` (`POST /api/agent/autopilot`) - Start article generation via autopilot and capture the returned article job id.

   Input example:

```json
{
  "topic": "MCP adoption 2026",
  "size": "standard",
  "mode": "turbo"
}
```

2. Call `article.get` (`GET /api/agent/articles/{id}`) - Poll the queued article by id until status is completed or failed.
   Poll every 10s until status in [completed, failed].

   Input example:

```json
{
  "id": "00000000-0000-0000-0000-000000000000"
}
```

3. Call `adapt.generate` (`POST /api/agent/adapt`) - Generate social variants. If trust level is autopilot and accounts are connected, posting can happen automatically.

   Input example:

```json
{
  "article_id": "00000000-0000-0000-0000-000000000000",
  "platforms": [
    "linkedin",
    "x_thread"
  ],
  "include_ref_link": true
}
```

Output checklist:
- article id + terminal status
- headline summary after article.get reaches completed
- adaptations by platform with char counts
- published=true/false per platform

### /shorts

Generate shorts and poll until final video URL is ready.

1. Call `shorts.generate` (`POST /api/agent/shorts`) - Start shorts generation.

   Input example:

```json
{
  "prompt": "Explain why MCP improves developer productivity in 20 seconds",
  "avatar_url": "https://download.citedy.com/avatars/example.png",
  "duration": 15,
  "resolution": "720p",
  "aspect_ratio": "9:16"
}
```

2. Call `shorts.get` (`GET /api/agent/shorts/{id}`) - Poll generation status until terminal state.
   Poll every 10s until status in [completed, failed].

   Input example:

```json
{
  "id": "00000000-0000-0000-0000-000000000000"
}
```

Output checklist:
- status terminal state (completed/failed)
- video_url when completed
- clear retry advice when failed

### /knowledge

Load product knowledge and verify readiness impact.

1. Call `products.create` (`POST /api/agent/products`) - Upload one product knowledge document.

   Input example:

```json
{
  "title": "Product positioning",
  "content": "Citedy helps teams automate SEO+GEO articles and social distribution.",
  "source_type": "manual"
}
```

2. Call `products.search` (`POST /api/agent/products/search`) - Verify that knowledge chunks are retrievable.

   Input example:

```json
{
  "query": "pricing",
  "limit": 5
}
```

3. Call `agent.status` (`GET /api/agent/status`) - Re-check operational readiness after knowledge upload.
Output checklist:
- knowledge documents count increased
- search hits show indexed chunks
- updated readiness flags from agent.status

## Decision Rules

| When | Then |
|---|---|
| User asks /status or readiness | Call agent.status (not agent.health) and return actionable blockers with URLs. |
| billing.status is low or empty | Warn before costly tools and include billing.topup_url (fallback: dashboard billing URL). |
| social.connected_count is 0 | Do not promise publish outcome; direct user to social.connect_url. |
| knowledge.documents_count is 0 and task needs product context | Recommend products.create or ingest.create and include add_documents_url. |
| Tool returns processing or exposes operation.poll_tool | Auto-poll every 10s until terminal status, then summarize result. |
| HTTP 429 returned | Honor retry_after and X-RateLimit-Reset before retrying. |

## Error Policy

| Status | Meaning | Action |
|---|---|---|
| 401 | Invalid or missing API key | Stop and ask user to refresh agent key in dashboard settings. |
| 402 | Insufficient credits | Provide top-up URL: https://www.citedy.com/dashboard/billing |
| 403 | Agent paused or key revoked | Stop mutating actions and ask user to restore agent access. |
| 429 | Rate limited | Back off using retry metadata and retry once window resets. |
| 500 | Server-side error | Retry once with jitter; if still failing, return concise incident context. |

## /status Response Template

Return this structure when user asks `/status`:

```text
Status: <summary.operational_status>
Create Ready: <summary.ready_to_create>
Publish Ready: <summary.ready_to_publish>
Credits: <billing.credits_available> (<billing.status>) -> <billing.topup_url>
Social: <social.connected_count> connected -> <social.connect_url>
Knowledge: <knowledge.documents_count> docs -> <knowledge.add_documents_url>
Schedule 7d: <schedule.scheduled_7d> -> <schedule.calendar_url>
Top Actions:
1) <actions[0].title> -> <actions[0].url>
2) <actions[1].title> -> <actions[1].url>
```

## Machine Contract (Strict JSON)

Use this JSON block for deterministic orchestration and parsing:

```json
{
  "contract_version": "2026-03-01",
  "default_poll_interval_seconds": 10,
  "endpoints": {
    "rest_base": "https://www.citedy.com",
    "mcp": "https://mcp.citedy.com/mcp",
    "skill": "https://www.citedy.com/skill.md"
  },
  "status_contract": {
    "command": "/status",
    "tool": {
      "name": "agent.status",
      "endpoint": "GET /api/agent/status"
    },
    "required_sections": [
      {
        "key": "summary",
        "required_fields": [
          "operational_status",
          "ready_to_create",
          "ready_to_publish"
        ]
      },
      {
        "key": "billing",
        "required_fields": [
          "credits_available",
          "status",
          "topup_url"
        ]
      },
      {
        "key": "social",
        "required_fields": [
          "connected_count",
          "connect_url"
        ]
      },
      {
        "key": "knowledge",
        "required_fields": [
          "documents_count",
          "add_documents_url"
        ]
      },
      {
        "key": "schedule",
        "required_fields": [
          "scheduled_7d",
          "calendar_url"
        ]
      },
      {
        "key": "actions[]",
        "required_fields": [
          "severity",
          "title",
          "url"
        ]
      }
    ],
    "fallback_urls": {
      "billing": "https://www.citedy.com/dashboard/billing",
      "integrations": "https://www.citedy.com/dashboard/settings?section=account&tab=integrations",
      "knowledge": "https://www.citedy.com/dashboard/settings?section=blog&tab=knowledge",
      "calendar": "https://www.citedy.com/dashboard/calendar"
    }
  },
  "decision_rules": [
    {
      "when": "User asks /status or readiness",
      "then": "Call agent.status (not agent.health) and return actionable blockers with URLs."
    },
    {
      "when": "billing.status is low or empty",
      "then": "Warn before costly tools and include billing.topup_url (fallback: dashboard billing URL)."
    },
    {
      "when": "social.connected_count is 0",
      "then": "Do not promise publish outcome; direct user to social.connect_url."
    },
    {
      "when": "knowledge.documents_count is 0 and task needs product context",
      "then": "Recommend products.create or ingest.create and include add_documents_url."
    },
    {
      "when": "Tool returns processing or exposes operation.poll_tool",
      "then": "Auto-poll every 10s until terminal status, then summarize result."
    },
    {
      "when": "HTTP 429 returned",
      "then": "Honor retry_after and X-RateLimit-Reset before retrying."
    }
  ],
  "error_policy": [
    {
      "status": 401,
      "meaning": "Invalid or missing API key",
      "action": "Stop and ask user to refresh agent key in dashboard settings."
    },
    {
      "status": 402,
      "meaning": "Insufficient credits",
      "action": "Provide top-up URL: https://www.citedy.com/dashboard/billing"
    },
    {
      "status": 403,
      "meaning": "Agent paused or key revoked",
      "action": "Stop mutating actions and ask user to restore agent access."
    },
    {
      "status": 429,
      "meaning": "Rate limited",
      "action": "Back off using retry metadata and retry once window resets."
    },
    {
      "status": 500,
      "meaning": "Server-side error",
      "action": "Retry once with jitter; if still failing, return concise incident context."
    }
  ],
  "playbooks": [
    {
      "id": "status_audit",
      "command": "/status",
      "triggers": [
        "/status",
        "status",
        "readiness"
      ],
      "goal": "Return actionable operational readiness with concrete fix links.",
      "steps": [
        {
          "tool": "agent.status",
          "endpoint": "GET /api/agent/status",
          "purpose": "Fetch the single operational snapshot (billing, socials, knowledge, schedule, actions).",
          "optional": false,
          "input_example": null,
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        },
        {
          "tool": "agent.me",
          "endpoint": "GET /api/agent/me",
          "purpose": "Optionally enrich with limits and referral metadata.",
          "optional": true,
          "input_example": null,
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        }
      ],
      "output_checklist": [
        "summary.operational_status, ready_to_create, ready_to_publish",
        "billing.credits_available + billing.status + topup_url",
        "social.connected_count + connect_url",
        "knowledge.documents_count + add_documents_url",
        "schedule.scheduled_7d + calendar_url",
        "prioritized actions[] with url"
      ]
    },
    {
      "id": "gaps_scan",
      "command": "/gaps",
      "triggers": [
        "/gaps",
        "content gaps",
        "quick scan"
      ],
      "goal": "Generate and retrieve fresh content gap opportunities.",
      "steps": [
        {
          "tool": "gaps.generate",
          "endpoint": "POST /api/agent/gaps/generate",
          "purpose": "Start gap generation from competitor URLs.",
          "optional": false,
          "input_example": {
            "competitor_urls": [
              "https://example-competitor.com",
              "https://another-competitor.com"
            ]
          },
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        },
        {
          "tool": "gaps.list",
          "endpoint": "GET /api/agent/gaps",
          "purpose": "Read saved gap results for summarization.",
          "optional": false,
          "input_example": null,
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        }
      ],
      "output_checklist": [
        "top opportunities with score/priority",
        "short rationale per opportunity",
        "suggested next command (/write or article.generate)"
      ]
    },
    {
      "id": "article_and_adapt",
      "command": "/write",
      "triggers": [
        "/write",
        "create article",
        "article + social"
      ],
      "goal": "Generate an article, poll until it finishes, then create social adaptations.",
      "steps": [
        {
          "tool": "article.generate",
          "endpoint": "POST /api/agent/autopilot",
          "purpose": "Start article generation via autopilot and capture the returned article job id.",
          "optional": false,
          "input_example": {
            "topic": "MCP adoption 2026",
            "size": "standard",
            "mode": "turbo"
          },
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        },
        {
          "tool": "article.get",
          "endpoint": "GET /api/agent/articles/{id}",
          "purpose": "Poll the queued article by id until status is completed or failed.",
          "optional": false,
          "input_example": {
            "id": "00000000-0000-0000-0000-000000000000"
          },
          "poll_every_seconds": 10,
          "until_status_in": [
            "completed",
            "failed"
          ],
          "notes": null
        },
        {
          "tool": "adapt.generate",
          "endpoint": "POST /api/agent/adapt",
          "purpose": "Generate social variants. If trust level is autopilot and accounts are connected, posting can happen automatically.",
          "optional": false,
          "input_example": {
            "article_id": "00000000-0000-0000-0000-000000000000",
            "platforms": [
              "linkedin",
              "x_thread"
            ],
            "include_ref_link": true
          },
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        }
      ],
      "output_checklist": [
        "article id + terminal status",
        "headline summary after article.get reaches completed",
        "adaptations by platform with char counts",
        "published=true/false per platform"
      ]
    },
    {
      "id": "shorts_pipeline",
      "command": "/shorts",
      "triggers": [
        "/shorts",
        "video",
        "short-form video"
      ],
      "goal": "Generate shorts and poll until final video URL is ready.",
      "steps": [
        {
          "tool": "shorts.generate",
          "endpoint": "POST /api/agent/shorts",
          "purpose": "Start shorts generation.",
          "optional": false,
          "input_example": {
            "prompt": "Explain why MCP improves developer productivity in 20 seconds",
            "avatar_url": "https://download.citedy.com/avatars/example.png",
            "duration": 15,
            "resolution": "720p",
            "aspect_ratio": "9:16"
          },
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        },
        {
          "tool": "shorts.get",
          "endpoint": "GET /api/agent/shorts/{id}",
          "purpose": "Poll generation status until terminal state.",
          "optional": false,
          "input_example": {
            "id": "00000000-0000-0000-0000-000000000000"
          },
          "poll_every_seconds": 10,
          "until_status_in": [
            "completed",
            "failed"
          ],
          "notes": null
        }
      ],
      "output_checklist": [
        "status terminal state (completed/failed)",
        "video_url when completed",
        "clear retry advice when failed"
      ]
    },
    {
      "id": "knowledge_bootstrap",
      "command": "/knowledge",
      "triggers": [
        "/knowledge",
        "product docs",
        "upload docs"
      ],
      "goal": "Load product knowledge and verify readiness impact.",
      "steps": [
        {
          "tool": "products.create",
          "endpoint": "POST /api/agent/products",
          "purpose": "Upload one product knowledge document.",
          "optional": false,
          "input_example": {
            "title": "Product positioning",
            "content": "Citedy helps teams automate SEO+GEO articles and social distribution.",
            "source_type": "manual"
          },
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        },
        {
          "tool": "products.search",
          "endpoint": "POST /api/agent/products/search",
          "purpose": "Verify that knowledge chunks are retrievable.",
          "optional": false,
          "input_example": {
            "query": "pricing",
            "limit": 5
          },
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        },
        {
          "tool": "agent.status",
          "endpoint": "GET /api/agent/status",
          "purpose": "Re-check operational readiness after knowledge upload.",
          "optional": false,
          "input_example": null,
          "poll_every_seconds": null,
          "until_status_in": null,
          "notes": null
        }
      ],
      "output_checklist": [
        "knowledge documents count increased",
        "search hits show indexed chunks",
        "updated readiness flags from agent.status"
      ]
    }
  ]
}
```

## MCP Tools

See full list: `https://www.citedy.com/mcp-tools.md`

| Tool | Endpoint |
|---|---|
| `adapt.generate` | `POST /api/agent/adapt` |
| `agent.health` | `GET /api/agent/health` |
| `agent.me` | `GET /api/agent/me` |
| `agent.status` | `GET /api/agent/status` |
| `article.delete` | `DELETE /api/agent/articles/{id}` |
| `article.generate` | `POST /api/agent/autopilot` |
| `article.get` | `GET /api/agent/articles/{id}` |
| `article.list` | `GET /api/agent/articles` |
| `article.publish` | `POST /api/agent/articles/{id}/publish` |
| `article.unpublish` | `PATCH /api/agent/articles/{id}` |
| `brand.scan` | `POST /api/agent/tools/brand-scan` |
| `brand.scan.get` | `GET /api/agent/tools/brand-scan/{id}` |
| `competitors.discover` | `POST /api/agent/competitors/discover` |
| `competitors.scout` | `POST /api/agent/competitors/scout` |
| `gaps.generate` | `POST /api/agent/gaps/generate` |
| `gaps.list` | `GET /api/agent/gaps` |
| `gsc.report` | `GET /api/agent/gsc/report` |
| `ingest.batch` | `POST /api/agent/ingest/batch` |
| `ingest.content.get` | `GET /api/agent/ingest/{id}/content` |
| `ingest.create` | `POST /api/agent/ingest` |
| `ingest.get` | `GET /api/agent/ingest/{id}` |
| `leadmagnet.archive` | `PATCH /api/agent/lead-magnets/{id}` |
| `leadmagnet.generate` | `POST /api/agent/lead-magnets` |
| `leadmagnet.get` | `GET /api/agent/lead-magnets/{id}` |
| `leadmagnet.publish` | `PATCH /api/agent/lead-magnets/{id}` |
| `personas.list` | `GET /api/agent/personas` |
| `products.create` | `POST /api/agent/products` |
| `products.delete` | `DELETE /api/agent/products/{id}` |
| `products.list` | `GET /api/agent/products` |
| `products.search` | `POST /api/agent/products/search` |
| `schedule.gaps` | `GET /api/agent/schedule/gaps` |
| `schedule.list` | `GET /api/agent/schedule` |
| `scout.reddit` | `POST /api/agent/scout/reddit` |
| `scout.reddit.result` | `GET /api/agent/scout/reddit/{runId}` |
| `scout.x` | `POST /api/agent/scout/x` |
| `scout.x.result` | `GET /api/agent/scout/x/{runId}` |
| `seo.headings.check` | `POST /api/agent/tools/headings` |
| `seo.internal_links.plan` | `POST /api/agent/tools/internal-links` |
| `seo.links.analyze` | `POST /api/agent/tools/links` |
| `seo.meta_tags.check` | `POST /api/agent/tools/meta-tags` |
| `seo.og_image.generate` | `POST /api/agent/tools/og-image` |
| `seo.og.preview` | `POST /api/agent/tools/og-preview` |
| `seo.robots.check` | `POST /api/agent/tools/robots` |
| `seo.schema.validate` | `POST /api/agent/tools/schema-validate` |
| `seo.sitemap.check` | `POST /api/agent/tools/sitemap` |
| `session.create` | `POST /api/agent/session` |
| `settings.get` | `GET /api/agent/settings` |
| `shorts.avatar` | `POST /api/agent/shorts/avatar` |
| `shorts.generate` | `POST /api/agent/shorts` |
| `shorts.get` | `GET /api/agent/shorts/{id}` |
| `shorts.merge` | `POST /api/agent/shorts/merge` |
| `shorts.publish` | `POST /api/agent/shorts/publish` |
| `shorts.script` | `POST /api/agent/shorts/script` |
| `social.publish` | `POST /api/agent/publish` |
| `webhooks.delete` | `DELETE /api/agent/webhooks/{id}` |
| `webhooks.deliveries` | `GET /api/agent/webhooks/deliveries` |
| `webhooks.list` | `GET /api/agent/webhooks` |
| `webhooks.register` | `POST /api/agent/webhooks` |

## REST Operations

| Method | Path | Summary |
|---|---|---|
| `POST` | `/api/agent/adapt` | Generate social adaptations |
| `POST` | `/api/agent/approve` | Approve pending registration |
| `GET` | `/api/agent/articles` | List articles |
| `GET` | `/api/agent/articles/{id}` | Get queued article generation status or result by ID |
| `PATCH` | `/api/agent/articles/{id}` | Unpublish an article (revert to draft) |
| `DELETE` | `/api/agent/articles/{id}` | Permanently delete an article |
| `POST` | `/api/agent/articles/{id}/publish` | Publish a draft article |
| `POST` | `/api/agent/autopilot` | Generate article |
| `POST` | `/api/agent/competitors/discover` | Discover competitors by keywords |
| `POST` | `/api/agent/competitors/scout` | Analyze a competitor domain |
| `GET` | `/api/agent/gaps` | List content gaps |
| `POST` | `/api/agent/gaps/generate` | Generate content gaps |
| `GET` | `/api/agent/gsc/report` | Get GSC performance report |
| `GET` | `/api/agent/health` | Health check |
| `PUT` | `/api/agent/image-style` | Set illustration style preset |
| `GET` | `/api/agent/ingest` | List ingestion jobs |
| `POST` | `/api/agent/ingest` | Create ingestion job |
| `POST` | `/api/agent/ingest/batch` | Batch create ingestion jobs |
| `GET` | `/api/agent/ingest/{id}` | Poll ingestion job status |
| `GET` | `/api/agent/ingest/{id}/content` | Download raw ingested content |
| `POST` | `/api/agent/lead-magnets` | Generate lead magnet |
| `GET` | `/api/agent/lead-magnets/{id}` | Get lead magnet status/details |
| `PATCH` | `/api/agent/lead-magnets/{id}` | Publish or archive lead magnet |
| `GET` | `/api/agent/lead-magnets/{id}/wait` | Long-poll wait for lead magnet completion |
| `GET` | `/api/agent/me` | Get agent info, balance and limits |
| `GET` | `/api/agent/pending/{id}` | Check pending registration status |
| `GET` | `/api/agent/personas` | List available personas |
| `POST` | `/api/agent/post` | Create micro-content post with social adaptations |
| `GET` | `/api/agent/products` | List product knowledge documents |
| `POST` | `/api/agent/products` | Upload product knowledge document |
| `POST` | `/api/agent/products/search` | Search product knowledge documents |
| `DELETE` | `/api/agent/products/{id}` | Delete product knowledge document by ID |
| `POST` | `/api/agent/publish` | Publish, schedule, cancel, or direct-publish (as-is) social content |
| `POST` | `/api/agent/register` | Create pending agent registration |
| `POST` | `/api/agent/rotate-key` | Rotate current agent API key |
| `POST` | `/api/agent/scan` | Scan trends via xAI Grok (experimental) |
| `GET` | `/api/agent/schedule` | Get scheduled content timeline |
| `GET` | `/api/agent/schedule/gaps` | Identify days with fewer posts than target |
| `GET` | `/api/agent/schedule/suggest` | Get recommended posting time slots |
| `POST` | `/api/agent/scout/reddit` | Run Reddit scout |
| `GET` | `/api/agent/scout/reddit/{runId}` | Poll Reddit scout result |
| `POST` | `/api/agent/scout/x` | Run X/Twitter scout |
| `GET` | `/api/agent/scout/x/{runId}` | Poll X scout result |
| `POST` | `/api/agent/session` | Create and start autopilot session |
| `GET` | `/api/agent/settings` | Get agent preferences and configuration |
| `PUT` | `/api/agent/settings` | Update agent preferences (partial update) |
| `POST` | `/api/agent/shorts` | Generate short-form video |
| `POST` | `/api/agent/shorts/avatar` | Generate shorts avatar |
| `POST` | `/api/agent/shorts/merge` | Merge shorts videos and add subtitles |
| `POST` | `/api/agent/shorts/publish` | Publish short video to YouTube Shorts and/or Instagram Reels |
| `POST` | `/api/agent/shorts/script` | Generate shorts script |
| `GET` | `/api/agent/shorts/{id}` | Get shorts generation status by ID |
| `GET` | `/api/agent/status` | Get operational agent status |
| `POST` | `/api/agent/tools/brand-scan` | Start async AI brand visibility scan |
| `GET` | `/api/agent/tools/brand-scan/{id}` | Get async brand scan status/result |
| `POST` | `/api/agent/tools/headings` | Analyze heading hierarchy |
| `POST` | `/api/agent/tools/internal-links` | Plan internal links from page + targets |
| `POST` | `/api/agent/tools/links` | Analyze page links |
| `POST` | `/api/agent/tools/meta-tags` | Analyze page meta tags |
| `POST` | `/api/agent/tools/og-image` | Generate branded Open Graph image |
| `POST` | `/api/agent/tools/og-preview` | Extract Open Graph/Twitter preview metadata |
| `POST` | `/api/agent/tools/robots` | Analyze robots.txt directives |
| `POST` | `/api/agent/tools/schema-validate` | Validate page JSON-LD schema markup |
| `POST` | `/api/agent/tools/sitemap` | Check sitemap availability and robots.txt hints |
| `GET` | `/api/agent/webhooks` | List webhook endpoints |
| `POST` | `/api/agent/webhooks` | Register webhook endpoint |
| `GET` | `/api/agent/webhooks/deliveries` | List webhook delivery history |
| `DELETE` | `/api/agent/webhooks/{id}` | Delete webhook endpoint |

## Source Artifacts

- `openapi/agent-api.openapi.json`
- `lib/mcp/tool-definitions.ts`
- `citedy-seo-agent/autogpt/actions.json`