SEO Agentic Approval API Guide

API Overview and Purpose

The Agentic Approval API automates SEOLinkMap operation approvals through programmatic access. Your AI agents can retrieve approval codes for queued crawls, competitor research, and new project creation without manual intervention.

This API works with the Private MCP and Agentic SEO Workflows system to enable fully automated SEO operations.

Authentication Requirements

Authentication requires an agent key and IP allowlist configuration. Generate your agent key in the Settings page Agent Configuration section, then add your server's IP addresses to the allowlist field.

Endpoint Configuration

The approval endpoint uses GET https://seolinkmap.com/api/agentic-approvals with Bearer token authentication. Include your agent key in the Authorization header: Authorization: Bearer {your_agent_key}.

Response Format Details

Successful responses return pending approvals with structured data including operation details and approval codes. Each approval contains project information, operation type, estimated costs, and a time-limited approval code.

Success Response (200):

{
  "success": true,
  "agency_id": 123,
  "pending_approvals": [
    {
      "id": 456,
      "project": {
        "id": 789,
        "name": "Example Website",
        "domain": "example.com"
      },
      "operation": {
        "type": "crawl",
        "subtype": "full_site",
        "description": "Full site crawl and analysis"
      },
      "cost": {
        "estimated_credits": 250
      },
      "approval": {
        "code": "ABC123DEF",
        "expires_at": "2025-09-15 14:30:00"
      },
      "request_details": {
        "notes": "Updated crawl requested for site changes"
      },
      "created_at": "2025-09-14 12:00:00"
    }
  ],
  "total_count": 1
}

Request Details Structure

Request details contain operation-specific parameters that vary by operation type. The structure depends on whether the queued operation is a crawl, competitor research, or new project creation.

Crawl Operations:

"request_details": {
  "notes": "Updated crawl for recent site changes"
}

Competitor Research Operations:

"request_details": {
  "keywords": ["seo tools", "link analysis"],
  "tier": "basic",
  "notes": "Research for Q4 strategy"
}

New Project Operations:

"request_details": {
  "website": "https://newclient.com",
  "name": "New Client Project",
  "notes": "Initial client onboarding"
}

Error Handling Methods

401 Unauthorized - Missing Authorization:

{
  "error": "Missing Authorization header"
}

401 Unauthorized - Invalid Key:

{
  "error": "Invalid agent key"
}

403 Forbidden - IP Restricted:

{
  "error": "IP not allowed"
}

Verify your IP allowlist configuration includes your server's current address when encountering IP restriction errors.

Implementation Workflow

Implementation connects your Private MCP tools with automatic approval processing. Agents use queue_crawl, queue_competitor_research, or create_new_project to add operations, then retrieve approval codes through this API.

The complete workflow: Private MCP queues operations → Agentic API retrieves approval codes → MCP approval_code tool submits codes → operations execute automatically. This eliminates manual dashboard approval while maintaining full operational control.

Security Considerations

Agent key security requires careful management since approval access grants operational control. Store agent keys securely and restrict IP allowlists to known server addresses only.

Approval codes expire based on configured timeouts to limit exposure windows. Users maintain full responsibility for agent decisions and approval automation - monitor agent activities through the SEOLinkMap dashboard to track automated approvals and maintain oversight.