Agent Pilot

ScanTheLink Agent API

Private pilot API for trusted automation clients. Sign in at the dashboard to request Agent API beta access. Approved accounts can create one Basic-scan key from the dashboard; admins can also issue keys manually. Plaintext keys are never shown again after creation or rotation.

Authentication

Authorization: Bearer <agent_api_key>

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

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"])

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, meta, and optional error.

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.

Error Codes

• 401 agent_key_missing or agent_key_invalid: send a valid key in the Authorization header.
• 403 agent_key_paused, agent_key_revoked, agent_key_expired, or agent_scope_required: ask the account owner or ScanTheLink admin to review access.
• 402 pilot_credits_required: the key has no pilot credits remaining.
• 429 agent_rate_limit_exceeded: wait until the per-key rate-limit window resets.
• 400 invalid_target: the submitted URL or handle cannot be scanned.

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 LLM info

Common Errors

{
  "schema_version": "scanthelink.agent_error.v1",
  "request_id": "...",
  "error": {
    "code": "pilot_credits_required",
    "message": "No Agent Pilot credits remaining. Request new pilot credits from ScanTheLink.",
    "retryable": false,
    "action": "request_more_credits"
  }
}