Agent Web Map Sections API

openapi: 3.2.0
info:
  title: Agent Web Map Sections 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: Sections
paths:
  /v1/sections:
    get:
      operationId: listSections
      summary: Publisher heading catalogue, distinct-site counts, emerging labels and coverage
      description: Labels come from the indexed corpus. Newest shows labels observed after the baseline. Emerging additionally requires positive seven-day growth, ten estimated domain-name families from complete files without known templates/duplicates, and three days of observation. These are index signals, not adoption dates. Seven-day changes count net site memberships after the baseline; headings do not certify capabilities.
      parameters:
      - name: q
        in: query
        schema:
          type: string
          maxLength: 120
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - common
          - alphabetical
          - newest
          - emerging
          default: common
      - 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: 36
      - 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/SectionCatalogue'
        '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'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Sections
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
    SectionCatalogue:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        results:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              label:
                type: string
              sites:
                type: integer
              total_sites:
                type: integer
              first_seen:
                type: string
              emerged_at:
                type:
                - string
                - 'null'
              change_7d:
                type: integer
              trend_evidence:
                anyOf:
                - type: object
                  properties:
                    publisher_groups:
                      type: integer
                  required:
                  - publisher_groups
                  additionalProperties: false
                - type: 'null'
            required:
            - key
            - label
            - sites
            - total_sites
            - first_seen
            - emerged_at
            - change_7d
            - trend_evidence
            additionalProperties: false
        trend_policy:
          type: string
        filters:
          type: object
          properties:
            sections:
              type: array
              items:
                type: string
            sectionMatch:
              enum:
              - all
              - any
            country:
              type:
              - string
              - 'null'
            action:
              type:
              - string
              - 'null'
          required:
          - sections
          - sectionMatch
          additionalProperties: false
        coverage:
          type: object
          properties:
            eligible_sites:
              type: integer
            indexed_sites:
              type: integer
            partial_sites:
              type: integer
            pending_files:
              type: integer
            baseline_ready:
              type: boolean
            updated_at:
              type:
              - string
              - 'null'
            statistics_updated_at:
              type: string
            statistics_stale:
              type: boolean
          required:
          - eligible_sites
          - indexed_sites
          - partial_sites
          - pending_files
          - baseline_ready
          - updated_at
          additionalProperties: false
      required:
      - total
      - page
      - per_page
      - results
      - trend_policy
      - filters
      - coverage
      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.