{
  "openapi": "3.1.0",
  "info": {
    "title": "Nextriad Agent Visit Registry",
    "version": "2026-05-02",
    "description": "Contract for AI agents, crawlers, assistants, and autonomous systems that visit nextriad.ai and want to identify themselves, declare intent, request allowed surfaces, or initiate a Triad handoff."
  },
  "servers": [
    { "url": "https://nextriad.ai" }
  ],
  "paths": {
    "/.well-known/agent-registry.json": {
      "get": {
        "summary": "Discover the Nextriad agent self-registration protocol",
        "operationId": "getAgentRegistryManifest",
        "responses": {
          "200": {
            "description": "Agent registry discovery manifest",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentRegistryManifest" }
              }
            }
          }
        }
      }
    },
    "/api/agent-visits": {
      "post": {
        "summary": "Register an AI agent website visit",
        "operationId": "registerAgentVisit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentVisit" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent visit accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "agentVisitId": { "type": "string" },
                    "recommendedSurfaces": {
                      "type": "array",
                      "items": { "type": "string" },
                      "examples": [["/llms.txt", "/agents.txt", "/mcp/manifest.json", "/ars", "/integrations"]]
                    },
                    "triadHandoff": {
                      "type": "object",
                      "properties": {
                        "available": { "type": "boolean" },
                        "nextAction": { "type": "string", "example": "request_ars_diagnostic" }
                      }
                    },
                    "crm": {
                      "type": "object",
                      "properties": {
                        "stage": { "type": "string", "example": "qualified_agent_signal" },
                        "score": { "type": "integer", "example": 91 },
                        "nextAction": { "type": "string", "example": "Triad handoff" }
                      }
                    },
                    "aiosSync": {
                      "type": "object",
                      "description": "AIOS/Supabase sync status for Agent CRM.",
                      "properties": {
                        "status": { "type": "string", "enum": ["synced", "skipped", "failed"] },
                        "tenantId": { "type": ["string", "null"] },
                        "agentVisitTableId": { "type": ["string", "null"] },
                        "reason": { "type": "string" },
                        "error": { "type": "string" }
                      }
                    },
                    "email": {
                      "type": "object",
                      "description": "Internal transactional notification status for qualified agent signals.",
                      "properties": {
                        "internal": { "$ref": "#/components/schemas/EmailStatus" }
                      }
                    }
                  },
                  "required": ["ok"]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AgentRegistryManifest": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "name": { "type": "string" },
          "registration": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "method": { "type": "string" },
              "endpoint": { "type": "string", "format": "uri" },
              "openapi": { "type": "string", "format": "uri" }
            }
          },
          "allowed_surfaces": {
            "type": "array",
            "items": { "type": "string", "format": "uri" }
          }
        }
      },
      "AgentVisit": {
        "type": "object",
        "required": ["type", "agent", "visit", "intent"],
        "properties": {
          "type": { "const": "nextriad_agent_visit" },
          "version": { "type": "string", "example": "2026-05-02" },
          "agent": {
            "type": "object",
            "required": ["name"],
            "properties": {
              "name": { "type": "string", "example": "ExampleResearchAgent" },
              "provider": { "type": "string", "example": "Example AI" },
              "model": { "type": "string", "example": "example-model-1" },
              "homepage": { "type": "string", "format": "uri" },
              "contact": { "type": "string" },
              "capabilities": {
                "type": "array",
                "items": { "type": "string" },
                "examples": [["research", "summarization", "procurement", "lead_qualification"]]
              }
            }
          },
          "visit": {
            "type": "object",
            "properties": {
              "sourceUrl": { "type": "string", "format": "uri" },
              "referrer": { "type": "string" },
              "timestamp": { "type": "string", "format": "date-time" },
              "userAgent": { "type": "string" },
              "sessionId": { "type": "string" }
            }
          },
          "intent": {
            "type": "object",
            "properties": {
              "purpose": {
                "type": "string",
                "enum": ["research", "vendor_evaluation", "procurement", "integration", "diagnostic", "support", "other"]
              },
              "requestedSurfaces": {
                "type": "array",
                "items": { "type": "string" }
              },
              "companyRepresented": { "type": "string" },
              "humanPrincipal": { "type": "string" },
              "triadHandoffRequested": { "type": "boolean" }
            }
          },
          "consent": {
            "type": "object",
            "properties": {
              "mayContactHumanPrincipal": { "type": "boolean" },
              "mayStoreVisit": { "type": "boolean" },
              "mayUseForKnowledgeGraph": { "type": "boolean" }
            }
          },
          "crm": {
            "type": "object",
            "description": "Agent CRM routing metadata generated by Nextriad AIOS or by the website pre-qualification layer.",
            "properties": {
              "pipeline": { "type": "string", "example": "Agent CRM" },
              "stage": {
                "type": "string",
                "enum": ["agent_identified", "qualified_agent_signal", "triad_handoff_requested", "converted_to_human_lead", "closed"]
              },
              "score": { "type": "integer", "minimum": 0, "maximum": 100 },
              "ownerTeam": { "type": "string", "example": "Nextriad Growth" },
              "nextAction": { "type": "string", "example": "Triad handoff" }
            }
          }
        }
      },
      "EmailStatus": {
        "type": "object",
        "properties": {
          "emailId": { "type": "string" },
          "provider": { "type": "string", "example": "resend" },
          "status": { "type": "string", "enum": ["sent", "skipped", "failed"] },
          "reason": { "type": "string" },
          "error": { "type": "string" }
        }
      }
    }
  }
}