Agent Web Map Domain API

openapi: 3.2.0
info:
  title: Agent Web Map Domain API
  version: 0.28.1
  description: 'Agent Web Map is the directory of websites publishing llms.txt: found across the web, validated continuously and ranked by authority, with a free JSON API and MCP server so AI agents can look any site up. Basic discovery stays anonymous. Enumeration windows cover 250 anonymous or 1,000 registered results per query; bulk needs separate approval. Generator, audits and MCP checks require free registration. Daily counters remain observations. Integration identity uses Authorization: Bearer awm_client_… or X-AgentWebMap-Key, separate from owner keys. Responses are private, no-store. See https://agentwebmap.com/docs#limits. Compact fields are the default; detail=full includes owner metadata. Ownership verification proves identity, not documentation correctness. MCP server: https://agentwebmap.com/mcp'
  contact:
    email: admin@agentwebmap.com
servers:
- url: https://agentwebmap.com
tags:
- name: Domain
paths:
  /v1/domain/{domain}:
    get:
      operationId: lookupDomain
      summary: Domain sources, health timestamp and terms
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 253
        description: Domain name, e.g. example.com
      - name: detail
        in: query
        schema:
          type: string
          enum:
          - compact
          - full
          default: compact
        description: Compact consumer fields; full adds owner profile and claim instructions.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '400':
          description: Invalid arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Bad or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Domain
  /v1/domain/{domain}/llms.txt:
    get:
      operationId: readLlmsTxt
      summary: Our validated copy of the site llms.txt as text/plain, with X-Source-URL…
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 253
        description: Domain name, e.g. example.com
      responses:
        '200':
          description: The llms.txt text
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Publisher check failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Domain
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        hint:
          type: string
        detail:
          type: string
        domain:
          type: string
        retry_after_seconds:
          type: integer
      required:
      - error
      additionalProperties: true
    Domain:
      type: object
      properties:
        domain:
          type: string
        status:
          type: string
          enum:
          - pending
          - valid
          - invalid
          - unreachable
        tier:
          type:
          - string
          - 'null'
          enum:
          - featured
          - listed
          - unlisted
          - rejected
          - null
        authority:
          type:
          - integer
          - 'null'
        verified:
          type: boolean
        title:
          type:
          - string
          - 'null'
        summary:
          type:
          - string
          - 'null'
        llms_txt:
          type:
          - string
          - 'null'
        llms_full_txt:
          type:
          - string
          - 'null'
        last_checked:
          type:
          - string
          - 'null'
        agent_terms:
          anyOf:
          - type: object
            properties:
              automated_access:
                type: string
                enum:
                - welcome
                - limited
                - ask
                - not_allowed
              rate_limit:
                type: string
                maxLength: 100
              attribution:
                type: string
                enum:
                - required
                - appreciated
                - none
              attribution_text:
                type: string
                maxLength: 200
              pricing:
                type: string
                enum:
                - free
                - freemium
                - paid
              pricing_url:
                type: string
              terms_url:
                type: string
              notes:
                type: string
                maxLength: 500
            required: []
            additionalProperties: false
          - type: 'null'
        categories:
          type: array
          items:
            type: string
            enum:
            - ai-ml
            - developer-tools
            - infrastructure
            - data-analytics
            - cybersecurity
            - finance-payments
            - ecommerce
            - productivity
            - marketing
            - education
            - healthcare
            - media
            - design
            - gaming
            - travel
            - community
            - legal
            - recruiting-careers
            - industrial-manufacturing
            - real-estate
            - arts-culture
            - sports-fitness
            - food-dining
            - automotive
            - government-public-services
            - science-research
            - ai-agents-mcp
            - apis-sdks
            - databases
            - auth-identity
            - devops-observability
            - no-code-automation
            - communications
            - crypto-web3
            - saas-business-software
            - open-source
            - documentation-reference
            - fashion-beauty
            - home-garden
            - consumer-electronics
            - pets
            - insurance
            - telecom
            - logistics-shipping
            - energy-utilities
            - construction-architecture
            - agriculture
            - nonprofit
            - events
            - personal-blog
            - entertainment
            - local-business
          maxItems: 8
          uniqueItems: true
          description: Inferred topic IDs from publisher metadata; empty means unclassified.
        inferred_tags:
          type: array
          items:
            type: string
          description: Topic tags inferred by the AI classifier from the site text.
        audience:
          anyOf:
          - type: string
            enum:
            - developers
            - consumers
            - business
            - mixed
          - type: 'null'
        agent_uses:
          type: array
          items:
            type: string
            enum:
            - read_docs
            - call_api
            - buy
            - book
            - search_content
            - download_data
            - contact_support
          uniqueItems: true
        language:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
          description: Published or declared address country preferred; domain/hosting fallback. Null when unknown. Not independently verified headquarters or markets served.
        country_source:
          type:
          - string
          - 'null'
          enum:
          - owner
          - structured_data
          - contact_page
          - tld
          - ip
          - cdn
          - null
          description: 'owner: owner-declared address; structured_data/contact_page: site-published address; tld: domain inference; ip: non-CDN hosting inference; cdn: location withheld. No source independently verifies headquarters.'
        publisher_country:
          type:
          - string
          - 'null'
        publisher_country_source:
          type:
          - string
          - 'null'
          enum:
          - owner
          - structured_data
          - contact_page
          - null
        hosting_country:
          type:
          - string
          - 'null'
        platform_generated:
          type:
          - boolean
          - 'null'
        agent_summary:
          type:
          - string
          - 'null'
        llms_txt_cached:
          type: string
        agentic:
          anyOf:
          - type: string
            enum:
            - interface
            - transactional
            - documentation
            - informational
            description: 'What an agent can do with the site: interface (API or MCP endpoint to call), transactional (buy or book), documentation (docs to read), informational (for people).'
          - type: 'null'
        section_keys:
          type: array
          items:
            type: string
        section_partial:
          type: boolean
        section_indexed_at:
          type:
          - string
          - 'null'
        capabilities:
          type: array
          items:
            type: string
            enum:
            - mcp
          uniqueItems: true
          description: Publisher-declared capabilities. An MCP declaration does not prove availability or protocol compatibility.
        section_headings:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              label:
                type: string
              level:
                type: integer
              path:
                type: string
              line:
                type:
                - integer
                - 'null'
              format:
                enum:
                - markdown
                - loose
                - setext
                - indexed_link
              source_url:
                type:
                - string
                - 'null'
            required:
            - key
            - label
            - level
            - path
            - line
            - format
            additionalProperties: false
        verified_at:
          type:
          - string
          - 'null'
        nested_llms_txt:
          type: array
          items:
            type: string
        description:
          type:
          - string
          - 'null'
        tags:
          type: array
          items:
            type: string
        contact:
          type:
          - string
          - 'null'
        sections:
          type:
          - integer
          - 'null'
        links:
          type:
          - integer
          - 'null'
        rank:
          type:
          - integer
          - 'null'
        registered_at:
          type:
          - string
          - 'null'
        first_seen:
          type:
          - string
          - 'null'
        badge:
          type: string
        claim:
          type: object
          properties:
            agent_prompt:
              type: string
            hint:
              type: string
            verification:
              type: string
            verify:
              type: string
            docs:
              type: string
            mcp:
              type: string
            benefits:
              type: array
              items:
                type: string
          required:
          - agent_prompt
          - hint
          - verification
          - verify
          - docs
          - mcp
          - benefits
          additionalProperties: false
        domain_country:
          type:
          - string
          - 'null'
        country_checked_at:
          type:
          - string
          - 'null'
        country_status:
          type: string
        country_evidence:
          type: array
          items:
            type: object
            properties:
              country:
                type: string
              source:
                type: string
              url:
                type:
                - string
                - 'null'
              checked_at:
                type:
                - string
                - 'null'
              method:
                type: string
            required:
            - country
            - source
            - url
            - checked_at
            - method
            additionalProperties: false
        why:
          type: array
          items:
            type: string
        match_score:
          type: number
        evidence:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              title:
                type:
                - string
                - 'null'
              excerpt:
                type:
                - string
                - 'null'
              source_url:
                type:
                - string
                - 'null'
            required:
            - url
            additionalProperties: true
        category_evidence:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                enum:
                - ai-ml
                - developer-tools
                - infrastructure
                - data-analytics
                - cybersecurity
                - finance-payments
                - ecommerce
                - productivity
                - marketing
                - education
                - healthcare
                - media
                - design
                - gaming
                - travel
                - community
                - legal
                - recruiting-careers
                - industrial-manufacturing
                - real-estate
                - arts-culture
                - sports-fitness
                - food-dining
                - automotive
                - government-public-services
                - science-research
                - ai-agents-mcp
                - apis-sdks
                - databases
                - auth-identity
                - devops-observability
                - no-code-automation
                - communications
                - crypto-web3
                - saas-business-software
                - open-source
                - documentation-reference
                - fashion-beauty
                - home-garden
                - consumer-electronics
                - pets
                - insurance
                - telecom
                - logistics-shipping
                - energy-utilities
                - construction-architecture
                - agriculture
                - nonprofit
                - events
                - personal-blog
                - entertainment
                - local-business
              confidence:
                type: number
                minimum: 0
                maximum: 1
                description: Deterministic rule strength, not a calibrated probability.
              evidence:
                type: array
                items:
                  type: string
              source:
                enum:
                - publisher_metadata
                - llm
            required:
            - id
            - confidence
            - evidence
            - source
            additionalProperties: false
        category_version:
          type:
          - string
          - 'null'
        categorized_at:
          type:
          - string
          - 'null'
        capability_evidence:
          type: array
          items:
            type: object
            properties:
              id:
                const: mcp
              url:
                type: string
              source_url:
                type: string
              status:
                const: publisher_declared
            required:
            - id
            - url
            - source_url
            - status
            additionalProperties: false
      required:
      - domain
      - status
      - tier
      - authority
      - verified
      - title
      - summary
      - llms_txt
      - llms_full_txt
      - last_checked
      - agent_terms
      - categories
      - capabilities
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Owner API key from /verify
    discoveryClient:
      type: apiKey
      in: header
      name: X-AgentWebMap-Key
      description: Self-service scoped integration key, awm_client_…. Required for generator, audits and MCP checks, and deeper enumeration; basic discovery stays anonymous. Owner keys are separate.