Agent Web Map Domains API

openapi: 3.2.0
info:
  title: Agent Web Map Domains 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: Domains
paths:
  /v1/domains:
    get:
      operationId: listDomains
      summary: Ranked listing (verified first, then authority)
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number. Anonymous enumeration covers 250 results per query; registered keys cover 1,000.
      - name: per_page
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - name: include_unlisted
        in: query
        schema:
          type: boolean
          default: false
        description: Requires explicit unlisted permission on an approved discovery client key.
      - name: verified
        in: query
        schema:
          type: boolean
          default: false
        description: Only domains whose owner has verified them
      - name: detail
        in: query
        schema:
          type: string
          enum:
          - compact
          - full
          default: compact
        description: Compact consumer fields; full adds owner profile and claim instructions.
      - name: category
        in: query
        schema:
          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
        description: Topic ID from GET /v1/categories. Classification uses publisher metadata; unclassified sites have categories=[].
      - name: capability
        in: query
        schema:
          type: string
          enum:
          - mcp
        description: Publisher-declared MCP endpoint. This declaration does not prove endpoint availability or protocol compatibility.
      - name: agentic
        in: query
        schema:
          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).'
      - name: country
        in: query
        schema:
          type: string
          pattern: ^(?:[A-Za-z]{2}|[Uu][Nn][Kk][Nn][Oo][Ww][Nn])$
          description: 'Country: owner-declared or site-published address preferred; domain/hosting inference is a labeled fallback. ISO 3166-1 alpha-2 (XK supported), case-insensitive, or unknown. GET /v1/countries / list_countries lists counts. Not verified headquarters or markets served.'
        description: 'Country: owner-declared or site-published address preferred; domain/hosting inference is a labeled fallback. ISO 3166-1 alpha-2 (XK supported), case-insensitive, or unknown. GET /v1/countries / list_countries lists counts. Not verified headquarters or markets served.'
      - name: action
        in: query
        schema:
          type: string
          enum:
          - read_docs
          - search_content
          - call_api
          - buy
          - book
          - download_data
          - contact_support
          description: Actions are inferred from publisher content. They can overlap and do not prove a working integration, authorization or task success. Unclassified sites may be missing useful actions.
        description: Actions are inferred from publisher content. They can overlap and do not prove a working integration, authorization or task success. Unclassified sites may be missing useful actions.
      - name: sections
        in: query
        schema:
          type: string
          maxLength: 605
        description: Up to five comma-separated publisher section keys from GET /v1/sections. Independent of business categories.
      - name: section_match
        in: query
        schema:
          type: string
          enum:
          - all
          - any
          default: all
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing'
        '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'
        '403':
          description: Blocked domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Domains
components:
  schemas:
    Listing:
      type: object
      properties:
        query:
          type: string
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        results:
          type: array
          items:
            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
      required:
      - page
      - per_page
      - total
      - results
      additionalProperties: false
    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
  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.