Agent Adoption

REST endpoints for Agent Adoption. Base URL https://api.competlab.com; every request needs a CL-API-Key header (see Authentication). Responses wrap in { item } or { items }; errors in { error }.

Start an async agent-adoption scan

POST/v1/tools/agent-adoption/scans

Start an asynchronous AI agent-adoption scan for a public domain. Runs 25 checks across four categories — discoverability (robots.txt, sitemap.xml, Link headers), accessControl (AI bot rules, content signals, web-bot-auth, robots-allow-all), contentReadability (/llms.txt, markdown negotiation, rendering strategy, page size, redirects, agents.md, cache headers), and agentEndpoints (OpenAPI catalog, OAuth discovery, MCP server card, A2A agent card, agent skills). Returns sub-second with item: { id, status: "queued", createdAt, expiresAt } — poll GET /v1/tools/agent-adoption/scans/{scanId} until status is completed or failed. Most scans complete in 35–60 seconds; slow or JS-heavy domains can take up to ~3 minutes. Result and error payloads are persisted for 24h, after which the scan auto-deletes and GET returns 404. No project required. Suitable for AI-adoption audits, agent-adoption maturity assessments, and pre-launch agentic-commerce reviews — and the only supported shape for MCP clients (Cursor / Claude Desktop hardcode 60-second tool-call timeouts).

Returns · { item }

Request body — application/json

Field	Type	Description
`domain`	`string`	Target domain to scan for AI-agent readiness. Accepts a bare hostname or a full URL — normalized (lowercased, scheme and path stripped) before scanning.
`debugMode`	`boolean`	When true, include the full HTTP trace (`evidence`) for every check in the response. Defaults to false.
`includeFixPrompts`	`boolean`	When true, include a copy-paste remediation prompt (`fixPrompt`) for each failed, scored check. Defaults to false.

Request


curl -X POST "https://api.competlab.com/v1/tools/agent-adoption/scans" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com","debugMode":false,"includeFixPrompts":false}'

Response 200 OK

Example


{
  "item": {
    "id": "6638e9a1b2c3d4e5f6a7b8c9",
    "status": "queued",
    "createdAt": "2026-05-17T14:30:00.000Z",
    "expiresAt": "2026-05-18T14:30:00.000Z"
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	Scan ID (24-char hex identifier). Use to poll GET /scans/:scanId.
`status`	`string`	Current lifecycle state. Poll until `completed` or `failed`. Values: `queued`, `running`, `completed`, `failed`.
`createdAt`	`string`	ISO-8601 timestamp when the scan was created.
`expiresAt`	`string`	ISO-8601 timestamp when the doc auto-deletes (createdAt + 24h). After this, GET returns 404.
`startedAt`	`string`	ISO-8601 timestamp when the background runner began scanning. Set once status leaves `queued`.
`completedAt`	`string`	ISO-8601 timestamp when the scan reached a terminal state (completed or failed).
`result`	`object`	Full canonical agent-adoption result. Present only when `status === "completed"`. See `item.result`.
`error`	`object`	Error details. Present only when `status === "failed"`. See `item.error`.

item.result — object

Field	Type	Description
`specVersion`	`string`	Spec version this output conforms to
`profile`	`string`	Profile name this scanner output reflects
`scanner`	`object`	Scanner identity — name + version. See `item.result.scanner`.
`domain`	`string`	Normalized domain, as actually requested
`finalUrl`	`string`	Final URL after redirects (from the upstream homepage fetch)
`scannedAt`	`string`	ISO-8601 timestamp of when the scan completed
`score`	`number`	0..100 integer overall score. Informational checks excluded; capped when a cluster cap verdict fires. Decorative — does not drive `level`.
`level`	`number`	Numeric level tier. Gate-based — see nextLevel.requirements.
`levelName`	`string`	Human-readable level name paired with level
`nextLevel`	`object`	Next-level gate — absent when at top of known ladder (L3+ gates unknown in v1). See `item.result.nextLevel`.
`categoryReports`	`array<object>`	4 category reports — locked order: discoverability → accessControl → contentReadability → agentEndpoints. See `item.result.categoryReports[]`.
`clusters`	`array<object>`	Cross-check scoring-layer verdicts (coefficients + caps). Always present — even non-triggered. Order locked: htmlPath → spaRenderingCap → noViablePathCap. See `item.result.clusters[]`.
`meta`	`object`	Envelope meta — scan duration, evaluated/skipped check counts, counters. See `item.result.meta`.

item.error — object

Field	Type	Description
`code`	`string`	Machine-readable error code. Values: `homepage_fetch_failed`, `scan_failed`.
`message`	`string`	Human-readable error message

item.result.scanner — object

Field	Type	Description
`name`	`string`	Scanner brand string (constant per implementation)
`version`	`string`	Semver-style version tag of the scanner emitting this response

item.result.nextLevel — object

Field	Type	Description
`level`	`number`	Target level number
`levelName`	`string`	Target level name
`requirements`	`array<string>`	Checks that must pass to advance (AND semantics)

item.result.categoryReports[] — each entry

Field	Type	Description
`category`	`string`	Category identifier. Values: `discoverability`, `accessControl`, `contentReadability`, `agentEndpoints`.
`description`	`string`	One-sentence customer-value description of what the category covers
`score`	`number`	0..100 integer category subscore
`passed`	`number`	Count of scored checks that passed in this category
`failed`	`number`	Count of scored checks that failed in this category
`neutral`	`number`	Count of checks that were neutral / informational
`checks`	`array<object>`	All checks belonging to this category. See `item.result.categoryReports[].checks[]`.

item.result.clusters[] — each entry

Field	Type	Description
`name`	`string`	Cluster verdict name. Values: `htmlPath`, `spaRenderingCap`, `noViablePathCap`.
`kind`	`string`	Verdict kind. ‘coefficient’ scales per-check weights; ‘cap’ clamps the final overall score. Values: `coefficient`, `cap`.
`triggered`	`boolean`	Whether the verdict fired for this scan
`coefficient`	`number`	Present when kind === ‘coefficient’. Multiplier in 0..1 — 1 = no penalty.
`appliesTo`	`array<string>`	Present when kind === ‘coefficient’. Check IDs whose weight is scaled.
`capScore`	`number`	Present when kind === ‘cap’ AND triggered. Final score is forced ≤ this value.
`message`	`string`	One-line human-readable verdict

item.result.meta — object

Field	Type	Description
`checksEvaluated`	`number`	Count of checks that produced a result (pass/fail/neutral). Dependency-skipped checks are counted.
`checksSkipped`	`number`	Count of v1 checks that did not run at all in this scan (e.g., future checks not yet implemented). Does not include dependency-skipped checks.
`scanDurationMs`	`number`	Total wall-clock scan duration in milliseconds
`counters`	`object`	Per-scan counters — fetches + upstream fetch-pipeline calls. Visible in all modes. See `item.result.meta.counters`.

item.result.categoryReports[].checks[] — each entry

Field	Type	Description
`id`	`string`	Check identifier, kebab-case (matches 25-check v1 scorecard). One of 25 values (e.g. `robots-txt-exists`, `sitemap-exists`, `link-headers`, …).
`category`	`string`	Top-level category this check belongs to. Values: `discoverability`, `accessControl`, `contentReadability`, `agentEndpoints`.
`status`	`string`	Tri-state check result; ‘neutral’ is informational. Values: `pass`, `fail`, `neutral`.
`scored`	`boolean`	Whether the check is scored. false = informational — excluded from both numerator and denominator.
`weight`	`number`	Weight on the 0-10 tier scale (Critical 10 / High 7 / Medium 4 / Low 2). 0 for informational checks.
`message`	`string`	Declarative, verdict-phrased — ‘what is the verdict + why’
`description`	`string`	Constant per-check one-sentence ‘what this measures’ (scan-invariant)
`durationMs`	`number`	Per-check duration in milliseconds
`dependsOn`	`array<string>`	Check IDs this check depends on — skipped when deps did not pass
`specUrls`	`array<string>`	Authoritative spec URLs (RFCs, W3C drafts, vendor docs). Always present so consumers can link to docs regardless of verdict.
`details`	`object`	Typed per-check structured metrics. Shape varies by check id (discriminated by ‘kind’ === check.id). Undefined when the check has no meaningful programmatic metrics beyond `message`.
`fixPrompt`	`object`	Copy-paste remediation prompt. Emitted only when the request sets includeFixPrompts: true and the check is failed and scored. Nested — see the Example tab.
`evidence`	`array<object>`	Full HTTP trace. Emitted only when the request sets debugMode: true. Nested — see the Example tab.

item.result.meta.counters — object

Field	Type	Description
`fetches`	`object`	Per-scan lightweight HTTP fetch counters. Nested — see the Example tab.
`heavyFetchCalls`	`object`	Per-scan heavy-fetch counters (used when the lightweight fetch is blocked or when JavaScript-rendered HTML is required). Nested — see the Example tab.

Errors

Status	Code	Meaning
400	`invalid_parameters`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.
502	`bad_gateway`	Upstream fetch failed (e.g. the target page could not be retrieved).

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.

Get an async agent-adoption scan by ID

GET/v1/tools/agent-adoption/scans/{scanId}

Get the current state of an async agent-adoption scan. Returns the scan’s lifecycle (queued / running / completed / failed) along with createdAt and expiresAt always, plus startedAt once the runner picks it up and completedAt once it reaches a terminal state. On completed the full canonical scan response is in item.result. On failed the failure details are in item.error with a machine-readable code — currently homepage_fetch_failed (upstream homepage fetch threw) or scan_failed (any other error during scan execution). Scoped to the API key’s organization — cross-tenant access, never-existed IDs, expired IDs (24h TTL), and malformed IDs all return 404 scan_not_found with an identical envelope to prevent existence-disclosure. Typically sub-second — safe to poll on a 2–5 second interval depending on your timeout budget.

Returns · { item }

Path parameters

Name	Type	Description
`scanId`	`string`

Request


curl "https://api.competlab.com/v1/tools/agent-adoption/scans/65a1b2c3d4e5f6a7b8c9d0e1" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "id": "6638e9a1b2c3d4e5f6a7b8c9",
    "status": "completed",
    "createdAt": "2026-05-17T14:30:00.000Z",
    "expiresAt": "2026-05-18T14:30:00.000Z",
    "startedAt": "2026-05-17T14:30:00.412Z",
    "completedAt": "2026-05-17T14:30:08.420Z",
    "result": {
      "specVersion": "1.0.0",
      "profile": "b2b-saas",
      "scanner": {
        "name": "CompetLab Agent-Adoption Scanner",
        "version": "0.8.0"
      },
      "domain": "stripe.com",
      "finalUrl": "https://stripe.com/",
      "scannedAt": "2026-05-17T14:30:08.000Z",
      "score": 72,
      "level": 2,
      "levelName": "AI-Aware",
      "categoryReports": [
        {
          "category": "discoverability",
          "description": "Whether AI agents can find your site through standard discovery mechanisms (robots.txt, sitemaps, link headers).",
          "score": 100,
          "passed": 1,
          "failed": 0,
          "neutral": 0,
          "checks": [
            {
              "id": "robots-txt-exists",
              "category": "discoverability",
              "status": "pass",
              "scored": true,
              "weight": 10,
              "message": "robots.txt found at https://stripe.com/robots.txt with 3 user-agent rules",
              "description": "Verifies a /robots.txt file exists and is fetchable.",
              "durationMs": 142,
              "dependsOn": [],
              "specUrls": [
                "https://www.rfc-editor.org/rfc/rfc9309"
              ]
            }
          ]
        },
        {
          "category": "accessControl",
          "description": "Whether your access rules deliberately allow or block AI agents.",
          "score": 100,
          "passed": 1,
          "failed": 0,
          "neutral": 0,
          "checks": [
            {
              "id": "ai-bot-rules",
              "category": "accessControl",
              "status": "pass",
              "scored": true,
              "weight": 7,
              "message": "Explicit rules found for 4 known AI user-agents",
              "description": "Checks whether robots.txt declares explicit rules for known AI crawlers.",
              "durationMs": 38,
              "dependsOn": [
                "robots-txt-exists"
              ],
              "specUrls": [
                "https://platform.openai.com/docs/bots"
              ]
            }
          ]
        },
        {
          "category": "contentReadability",
          "description": "Whether your content is structured for efficient agent consumption.",
          "score": 0,
          "passed": 0,
          "failed": 1,
          "neutral": 0,
          "checks": [
            {
              "id": "llms-txt-exists",
              "category": "contentReadability",
              "status": "fail",
              "scored": true,
              "weight": 4,
              "message": "No /llms.txt file found",
              "description": "Verifies a /llms.txt file exists at the site root.",
              "durationMs": 51,
              "dependsOn": [],
              "specUrls": [
                "https://llmstxt.org/"
              ]
            }
          ]
        },
        {
          "category": "agentEndpoints",
          "description": "Whether you expose machine-readable agent endpoints (MCP, A2A, OAuth discovery).",
          "score": 0,
          "passed": 0,
          "failed": 0,
          "neutral": 1,
          "checks": [
            {
              "id": "mcp-server-card",
              "category": "agentEndpoints",
              "status": "neutral",
              "scored": false,
              "weight": 0,
              "message": "No MCP server card detected (informational)",
              "description": "Looks for a published MCP server card advertising agent tools.",
              "durationMs": 44,
              "dependsOn": [],
              "specUrls": [
                "https://modelcontextprotocol.io/"
              ]
            }
          ]
        }
      ],
      "clusters": [
        {
          "name": "htmlPath",
          "kind": "coefficient",
          "triggered": true,
          "coefficient": 1,
          "appliesTo": [
            "rendering-strategy",
            "page-size-html"
          ],
          "message": "Standard HTML path detected — no rendering penalties applied."
        },
        {
          "name": "spaRenderingCap",
          "kind": "cap",
          "triggered": false,
          "message": "No SPA rendering cap applied."
        },
        {
          "name": "noViablePathCap",
          "kind": "cap",
          "triggered": false,
          "message": "A viable agent path exists — no cap applied."
        }
      ],
      "meta": {
        "checksEvaluated": 25,
        "checksSkipped": 0,
        "scanDurationMs": 8420,
        "counters": {
          "fetches": {
            "total": 28,
            "success": 22,
            "wafBlocked": 0,
            "notFound": 5,
            "failed": 1
          },
          "heavyFetchCalls": {
            "total": 2,
            "success": 2,
            "unavailable": 0
          }
        }
      }
    }
  }
}

Fields

item — object

Field	Type	Description
`id`	`string`	Scan ID (24-char hex identifier). Use to poll GET /scans/:scanId.
`status`	`string`	Current lifecycle state. Poll until `completed` or `failed`. Values: `queued`, `running`, `completed`, `failed`.
`createdAt`	`string`	ISO-8601 timestamp when the scan was created.
`expiresAt`	`string`	ISO-8601 timestamp when the doc auto-deletes (createdAt + 24h). After this, GET returns 404.
`startedAt`	`string`	ISO-8601 timestamp when the background runner began scanning. Set once status leaves `queued`.
`completedAt`	`string`	ISO-8601 timestamp when the scan reached a terminal state (completed or failed).
`result`	`object`	Full canonical agent-adoption result. Present only when `status === "completed"`. See `item.result`.
`error`	`object`	Error details. Present only when `status === "failed"`. See `item.error`.

item.result — object

Field	Type	Description
`specVersion`	`string`	Spec version this output conforms to
`profile`	`string`	Profile name this scanner output reflects
`scanner`	`object`	Scanner identity — name + version. See `item.result.scanner`.
`domain`	`string`	Normalized domain, as actually requested
`finalUrl`	`string`	Final URL after redirects (from the upstream homepage fetch)
`scannedAt`	`string`	ISO-8601 timestamp of when the scan completed
`score`	`number`	0..100 integer overall score. Informational checks excluded; capped when a cluster cap verdict fires. Decorative — does not drive `level`.
`level`	`number`	Numeric level tier. Gate-based — see nextLevel.requirements.
`levelName`	`string`	Human-readable level name paired with level
`nextLevel`	`object`	Next-level gate — absent when at top of known ladder (L3+ gates unknown in v1). See `item.result.nextLevel`.
`categoryReports`	`array<object>`	4 category reports — locked order: discoverability → accessControl → contentReadability → agentEndpoints. See `item.result.categoryReports[]`.
`clusters`	`array<object>`	Cross-check scoring-layer verdicts (coefficients + caps). Always present — even non-triggered. Order locked: htmlPath → spaRenderingCap → noViablePathCap. See `item.result.clusters[]`.
`meta`	`object`	Envelope meta — scan duration, evaluated/skipped check counts, counters. See `item.result.meta`.

item.error — object

Field	Type	Description
`code`	`string`	Machine-readable error code. Values: `homepage_fetch_failed`, `scan_failed`.
`message`	`string`	Human-readable error message

item.result.scanner — object

Field	Type	Description
`name`	`string`	Scanner brand string (constant per implementation)
`version`	`string`	Semver-style version tag of the scanner emitting this response

item.result.nextLevel — object

Field	Type	Description
`level`	`number`	Target level number
`levelName`	`string`	Target level name
`requirements`	`array<string>`	Checks that must pass to advance (AND semantics)

item.result.categoryReports[] — each entry

Field	Type	Description
`category`	`string`	Category identifier. Values: `discoverability`, `accessControl`, `contentReadability`, `agentEndpoints`.
`description`	`string`	One-sentence customer-value description of what the category covers
`score`	`number`	0..100 integer category subscore
`passed`	`number`	Count of scored checks that passed in this category
`failed`	`number`	Count of scored checks that failed in this category
`neutral`	`number`	Count of checks that were neutral / informational
`checks`	`array<object>`	All checks belonging to this category. See `item.result.categoryReports[].checks[]`.

item.result.clusters[] — each entry

Field	Type	Description
`name`	`string`	Cluster verdict name. Values: `htmlPath`, `spaRenderingCap`, `noViablePathCap`.
`kind`	`string`	Verdict kind. ‘coefficient’ scales per-check weights; ‘cap’ clamps the final overall score. Values: `coefficient`, `cap`.
`triggered`	`boolean`	Whether the verdict fired for this scan
`coefficient`	`number`	Present when kind === ‘coefficient’. Multiplier in 0..1 — 1 = no penalty.
`appliesTo`	`array<string>`	Present when kind === ‘coefficient’. Check IDs whose weight is scaled.
`capScore`	`number`	Present when kind === ‘cap’ AND triggered. Final score is forced ≤ this value.
`message`	`string`	One-line human-readable verdict

item.result.meta — object

Field	Type	Description
`checksEvaluated`	`number`	Count of checks that produced a result (pass/fail/neutral). Dependency-skipped checks are counted.
`checksSkipped`	`number`	Count of v1 checks that did not run at all in this scan (e.g., future checks not yet implemented). Does not include dependency-skipped checks.
`scanDurationMs`	`number`	Total wall-clock scan duration in milliseconds
`counters`	`object`	Per-scan counters — fetches + upstream fetch-pipeline calls. Visible in all modes. See `item.result.meta.counters`.

item.result.categoryReports[].checks[] — each entry

Field	Type	Description
`id`	`string`	Check identifier, kebab-case (matches 25-check v1 scorecard). One of 25 values (e.g. `robots-txt-exists`, `sitemap-exists`, `link-headers`, …).
`category`	`string`	Top-level category this check belongs to. Values: `discoverability`, `accessControl`, `contentReadability`, `agentEndpoints`.
`status`	`string`	Tri-state check result; ‘neutral’ is informational. Values: `pass`, `fail`, `neutral`.
`scored`	`boolean`	Whether the check is scored. false = informational — excluded from both numerator and denominator.
`weight`	`number`	Weight on the 0-10 tier scale (Critical 10 / High 7 / Medium 4 / Low 2). 0 for informational checks.
`message`	`string`	Declarative, verdict-phrased — ‘what is the verdict + why’
`description`	`string`	Constant per-check one-sentence ‘what this measures’ (scan-invariant)
`durationMs`	`number`	Per-check duration in milliseconds
`dependsOn`	`array<string>`	Check IDs this check depends on — skipped when deps did not pass
`specUrls`	`array<string>`	Authoritative spec URLs (RFCs, W3C drafts, vendor docs). Always present so consumers can link to docs regardless of verdict.
`details`	`object`	Typed per-check structured metrics. Shape varies by check id (discriminated by ‘kind’ === check.id). Undefined when the check has no meaningful programmatic metrics beyond `message`.
`fixPrompt`	`object`	Copy-paste remediation prompt. Emitted only when the request sets includeFixPrompts: true and the check is failed and scored. Nested — see the Example tab.
`evidence`	`array<object>`	Full HTTP trace. Emitted only when the request sets debugMode: true. Nested — see the Example tab.

item.result.meta.counters — object

Field	Type	Description
`fetches`	`object`	Per-scan lightweight HTTP fetch counters. Nested — see the Example tab.
`heavyFetchCalls`	`object`	Per-scan heavy-fetch counters (used when the lightweight fetch is blocked or when JavaScript-rendered HTML is required). Nested — see the Example tab.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`scan_not_found`	No `scan` matches the id in the path.
429	`rate_limit_exceeded`	Rate limit exceeded — retry with backoff.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Transient failures (429, 5xx) are safe to retry with exponential backoff.