Agent Pilot

ScanTheLink Agent API

Private pilot API for trusted automation clients. ScanTheLink collects public website and profile signals on our servers and returns structured findings your agent can use in client reports, sales conversations, outreach drafts, CRM notes, or internal triage without spending its own tokens to rediscover the same page facts. Basic scans stay fast and single-target; approved Deep/VIP scans can add bounded crawl_evidence for sampled URLs, indexability, structured data, canonical, hreflang, broken-link, redirect, index-exclusion, missing-meta, and duplicate-title signals.

{
  "agent_vip_scan_offer": {
    "amount": 1,
    "currency": "USD",
    "phase": "test_buildout",
    "starter_credits": 10,
    "starter_credit_reason": "test_service_give_feedback_find_bugs",
    "availability": "manual_approval_limited_capacity",
    "scope": [
      "more_urls_or_targeted_landing_page_group",
      "optional_js_render_check_when_useful_and_capacity_allows",
      "screenshot_evidence_bundle",
      "client_ready_summary_with_priorities_confidence_and_sales_context",
      "structured_json_plus_share_report_where_available",
      "manual_pilot_review_capacity"
    ],
    "excluded": [
      "public_payment_checkout",
      "unlimited_site_crawler",
      "backlink_keyword_database"
    ]
  }
}

What Agents Can Do With The Report

Your agent may transform the returned analysis for its own customer workflow: summarize it, translate it, rank opportunities, turn it into a sales pitch, build a proposal, prefill CRM fields, or combine it with the customer's context. ScanTheLink provides the scan data and signal extraction; your agent decides how to package it for the end customer.

Authentication

Authorization: Bearer <agent_api_key>

The fallback header X-Agent-API-Key is also accepted. Do not send keys in query parameters.

MCP Tool Server

MCP clients can call POST /api/mcp with the same Bearer Agent API key. The endpoint is JSON-RPC over HTTP, not a framework docs export, and exposes thin tools over Agent API v1: submit_scan, get_scan, and list_finding_types. The tools use the same Agent API rate limits, credit reservation, SSRF checks, redaction, and result schema as the endpoints below.

{
  "jsonrpc": "2.0",
  "id": "scan-1",
  "method": "tools/call",
  "params": {
    "name": "submit_scan",
    "arguments": {
      "target": "https://example.com",
      "scan_type": "auto",
      "scan_depth": "basic",
      "idempotency_key": "lead-123-example-com"
    }
  }
}

Create Scan

Use one stable Idempotency-Key per target attempt. Retrying the same key returns the original request instead of reserving another credit.

POST /api/v1/scans
Idempotency-Key: your-retry-safe-id
Content-Type: application/json

{
  "target": "https://example.com",
  "scan_type": "auto",
  "scan_depth": "basic"
}

Successful requests return 202 Accepted with agent_request_id, status_url, and remaining pilot credits.

Copy-Paste Examples

curl

curl -X POST "https://scanthelink.com/api/v1/scans" \
  -H "Authorization: Bearer stl_agent_your_key" \
  -H "Idempotency-Key: lead-123-example-com" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com","scan_type":"auto","scan_depth":"basic"}'

JavaScript fetch

const response = await fetch("https://scanthelink.com/api/v1/scans", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCANTHELINK_AGENT_KEY}`,
    "Idempotency-Key": "lead-123-example-com",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    target: "https://example.com",
    scan_type: "auto",
    scan_depth: "basic"
  })
});

const scan = await response.json();
console.log(scan.status_url);

Python requests

import os
import requests

response = requests.post(
    "https://scanthelink.com/api/v1/scans",
    headers={
        "Authorization": f"Bearer {os.environ['SCANTHELINK_AGENT_KEY']}",
        "Idempotency-Key": "lead-123-example-com",
    },
    json={
        "target": "https://example.com",
        "scan_type": "auto",
        "scan_depth": "basic",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["status_url"])

Small Batch Create

Approved agents can submit a small batch when each target is still a normal Agent API scan. Use a unique idempotency_key per item. Successful items reserve credits independently; rejected items do not.

POST /api/v1/scans/batch
Content-Type: application/json

{
  "source": "crm_agent",
  "campaign_id": "june-leads",
  "targets": [
    {
      "target": "https://example.com",
      "external_id": "lead-123",
      "idempotency_key": "lead-123-example-com"
    },
    {
      "target": "https://example.org",
      "external_id": "lead-124",
      "idempotency_key": "lead-124-example-org"
    }
  ]
}

The batch response returns accepted, rejected, remaining credits, and per-item status: accepted, reused, or rejected.

Poll Status

GET /api/v1/scans/{agent_request_id}

The response keeps the same top-level structure for pending, running, done, and failed states: schema_version, request_id, status, credits, signals, scores, findings, client_brief, client_safe_report, sales_talking_points, developer_tasks, evidence_summary, confidence, rescan_comparison, meta, and optional error. Deep/VIP results may include signals.crawl_evidence; Basic results keep it empty.

For spreadsheet workflows, call GET /api/v1/scans/{agent_request_id}/csv with the same Agent API key. The CSV uses structured findings fields such as finding_type, finding_id, severity, remediation, coverage, and confidence; profile exports keep monetary impact disabled.

Use client_safe_report for customer-facing or white-label agent output. It is structured for rewriting, translation, CRM notes, proposals, and client report views while preserving confidence limitations.

When a previous completed scan exists for the same Agent API key and exact target, rescan_comparison returns score_delta, monthly_loss_delta_eur, and fixed, regressed, and changed findings for follow-up reports and client conversations.

Credits And Limits

Invalid targets and blocked deep-scan requests do not reserve credits. Accepted scans reserve one credit. Reusing the same idempotency key does not reserve a second credit. Technical scan failures release the reserved credit. Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-Agent-Credits-Remaining.

The credits object includes low, threshold, and, when credits are low, event: "credits.low" plus action: "request_more_credits" so agents can route replenishment as an operator task without waiting for outbound webhooks.

Webhook Events

During the private pilot, admins can configure one public HTTPS webhook endpoint per Agent API key. Supported events are scan.completed, scan.failed, and credits.low. Webhook delivery is best-effort and audited; agents should still poll GET /api/v1/scans/{agent_request_id} as the source of truth.

Webhook payloads use scanthelink.agent_webhook.v1. Each request includes X-ScanTheLink-Event, X-ScanTheLink-Delivery, and X-ScanTheLink-Signature. The signature format is t=<unix_timestamp>,v1=<hmac_sha256>, computed over timestamp + "." + raw_body with the one-time signing secret shown when the webhook is configured.

Error And Retry Matrix

credits.low is an operator task, not a retry trigger. A workflow can continue while credits remain, but it should notify a human before the next batch runs out.

Agent Discovery Pages

• Website audit API for AI agents
• Client sales reporting with ScanTheLink
• Workflow integrations for n8n, Make, Zapier, and custom agents

Machine-Readable Files

• /llms.txt: short agent summary.
• /llms-full.txt: full agent-facing product, pricing, safety, and API context.
• /agent-action-schema.json: curated pilot action schema. This is not the private framework docs export.

Feedback

Use the Agent API section in the dashboard to tell us which endpoints, payload fields, callbacks, retry behavior, or pricing model your agent needs before this pilot becomes public.

Request Agent API beta Read full LLM info