{
  "openapi": "3.1.2",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "Agent Registry API",
    "version": "0.1-draft",
    "description": "Permission-aware catalog and semantic discovery. No manual registration or invocation operations.",
    "x-contract-status": "proposed"
  },
  "servers": [{"url": "/"}],
  "security": [{"bearerAuth": []}],
  "paths": {
    "/api/v1/agents": {
      "get": {
        "operationId": "listAgents",
        "summary": "List Agents visible to the authenticated principal",
        "parameters": [
          {"$ref": "#/components/parameters/WorkspaceId"},
          {"$ref": "#/components/parameters/Protocol"},
          {"$ref": "#/components/parameters/ImplementationType"},
          {"$ref": "#/components/parameters/LifecycleStatus"},
          {"$ref": "#/components/parameters/Owner"},
          {"$ref": "#/components/parameters/Cursor"},
          {"$ref": "#/components/parameters/Limit"}
        ],
        "responses": {
          "200": {
            "description": "Permission-filtered page without hidden-resource totals",
            "content": {
              "application/json": {"schema": {"$ref": "#/components/schemas/AgentListResponse"}}
            }
          },
          "401": {"$ref": "#/components/responses/Unauthenticated"},
          "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}
        }
      }
    },
    "/api/v1/agents/{agentId}": {
      "get": {
        "operationId": "getAgent",
        "summary": "Get an Agent projection by opaque UUID",
        "parameters": [{"$ref": "#/components/parameters/AgentId"}],
        "responses": {
          "200": {
            "description": "Visible Agent projection; interface omitted without invoke permission",
            "content": {
              "application/json": {"schema": {"$ref": "#/components/schemas/AgentProjection"}}
            }
          },
          "401": {"$ref": "#/components/responses/Unauthenticated"},
          "404": {"$ref": "#/components/responses/HiddenOrAbsent"},
          "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}
        }
      }
    },
    "/api/v1/agents/search": {
      "post": {
        "operationId": "searchAgents",
        "summary": "Find invoke-allowed Agents with hybrid search",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {"schema": {"$ref": "#/components/schemas/SearchRequest"}}
          }
        },
        "responses": {
          "200": {
            "description": "Allowed matches; the array is empty when no permitted candidate is above threshold",
            "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"}
        }
      }
    },
    "/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"}
      },
      "WorkspaceId": {
        "name": "workspaceId",
        "in": "query",
        "schema": {"type": "string", "minLength": 1, "maxLength": 128}
      },
      "Protocol": {
        "name": "protocol",
        "in": "query",
        "schema": {"type": "array", "items": {"enum": ["a2a", "mcp"]}},
        "explode": true
      },
      "ImplementationType": {
        "name": "implementationType",
        "in": "query",
        "description": "Implementation family of the selected version; independent from protocol",
        "schema": {"type": "array", "items": {"enum": ["sdk", "low-code"]}},
        "explode": true
      },
      "LifecycleStatus": {
        "name": "lifecycleStatus",
        "in": "query",
        "schema": {
          "type": "array",
          "items": {"enum": ["active", "degraded", "rejected", "removed"]}
        },
        "explode": true
      },
      "Owner": {
        "name": "owner",
        "in": "query",
        "schema": {"type": "string", "minLength": 1, "maxLength": 128}
      },
      "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": {
      "AgentProjection": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "workspaceId", "name", "owner", "implementationType", "lifecycleStatus", "sourceRevision", "updatedAt"],
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "workspaceId": {"type": "string"},
          "name": {"type": "string"},
          "displayName": {"type": "string"},
          "description": {"type": "string"},
          "owner": {"type": "string"},
          "implementationType": {
            "description": "Implementation family projected from selectedVersion; catalog classification only",
            "enum": ["sdk", "low-code"]
          },
          "lifecycleStatus": {"enum": ["active", "degraded", "rejected", "removed"]},
          "selectedVersion": {"$ref": "#/components/schemas/AgentVersionProjection"},
          "sourceRevision": {"type": "integer", "minimum": 1},
          "updatedAt": {"type": "string", "format": "date-time"}
        }
      },
      "AgentVersionProjection": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "version", "protocol", "protocolVersion", "capabilities", "skills"],
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "version": {"type": "string"},
          "protocol": {"enum": ["a2a", "mcp"]},
          "protocolVersion": {"type": "string"},
          "interface": {"$ref": "#/components/schemas/AgentInterface"},
          "capabilities": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
          "skills": {"type": "array", "items": {"$ref": "#/components/schemas/Skill"}}
        }
      },
      "AgentInterface": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url", "protocolBinding", "exposure", "authorization"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "pattern": "^(?:https://[^/]+/(?:(a2a|mcp)/v1/agents/[0-9A-Fa-f-]+/versions/[0-9A-Fa-f-]+|a2a/[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?)|http://api-gw\\.localhost:18085/a2a/[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?)$"
          },
          "protocolBinding": {"type": "string"},
          "exposure": {"enum": ["public_gateway", "nonprod_direct"]},
          "authorization": {"enum": ["platform_oidc_spicedb", "none"]}
        },
        "oneOf": [
          {
            "properties": {
              "url": {
                "pattern": "^https://[^/]+/(?:a2a|mcp)/v1/agents/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/versions/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
              },
              "exposure": {"const": "public_gateway"},
              "authorization": {"const": "platform_oidc_spicedb"}
            }
          },
          {
            "properties": {
              "url": {
                "pattern": "^(?:https://[^/]+/a2a/[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?|http://api-gw\\.localhost:18085/a2a/[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?)$"
              },
              "exposure": {"const": "nonprod_direct"},
              "authorization": {"const": "none"}
            }
          }
        ]
      },
      "Skill": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name"],
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "description": {"type": "string"}
        }
      },
      "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", "workspaceId"],
        "properties": {
          "query": {"type": "string", "minLength": 1, "maxLength": 4096},
          "workspaceId": {"type": "string", "minLength": 1, "maxLength": 128},
          "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": "Optional narrowing threshold. Effective value is max(platform profile floor, minScore); it cannot widen results."
          }
        }
      },
      "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"},
          "agentVersionId": {"type": "string", "format": "uuid"},
          "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 authentication",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}
      },
      "Forbidden": {
        "description": "Authenticated principal is not permitted",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}
      },
      "HiddenOrAbsent": {
        "description": "Resource absent or intentionally hidden",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}
      },
      "AuthorizationUnavailable": {
        "description": "Authorization dependency unavailable; no partial data",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}
      },
      "SearchDependencyUnavailable": {
        "description": "Authorization, search or embedding dependency unavailable",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}
      }
    }
  }
}