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, a layout recalculation, a competitor research order, a prospector order, an AI visibility prompt or a new project through the private MCP, and the order sits at pending approval. Without this API, somebody opens the dashboard and clicks approve.

The MCP itself never charges your account. It queues work for a person to approve on the dashboard, and the charge happens at that approval. This endpoint is for the agency that deliberately wants its own approval automated: your script collects the codes and hands them to the MCP, and your system's approval counts the same as a click, with the same fees behind it.

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": null,
        "description": "Full site crawl of example.com\n\nNotes: Updated crawl requested for site changes"
      },
      "cost": {
        "estimated_credits": 250
      },
      "approval": {
        "code": "3f9a1c7e2b4d4f6a8e1c0b2d9a7f5e31",
        "expires_at": "2025-09-18 12:00:00"
      },
      "request_details": {
        "project_id": 789,
        "enhanced_crawl": 0
      },
      "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. Notes the agent attached when it queued the operation appear in the operation description, not here.

Crawl:

"request_details": {
  "project_id": 789,
  "enhanced_crawl": 0
}

Layout recalculation:

"request_details": {
  "project_id": 789
}

Competitor research (tier is standard or premium):

"request_details": {
  "keywords": ["seo tools", "link analysis"],
  "tier": "standard",
  "keyword_count": 2,
  "project_id": 789,
  "serp_gl": "us",
  "serp_location": ""
}

Backlink Prospector:

"request_details": {
  "keywords": ["seo tools"],
  "keyword_count": 1,
  "project_id": 789
}

AI visibility:

"request_details": {
  "prompt": "best appointment scheduling software for dentists",
  "prompt_type": "unbranded",
  "engine": "google_aio",
  "project_id": 789,
  "country": "US",
  "state": "",
  "visibility_type": "standard"
}

AI visibility retire:

"request_details": {
  "prompt_id": 12,
  "visibility_id": 34,
  "prompt": "best appointment scheduling software for dentists",
  "project_id": 789
}

New project:

"request_details": {
  "name": "New Client Project",
  "domain": "newclient.com",
  "original_input": "https://newclient.com"
}

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_layout, queue_competitor_research, queue_backlink_prospector, queue_ai_visibility, queue_ai_visibility_retire 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.

What Does the Math Say
About Your Site?

Finding out is free and takes minutes.

Recent Articles

Getting Started with Your Dashboard

Your Private MCP URL, the left menu, and what a new LinkMap account should do first. A short tour of the dashboard and where each part of the platform lives.

What Do I Do Next with My SEO in Plain English

Stop deciding what to work on. Every SEOLinkMap dashboard tells you the next SEO action to take, in order and in plain English, built from your own data.

SEOLinkMap Account and Integration Settings Guide

Settings is four sections: your account, everything your agency shares, the integrations for the project you are on, and your password and two-factor login.

Website Structure and Page Depth Explained

Page depth is how many clicks it takes to reach a page from your homepage, and the visualization shows depth and content clusters as shapes instead of rows.

Share LinkMap Projects with Clients Using Guest Links

Share a read-only LinkMap with clients: custom URL, required expiry, and toggles for the audit report and snapshot timeline.

SEO Report Builder for Client Reporting Dashboards

Drag widgets onto a page, click each one to set it up, and send your client a link that shows current numbers every time they open it. Free with every account.

Popular Articles

Connect Your AI Chat Tool to MCP Servers

Connect an MCP server to Claude, ChatGPT or VS Code by pasting one URL into connector settings. Current setup steps for each AI platform, tested and free.

SEOLinkMap MCP Server Complete Guide

Every SEOLinkMap account includes a private MCP server. Connect Claude or ChatGPT and ask questions of your own crawl, rankings, traffic and research data.

SEO Report Builder for Client Reporting Dashboards

Drag widgets onto a page, click each one to set it up, and send your client a link that shows current numbers every time they open it. Free with every account.

SEO Analytics and Reporting Dashboard Guide

Three charts put what you changed on the same timeline as what Google did about it: a calendar heat map, a page quadrant and a trend line with action pins.

Agency Team Roles And Permissions

SEOLinkMap agency teams get five user roles, three permission layers and no per seat fee on any tier. Set up roles and project access for your whole team.

How to Set Up an SEO Project in SEOLinkMap

A project comes before the visualization and the optimization tools, and its domain setting decides which version of your pages LinkMap analyzes.

Other Categories

Chat with your own SEO data
Connect Claude, ChatGPT, or any AI chat to your private MCP server and ask "what should I fix first?" It answers from your data - crawls, rankings, competitor research, backlinks - and can even queue new analysis for you.

Wire it into your agentic system and it can re-measure a page while your agents work on it - change, measure, repeat.

Free and paid tiers have your own private MCP server alongside the dashboard you'd expect.

No account yet? The public server below answers anything about features, pricing, or support - and will pull a real SERP correlation analysis, methodology and raw data included.
https://seolinkmap.com/mcp