SEO Agentic Approval API Guide

Anything that spends credits waits for an approval, and this endpoint is how an agent collects that approval itself instead of waiting for a person. It is one GET request, it returns the codes for everything currently pending, and each code lasts four days.

What This Endpoint Is For

Your agent queues a crawl or a competitor research order through the private MCP and the order sits at pending approval. Without this API, somebody opens the dashboard and clicks approve.

With it, the loop closes in software. The MCP queues the operation, this endpoint hands back the approval code, the MCP approval_code tool submits that code, and the operation runs.

Before Your First Call

Two things live in the Agent Configuration card on your settings page. Generate an agent key there, then list the IP addresses your agent calls from, one per line. CIDR ranges work, so 198.51.100.0/24 covers a subnet.

The agent key is a bearer token with no second factor behind it, so treat it the way you would treat a password. Anything holding that key and calling from an allowed address can read every pending approval in your agency.

The Request

GET https://seolinkmap.com/api/agentic-approvals, with your agent key in the Authorization header as Authorization: Bearer {your_agent_key}. No parameters, no body.

What Comes Back

A success returns every operation that is pending approval, still has an unexpired code, and belongs to the agency that key resolves to. Each entry carries the project, the operation, the estimated credit cost, the code, and the moment that code dies.

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
}

Read estimated_credits before submitting anything. It is the number your agent should be checking against whatever budget you gave it, and it is the only warning you get before the credits are spent.

An empty pending_approvals array with total_count: 0 is the normal state. It means nothing is waiting, and it also means anything whose code has already expired has dropped out of the list rather than sitting there stale.

What Request Details Carries

request_details holds the parameters of the operation itself, and its shape depends on the operation type. Read it if your agent needs to decide whether to approve rather than approving whatever it finds.

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

The Three Errors

401 Unauthorized - Missing Authorization:

{
  "error": "Missing Authorization header"
}

The header was absent or did not start with Bearer . This is usually a client that sends the key in the wrong header.

401 Unauthorized - Invalid Key:

{
  "error": "Invalid agent key"
}

The key does not match any agent configuration. Check you copied the whole thing from Settings and that it was not regenerated since.

403 Forbidden - IP Restricted:

{
  "error": "IP not allowed"
}

The key is good and the address it called from is not on the allowlist. Cloud workers change addresses more often than people expect, so check the address the request actually came from before assuming the list is wrong.

Fitting It Into a Workflow

The full cycle is four steps: the MCP queues with queue_crawl, queue_competitor_research or create_new_project, this endpoint returns the code, the MCP approval_code tool submits it, and the work starts. Everything after that is normal - results land where they always land, and What Do I Do Next reads them the same way.

If you would rather not run a poller at all, an API key in Settings can carry an auto-approve switch that removes the approval step entirely. That is fewer moving parts and strictly less oversight, and which of those matters more is your call.

Keeping It Under Control

Codes expire four days after the operation is queued, which bounds how long a leaked response is worth anything. Keep the allowlist to addresses you recognize, and rotate the agent key on the same schedule you rotate anything else.

Approval automation means your agent is spending your credits without asking, and you remain responsible for what it decides. The queue in your dashboard is the record of every automated approval, and it is worth reading weekly until you trust what the agent is doing.