agiscorecard-com Scan API

openapi: 3.2.0
info:
  title: AgentReady public Scan API
  version: 1.0.0
  summary: 'Free AI sales-visibility scanner: score any website 0–100 on how discoverable and parseable it is for AI shopping agents.'
  description: 'AgentReady''s free public endpoints — no signup, no API key, CORS-open.


    - `GET /api/scan` — instant agent-readiness scan of any website: robots.txt access for the major AI crawlers (GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, PerplexityBot, Google-Extended), llms.txt and agents.md presence, schema.org JSON-LD structured data (Product, Offer, Organization, FAQPage), sitemap discoverability and answer-readiness metadata — returned as a 0–100 score with itemized checks and concrete fixes.

    - `GET /api/verify/status` — public verification status of an Agent-Ready Verified badge (no PII exposed).

    - `GET /badge/{id}.svg` — the embeddable Agent-Ready Verified badge image, kept honest by weekly automated re-verification.


    Please self-limit to a few requests per minute per target. A pay-per-call version of the scan for autonomous agents (x402 protocol, USDC on Base, no account) is documented at https://x402.agiscorecard.com/openapi.json.'
  contact:
    name: AgentReady
    url: https://agentready.agiscorecard.com/
  license:
    name: Proprietary — free public API, fair-use rate limits apply
    url: https://agentready.agiscorecard.com/terms
servers:
- url: https://agentready.agiscorecard.com
security:
- {}
tags:
- name: Scan
paths:
  /api/scan:
    get:
      operationId: scanSite
      summary: Free agent-readiness scan of any website
      description: Fetches the target's robots.txt, llms.txt, agents.md, homepage and sitemap, runs the full check suite and returns a 0–100 score with itemized pass/warn/fail checks and concrete fixes. Free, no auth. Private/local hosts are rejected.
      parameters:
      - name: url
        in: query
        required: true
        description: Target URL to scan (scheme optional — `https://` is assumed).
        schema:
          type: string
          examples:
          - example.com
      responses:
        '200':
          description: Scan report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanReport'
        '400':
          description: Missing or invalid url parameter, or a private/local host.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The target could not be reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Scan
components:
  schemas:
    ScanReport:
      type: object
      required:
      - url
      - score
      - grade
      - checks
      properties:
        url:
          type: string
          format: uri
          description: Normalized target URL that was scanned.
        scannedAt:
          type: string
          format: date-time
        score:
          type: integer
          minimum: 0
          maximum: 100
        grade:
          type: string
          examples:
          - A
          - B
          - C
          - D
          - F
        checks:
          type: array
          items:
            $ref: '#/components/schemas/Check'
        summary:
          type: string
          description: One-line human summary of the result.
      additionalProperties: true
    Check:
      type: object
      description: One itemized check in the scan report.
      properties:
        id:
          type: string
          examples:
          - bot-gptbot
          - llms
          - sd-product
        category:
          type: string
          examples:
          - AI crawler access
          - Structured data
        title:
          type: string
        earned:
          type: number
          description: Points earned.
        possible:
          type: number
          description: Points possible.
        status:
          type: string
          enum:
          - pass
          - warn
          - fail
        detail:
          type: string
        fix:
          type:
          - string
          - 'null'
          description: Concrete fix suggestion; null when the check passes.
      additionalProperties: true
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human- and agent-readable error message.