openapi: "3.0.3"
info:
  title: Not Human Search API
  description: Search engine for AI agents. Find websites ranked by agentic readiness.
  version: "1.0.0"
  contact:
    email: hello@nothumansearch.ai
servers:
  - url: https://nothumansearch.ai/api/v1
paths:
  /search:
    get:
      summary: Search for agent-ready sites
      operationId: searchSites
      parameters:
        - name: q
          in: query
          schema: { type: string }
          description: Search query (matches name, description, domain)
        - name: category
          in: query
          schema: { type: string, enum: [ai-tools, developer, data, jobs, finance, ecommerce, health, education, security, communication, productivity, other] }
        - name: tag
          in: query
          schema: { type: string }
          description: Exact tag match (e.g. mcp, openapi, payment, search). See /sitemap.xml for indexed tags.
        - name: min_score
          in: query
          schema: { type: integer, minimum: 0, maximum: 100 }
          description: Minimum agentic readiness score
        - name: has_api
          in: query
          schema: { type: boolean }
          description: Filter to sites with structured APIs
        - name: has_mcp
          in: query
          schema: { type: boolean }
          description: Filter to sites with a Model Context Protocol server
        - name: has_openapi
          in: query
          schema: { type: boolean }
          description: Filter to sites that publish an OpenAPI spec
        - name: has_llms_txt
          in: query
          schema: { type: boolean }
          description: Filter to sites that publish llms.txt
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results: { type: array, items: { $ref: "#/components/schemas/Site" } }
                  total: { type: integer }
                  page: { type: integer }
                  has_next: { type: boolean }
  /site/{domain}:
    get:
      summary: Get detailed agentic readiness report for a site
      operationId: getSite
      parameters:
        - name: domain
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Site details
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Site" }
  /submit:
    post:
      summary: Submit a site for crawling
      operationId: submitSite
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: { type: string, format: uri }
      responses:
        "201":
          description: Submitted for crawling
  /check:
    post:
      summary: On-demand agentic readiness check (live crawl)
      operationId: checkSite
      description: |
        Crawls the target URL on demand and returns its 7-signal agentic
        readiness score. Ideal for CI pipelines that should fail when an
        agent-facing site regresses. Free tier: 10 checks/hour per IP.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: { type: string, format: uri }
      responses:
        "200":
          description: Score + 7 signals
        "429":
          description: Rate limit exceeded
  /stats:
    get:
      summary: Get index statistics
      operationId: getStats
      responses:
        "200":
          description: Index stats
components:
  schemas:
    Site:
      type: object
      properties:
        id: { type: string, format: uuid }
        domain: { type: string }
        url: { type: string, format: uri }
        name: { type: string }
        description: { type: string }
        has_llms_txt: { type: boolean }
        has_ai_plugin: { type: boolean }
        has_openapi: { type: boolean }
        has_robots_ai: { type: boolean }
        has_structured_api: { type: boolean }
        has_mcp_server: { type: boolean }
        has_schema_org: { type: boolean }
        agentic_score: { type: integer, minimum: 0, maximum: 100 }
        category: { type: string }
        tags: { type: array, items: { type: string } }
        is_verified: { type: boolean }
        is_featured: { type: boolean }