{
  "openapi": "3.1.2",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "Agent Registry API",
    "version": "2.0-r2",
    "description": "R2 permission-aware Agent catalog, semantic discovery, and platform drift reporting. The API has no Agent mutation or invocation operations.",
    "x-contract-status": "accepted-by-ADR-0002-and-ADR-0003"
  },
  "servers": [{"url": "/"}],
  "security": [{"bearerAuth": []}],
  "paths": {
    "/api/v2/agents": {
      "get": {
        "operationId": "listAgentsV2",
        "summary": "List active Agents visible through agent#view",
        "x-authorization-permission": "agent#view",
        "parameters": [
          {"$ref": "#/components/parameters/Protocol"},
          {"$ref": "#/components/parameters/ImplementationType"},
          {"$ref": "#/components/parameters/OwnerType"},
          {"$ref": "#/components/parameters/OwnerIssuer"},
          {"$ref": "#/components/parameters/OwnerSubject"},
          {"$ref": "#/components/parameters/Cursor"},
          {"$ref": "#/components/parameters/Limit"}
        ],
        "responses": {
          "200": {
            "description": "Permission-filtered page; hidden-resource totals are not exposed",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentListResponse"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthenticated"},
          "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}
        }
      }
    },
    "/api/v2/agents/{agentId}": {
      "get": {
        "operationId": "getAgentV2",
        "summary": "Get an active Agent projection by Publisher-issued UUIDv7",
        "x-authorization-permission": "agent#view",
        "parameters": [{"$ref": "#/components/parameters/AgentId"}],
        "responses": {
          "200": {
            "description": "Visible active Agent projection",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentProjection"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthenticated"},
          "404": {"$ref": "#/components/responses/HiddenOrAbsent"},
          "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}
        }
      }
    },
    "/api/v2/agents/search": {
      "post": {
        "operationId": "searchAgentsV2",
        "summary": "Search active Agents and filter every bounded candidate through agent#view",
        "x-authorization-permission": "agent#view",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SearchRequest"}}}
        },
        "responses": {
          "200": {
            "description": "Visible matches; an empty allowed result is represented as matches=[]",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SearchResponse"}}}
          },
          "400": {"$ref": "#/components/responses/InvalidRequest"},
          "401": {"$ref": "#/components/responses/Unauthenticated"},
          "422": {"$ref": "#/components/responses/InvalidRequest"},
          "503": {"$ref": "#/components/responses/SearchDependencyUnavailable"}
        }
      }
    },
    "/api/v2/drift": {
      "get": {
        "operationId": "getDriftReportV2",
        "summary": "Read current drift for the exact platform observation allowlist",
        "x-authorization-resource": "platform:agent-platform",
        "x-authorization-permission": "platform#view_drift",
        "parameters": [
          {"$ref": "#/components/parameters/Cursor"},
          {"$ref": "#/components/parameters/Limit"}
        ],
        "responses": {
          "200": {
            "description": "Current state and coverage; no remediation operation is implied",
            "content": {"application/json": {"schema": {"$ref": "../schemas/drift-report-v2.schema.json"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthenticated"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}
        }
      }
    },
    "/health/live": {
      "get": {
        "operationId": "getLiveness",
        "security": [],
        "responses": {"200": {"description": "Process is alive", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Health"}}}}}
      }
    },
    "/health/ready": {
      "get": {
        "operationId": "getReadiness",
        "security": [],
        "responses": {
          "200": {"description": "Serving configuration is ready", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Health"}}}},
          "503": {"description": "Serving configuration is not ready", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Health"}}}}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}
    },
    "parameters": {
      "AgentId": {"name": "agentId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},
      "Protocol": {"name": "protocol", "in": "query", "schema": {"type": "array", "items": {"enum": ["a2a", "mcp"]}}, "explode": true},
      "ImplementationType": {"name": "implementationType", "in": "query", "description": "Versioned classification; only low-code is an advertised R2 publication source adapter", "x-r2-publishable-source-adapters": ["low-code"], "schema": {"type": "array", "items": {"enum": ["sdk", "low-code"]}}, "explode": true},
      "OwnerType": {"name": "ownerType", "in": "query", "description": "Direct-owner filter; ownerType, ownerIssuer and ownerSubject must be supplied together", "x-require-together": ["ownerType", "ownerIssuer", "ownerSubject"], "schema": {"enum": ["principal", "service"]}},
      "OwnerIssuer": {"name": "ownerIssuer", "in": "query", "description": "Accepted immutable identity issuer; supplied together with ownerType and ownerSubject", "x-require-together": ["ownerType", "ownerIssuer", "ownerSubject"], "schema": {"type": "string", "format": "uri", "maxLength": 1024}},
      "OwnerSubject": {"name": "ownerSubject", "in": "query", "description": "Immutable subject at ownerIssuer; supplied together with ownerType and ownerIssuer", "x-require-together": ["ownerType", "ownerIssuer", "ownerSubject"], "schema": {"type": "string", "minLength": 1, "maxLength": 512}},
      "Cursor": {"name": "cursor", "in": "query", "schema": {"type": "string", "minLength": 1, "maxLength": 2048}},
      "Limit": {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}
    },
    "schemas": {
      "DirectOwner": {
        "type": "object",
        "additionalProperties": false,
        "required": ["type", "issuer", "subject"],
        "properties": {
          "type": {"enum": ["principal", "service"]},
          "issuer": {"type": "string", "format": "uri", "maxLength": 1024},
          "subject": {"type": "string", "minLength": 1, "maxLength": 512}
        }
      },
      "AgentProjection": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "implementationType", "lifecycleStatus", "selectedVersion", "publicationRevision", "sourceRevision", "updatedAt"],
        "properties": {
          "id": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Publisher-issued UUIDv7 Agent identity"},
          "name": {"type": "string", "pattern": "^[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?$"},
          "displayName": {"type": "string", "minLength": 1, "maxLength": 256},
          "description": {"type": "string", "maxLength": 4096},
          "owner": {"$ref": "#/components/schemas/DirectOwner"},
          "implementationType": {"enum": ["sdk", "low-code"], "description": "Compatibility classification; only low-code can be newly published in R2"},
          "lifecycleStatus": {"const": "active"},
          "selectedVersion": {"$ref": "#/components/schemas/AgentVersionProjection"},
          "publicationRevision": {"type": "integer", "minimum": 1},
          "sourceRevision": {"type": "integer", "minimum": 1},
          "updatedAt": {"type": "string", "format": "date-time"}
        }
      },
      "AgentVersionProjection": {
        "type": "object",
        "additionalProperties": false,
        "allOf": [
          {
            "if": {
              "properties": {"protocol": {"const": "a2a"}},
              "required": ["protocol"]
            },
            "then": {"required": ["interface"]}
          }
        ],
        "required": ["id", "version", "protocol", "protocolVersion", "artifactDigest", "capabilities", "skills"],
        "properties": {
          "id": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Publisher-issued UUIDv7 immutable version identity"},
          "version": {"type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"},
          "protocol": {"enum": ["a2a", "mcp"]},
          "protocolVersion": {"type": "string", "minLength": 1},
          "artifactDigest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
          "interface": {"$ref": "#/components/schemas/AgentInterface"},
          "capabilities": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
          "skills": {"type": "array", "items": {"$ref": "#/components/schemas/Skill"}}
        }
      },
      "AgentInterface": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url", "protocolBinding", "exposure", "authentication", "authorization", "backendAuthentication", "backendCredential", "originalBearerForwarded", "callerIdentityForwarded"],
        "properties": {
          "url": {"type": "string", "format": "uri", "pattern": "^(?:https://[^/]+|http://agent-gw\\.localhost:18087)/a2a/v1/agents/[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Stable logical-Agent route; selected AgentVersion remains protected projection metadata, not a consumer URL segment"},
          "protocolBinding": {"const": "HTTP+JSON"},
          "exposure": {"const": "public_gateway"},
          "authentication": {"const": "platform_oidc"},
          "authorization": {"const": "authenticated_all"},
          "backendAuthentication": {"const": "none"},
          "backendCredential": {"const": "none"},
          "originalBearerForwarded": {"const": false},
          "callerIdentityForwarded": {"const": false}
        }
      },
      "Skill": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name"],
        "properties": {
          "id": {"type": "string", "minLength": 1},
          "name": {"type": "string", "minLength": 1},
          "description": {"type": "string", "maxLength": 2048}
        }
      },
      "AgentListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items", "traceId"],
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/AgentProjection"}},
          "nextCursor": {"type": "string"},
          "traceId": {"$ref": "#/components/schemas/TraceId"}
        }
      },
      "SearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["query"],
        "properties": {
          "query": {"type": "string", "minLength": 1, "maxLength": 4096},
          "profileId": {"type": "string", "minLength": 1, "maxLength": 128},
          "protocols": {"type": "array", "items": {"enum": ["a2a"]}, "uniqueItems": true},
          "implementationTypes": {"type": "array", "items": {"enum": ["sdk", "low-code"]}, "uniqueItems": true},
          "topK": {"type": "integer", "minimum": 1, "maximum": 20, "default": 5},
          "minScore": {"type": "number", "minimum": 0, "maximum": 1, "description": "Narrowing threshold; effective value is max(platform floor, minScore)"}
        }
      },
      "SearchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["matches", "catalogVersion", "scoringProfileId", "traceId"],
        "properties": {
          "matches": {"type": "array", "items": {"$ref": "#/components/schemas/SearchMatch"}},
          "catalogVersion": {"type": "integer", "minimum": 1},
          "scoringProfileId": {"type": "string"},
          "traceId": {"$ref": "#/components/schemas/TraceId"}
        }
      },
      "SearchMatch": {
        "type": "object",
        "additionalProperties": false,
        "required": ["agentId", "agentVersionId", "name", "score", "componentScores", "matchedSkills", "cardRef"],
        "properties": {
          "agentId": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},
          "agentVersionId": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},
          "name": {"type": "string"},
          "score": {"type": "number", "minimum": 0, "maximum": 1},
          "componentScores": {"type": "object", "additionalProperties": false, "required": ["vector", "bm25"], "properties": {"vector": {"type": "number"}, "bm25": {"type": "number"}}},
          "matchedSkills": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
          "interface": {"$ref": "#/components/schemas/AgentInterface"},
          "cardRef": {"type": "string"}
        }
      },
      "Health": {"type": "object", "additionalProperties": false, "required": ["status"], "properties": {"status": {"enum": ["ok", "not_ready"]}}},
      "TraceId": {"type": "string", "pattern": "^[0-9a-f]{32}$"},
      "ErrorEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message", "traceId", "details"],
            "properties": {
              "code": {"type": "string"},
              "message": {"type": "string"},
              "traceId": {"$ref": "#/components/schemas/TraceId"},
              "details": {"type": "array", "items": {"type": "object"}}
            }
          }
        }
      }
    },
    "responses": {
      "InvalidRequest": {"description": "Malformed or invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Unauthenticated": {"description": "Missing or invalid management API authentication", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Forbidden": {"description": "Authenticated principal lacks the required direct permission", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "HiddenOrAbsent": {"description": "Resource is absent, inactive, or intentionally hidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "AuthorizationUnavailable": {"description": "Platform AuthZ is unavailable; no partial data is returned", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "SearchDependencyUnavailable": {"description": "Authorization, search, or embedding dependency unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}}
    }
  }
}