{"openapi":"3.1.0","info":{"title":"A2A Registry API","description":"Community-driven directory of AI agents using the A2A Protocol","version":"1.0.0"},"paths":{"/":{"get":{"summary":"Root","description":"API root - basic info","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health Check","description":"Health check endpoint for k8s","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agents/preview":{"post":{"summary":"Preview Agent","description":"Fetch and validate an Agent Card without registering it.","operationId":"preview_agent_agents_preview_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegister"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/register":{"post":{"summary":"Register Agent Simple","description":"Register an agent by its wellKnownURI.\n\nJust provide the wellKnownURI and we'll fetch the agent card automatically.\nThe agent card must be accessible and contain valid A2A Protocol fields.","operationId":"register_agent_simple_agents_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegister"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents":{"post":{"summary":"Register Agent Full","description":"Register a new agent with full payload.\n\nValidates ownership by fetching wellKnownURI and comparing key fields.\nFor a simpler flow, use POST /agents/register with just the wellKnownURI.","operationId":"register_agent_full_agents_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"List Agents","description":"List agents with optional filtering and pagination.\n\nQuery parameters:\n- search: Full-text search across name, description, and author\n- skill: Filter by skill ID\n- capability: Filter by A2A capability (e.g., \"streaming\")\n- author: Filter by author name (case-insensitive partial match)\n- conformance: Filter by conformance (\"standard\" or \"non-standard\")\n- healthy: Filter by health status (true = healthy, false = unhealthy)\n- task_verified: true = only agents whose last A2A message/send probe passed\n- category: category slug from GET /categories (matches primary or secondary)\n- limit: Max results to return (default: 50, max: 100)\n- offset: Pagination offset (default: 0)","operationId":"list_agents_agents_get","parameters":[{"name":"skill","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Skill"}},{"name":"capability","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Capability"}},{"name":"author","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"conformance","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conformance"}},{"name":"healthy","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Healthy"}},{"name":"task_verified","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Task Verified"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAgents"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/categories":{"get":{"summary":"List Categories","description":"The registry's agent categories with how many public agents are in each.\n\nDefined in one place (app/categories.py); the website and Jev both use it.","operationId":"list_categories_categories_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CategoryInfo"},"type":"array","title":"Response List Categories Categories Get"}}}}}}},"/agents/{agent_id}":{"get":{"summary":"Get Agent","description":"Get a single agent by ID with health metrics","operationId":"get_agent_agents__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"summary":"Update Agent","description":"Re-fetch and update an agent's metadata from its wellKnownURI.\n\nBy default re-fetches the agent's current wellKnownURI. To point the agent\nat a new discovery URL (e.g. its old host rotated or 404s), send a JSON body\n`{\"wellKnownURI\": \"https://new-host/.well-known/agent-card.json\"}`. The new\nURL is fetched, validated, and persisted on success. With no body the\nexisting URI is used (backward compatible).","operationId":"update_agent_agents__agent_id__put","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Agent","description":"Delete an agent (admin only).","operationId":"delete_agent_agents__agent_id__delete","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{agent_id}/recheck":{"post":{"summary":"Recheck Agent","description":"Re-run the A2A `message/send` probe for a listed agent now.\n\nFor operators who fixed their agent and do not want to wait for the daily\nprobe. It only probes the agent's registered wellKnownURI and updates its\ntask result and any registry-written note; it cannot change the listing's\nURL or content. Card metadata already refreshes from the live card every\nhealth cycle (30 min).","operationId":"recheck_agent_agents__agent_id__recheck_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{agent_id}/health":{"get":{"summary":"Get Agent Health","description":"Get current health status for an agent (last 24 hours)","operationId":"get_agent_health_agents__agent_id__health_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{agent_id}/uptime":{"get":{"summary":"Get Agent Uptime","description":"Get historical uptime metrics for an agent","operationId":"get_agent_uptime_agents__agent_id__uptime_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"period_days","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Period Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMetrics"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stats":{"get":{"summary":"Get Registry Stats","description":"Get registry-wide statistics","operationId":"get_registry_stats_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryStats"}}}}}}},"/agents/{agent_id}/flag":{"post":{"summary":"Flag Agent","description":"Community flag/report an agent","operationId":"flag_agent_agents__agent_id__flag_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFlag"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{agent_id}/chat":{"post":{"summary":"Chat With Agent","description":"Proxy a chat message to an agent via the a2a-sdk.","operationId":"chat_with_agent_agents__agent_id__chat_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{agent_id}/notes":{"patch":{"summary":"Update Maintainer Notes","description":"Set or clear maintainer notes for an agent (admin only). Supports markdown.","operationId":"update_maintainer_notes_agents__agent_id__notes_patch","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaintainerNotesUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/flags":{"get":{"summary":"List Flags","description":"List all agent flags (admin only)","operationId":"list_flags_admin_flags_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/review":{"get":{"summary":"List Review Queue","description":"Agents Jev flagged or could not classify, highest score first (admin only).","operationId":"list_review_queue_admin_review_get","parameters":[{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/agents/{agent_id}/review":{"post":{"summary":"Decide Review","description":"Approve (publish) or reject (keep hidden) a queued agent (admin only).\n\nApproval covers the scored content named by `card_sha256`; a later change\nis classified again. Unscored agents cannot be approved.","operationId":"decide_review_admin_agents__agent_id__review_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewDecision"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/":{"get":{"summary":"Root","description":"API root - basic info","operationId":"root_api__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/health":{"get":{"summary":"Health Check","description":"Health check endpoint for k8s","operationId":"health_check_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/agents/preview":{"post":{"summary":"Preview Agent","description":"Fetch and validate an Agent Card without registering it.","operationId":"preview_agent_api_agents_preview_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegister"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents/register":{"post":{"summary":"Register Agent Simple","description":"Register an agent by its wellKnownURI.\n\nJust provide the wellKnownURI and we'll fetch the agent card automatically.\nThe agent card must be accessible and contain valid A2A Protocol fields.","operationId":"register_agent_simple_api_agents_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegister"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents":{"post":{"summary":"Register Agent Full","description":"Register a new agent with full payload.\n\nValidates ownership by fetching wellKnownURI and comparing key fields.\nFor a simpler flow, use POST /agents/register with just the wellKnownURI.","operationId":"register_agent_full_api_agents_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"List Agents","description":"List agents with optional filtering and pagination.\n\nQuery parameters:\n- search: Full-text search across name, description, and author\n- skill: Filter by skill ID\n- capability: Filter by A2A capability (e.g., \"streaming\")\n- author: Filter by author name (case-insensitive partial match)\n- conformance: Filter by conformance (\"standard\" or \"non-standard\")\n- healthy: Filter by health status (true = healthy, false = unhealthy)\n- task_verified: true = only agents whose last A2A message/send probe passed\n- category: category slug from GET /categories (matches primary or secondary)\n- limit: Max results to return (default: 50, max: 100)\n- offset: Pagination offset (default: 0)","operationId":"list_agents_api_agents_get","parameters":[{"name":"skill","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Skill"}},{"name":"capability","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Capability"}},{"name":"author","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"conformance","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conformance"}},{"name":"healthy","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Healthy"}},{"name":"task_verified","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Task Verified"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAgents"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/categories":{"get":{"summary":"List Categories","description":"The registry's agent categories with how many public agents are in each.\n\nDefined in one place (app/categories.py); the website and Jev both use it.","operationId":"list_categories_api_categories_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CategoryInfo"},"type":"array","title":"Response List Categories Api Categories Get"}}}}}}},"/api/agents/{agent_id}":{"get":{"summary":"Get Agent","description":"Get a single agent by ID with health metrics","operationId":"get_agent_api_agents__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"summary":"Update Agent","description":"Re-fetch and update an agent's metadata from its wellKnownURI.\n\nBy default re-fetches the agent's current wellKnownURI. To point the agent\nat a new discovery URL (e.g. its old host rotated or 404s), send a JSON body\n`{\"wellKnownURI\": \"https://new-host/.well-known/agent-card.json\"}`. The new\nURL is fetched, validated, and persisted on success. With no body the\nexisting URI is used (backward compatible).","operationId":"update_agent_api_agents__agent_id__put","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPublic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Agent","description":"Delete an agent (admin only).","operationId":"delete_agent_api_agents__agent_id__delete","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents/{agent_id}/recheck":{"post":{"summary":"Recheck Agent","description":"Re-run the A2A `message/send` probe for a listed agent now.\n\nFor operators who fixed their agent and do not want to wait for the daily\nprobe. It only probes the agent's registered wellKnownURI and updates its\ntask result and any registry-written note; it cannot change the listing's\nURL or content. Card metadata already refreshes from the live card every\nhealth cycle (30 min).","operationId":"recheck_agent_api_agents__agent_id__recheck_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents/{agent_id}/health":{"get":{"summary":"Get Agent Health","description":"Get current health status for an agent (last 24 hours)","operationId":"get_agent_health_api_agents__agent_id__health_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents/{agent_id}/uptime":{"get":{"summary":"Get Agent Uptime","description":"Get historical uptime metrics for an agent","operationId":"get_agent_uptime_api_agents__agent_id__uptime_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"period_days","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Period Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMetrics"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/stats":{"get":{"summary":"Get Registry Stats","description":"Get registry-wide statistics","operationId":"get_registry_stats_api_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryStats"}}}}}}},"/api/agents/{agent_id}/flag":{"post":{"summary":"Flag Agent","description":"Community flag/report an agent","operationId":"flag_agent_api_agents__agent_id__flag_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFlag"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents/{agent_id}/chat":{"post":{"summary":"Chat With Agent","description":"Proxy a chat message to an agent via the a2a-sdk.","operationId":"chat_with_agent_api_agents__agent_id__chat_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agents/{agent_id}/notes":{"patch":{"summary":"Update Maintainer Notes","description":"Set or clear maintainer notes for an agent (admin only). Supports markdown.","operationId":"update_maintainer_notes_api_agents__agent_id__notes_patch","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaintainerNotesUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/flags":{"get":{"summary":"List Flags","description":"List all agent flags (admin only)","operationId":"list_flags_api_admin_flags_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/review":{"get":{"summary":"List Review Queue","description":"Agents Jev flagged or could not classify, highest score first (admin only).","operationId":"list_review_queue_api_admin_review_get","parameters":[{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/agents/{agent_id}/review":{"post":{"summary":"Decide Review","description":"Approve (publish) or reject (keep hidden) a queued agent (admin only).\n\nApproval covers the scored content named by `card_sha256`; a later change\nis classified again. Unscored agents cannot be approved.","operationId":"decide_review_api_admin_agents__agent_id__review_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"x-admin-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewDecision"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentCreate":{"properties":{"protocolVersion":{"type":"string","maxLength":100,"title":"Protocolversion"},"name":{"type":"string","maxLength":300,"title":"Name"},"description":{"type":"string","maxLength":32768,"title":"Description"},"author":{"type":"string","maxLength":300,"title":"Author"},"wellKnownURI":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Wellknownuri"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"version":{"type":"string","maxLength":100,"title":"Version"},"provider":{"anyOf":[{"$ref":"#/components/schemas/Provider"},{"type":"null"}]},"documentationUrl":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Documentationurl"},"iconUrl":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Iconurl"},"supportsAuthenticatedExtendedCard":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Supportsauthenticatedextendedcard"},"security":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Security"},"securitySchemes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Securityschemes"},"capabilities":{"$ref":"#/components/schemas/Capabilities"},"defaultInputModes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Defaultinputmodes"},"defaultOutputModes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Defaultoutputmodes"},"skills":{"items":{"$ref":"#/components/schemas/Skill"},"type":"array","maxItems":200,"title":"Skills"},"conformance":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Conformance"},"conformance_errors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Conformance Errors"},"homepage":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Homepage"},"repository":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Repository"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"pricing":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pricing"},"contact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact"}},"type":"object","required":["protocolVersion","name","description","author","wellKnownURI","url","version","capabilities","defaultInputModes","defaultOutputModes","skills"],"title":"AgentCreate","description":"Model for creating a new agent (POST /agents) - full payload"},"AgentFlag":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"reason":{"$ref":"#/components/schemas/FlagReason","default":"other"},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Details"}},"type":"object","required":["agent_id"],"title":"AgentFlag","description":"Community flag/report"},"AgentPublic":{"properties":{"protocolVersion":{"type":"string","maxLength":100,"title":"Protocolversion"},"name":{"type":"string","maxLength":300,"title":"Name"},"description":{"type":"string","maxLength":32768,"title":"Description"},"author":{"type":"string","maxLength":300,"title":"Author"},"wellKnownURI":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Wellknownuri"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"version":{"type":"string","maxLength":100,"title":"Version"},"provider":{"anyOf":[{"$ref":"#/components/schemas/Provider"},{"type":"null"}]},"documentationUrl":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Documentationurl"},"iconUrl":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Iconurl"},"supportsAuthenticatedExtendedCard":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Supportsauthenticatedextendedcard"},"security":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Security"},"securitySchemes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Securityschemes"},"capabilities":{"$ref":"#/components/schemas/Capabilities"},"defaultInputModes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Defaultinputmodes"},"defaultOutputModes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Defaultoutputmodes"},"skills":{"items":{"$ref":"#/components/schemas/Skill"},"type":"array","maxItems":200,"title":"Skills"},"conformance":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Conformance"},"conformance_errors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Conformance Errors"},"homepage":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Homepage"},"repository":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Repository"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"pricing":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pricing"},"contact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact"},"id":{"type":"string","format":"uuid","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"hidden":{"type":"boolean","title":"Hidden","default":false},"flag_count":{"type":"integer","title":"Flag Count","default":0},"maintainer_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maintainer Notes"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"category_secondary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Secondary"},"uptime_percentage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Uptime Percentage"},"avg_response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Avg Response Time Ms"},"last_health_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Health Check"},"is_healthy":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Healthy"},"status_notes":{"items":{"type":"string"},"type":"array","title":"Status Notes"},"task_conformance":{"anyOf":[{"$ref":"#/components/schemas/TaskConformance"},{"type":"null"}]}},"type":"object","required":["protocolVersion","name","description","author","wellKnownURI","url","version","capabilities","defaultInputModes","defaultOutputModes","skills","id","created_at","updated_at"],"title":"AgentPublic","description":"Public agent model with computed health metrics"},"AgentRegister":{"properties":{"wellKnownURI":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Wellknownuri"},"author":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Author"}},"type":"object","required":["wellKnownURI"],"title":"AgentRegister","description":"Simplified registration - just provide the wellKnownURI"},"Capabilities":{"properties":{"streaming":{"type":"boolean","title":"Streaming","default":false},"pushNotifications":{"type":"boolean","title":"Pushnotifications","default":false},"stateTransitionHistory":{"type":"boolean","title":"Statetransitionhistory","default":false},"extensions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Extensions"}},"type":"object","title":"Capabilities","description":"A2A Protocol Capabilities"},"CategoryInfo":{"properties":{"slug":{"type":"string","title":"Slug"},"label":{"type":"string","title":"Label"},"description":{"type":"string","title":"Description"},"agent_count":{"type":"integer","title":"Agent Count"}},"type":"object","required":["slug","label","description","agent_count"],"title":"CategoryInfo","description":"One registry category, as defined in app.categories."},"ChatRequest":{"properties":{"message":{"type":"string","title":"Message"},"context_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Id"}},"type":"object","required":["message"],"title":"ChatRequest"},"FlagReason":{"type":"string","enum":["spam","harmful","impersonation","other"],"title":"FlagReason"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthCheck":{"properties":{"id":{"type":"integer","title":"Id"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code"},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Time Ms"},"success":{"type":"boolean","title":"Success"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"type":"object","required":["id","agent_id","checked_at","success"],"title":"HealthCheck","description":"Health check record"},"HealthStatus":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"is_healthy":{"type":"boolean","title":"Is Healthy"},"uptime_percentage":{"type":"number","title":"Uptime Percentage"},"avg_response_time_ms":{"type":"integer","title":"Avg Response Time Ms"},"last_check":{"type":"string","format":"date-time","title":"Last Check"},"total_checks":{"type":"integer","title":"Total Checks"},"successful_checks":{"type":"integer","title":"Successful Checks"}},"type":"object","required":["agent_id","is_healthy","uptime_percentage","avg_response_time_ms","last_check","total_checks","successful_checks"],"title":"HealthStatus","description":"Current health status for an agent"},"MaintainerNotesUpdate":{"properties":{"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"MaintainerNotesUpdate"},"PaginatedAgents":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/AgentPublic"},"type":"array","title":"Agents"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["agents","total","limit","offset"],"title":"PaginatedAgents","description":"Paginated list of agents"},"Provider":{"properties":{"organization":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Organization"},"url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Url"}},"type":"object","title":"Provider","description":"Agent provider information"},"RegistryStats":{"properties":{"total_agents":{"type":"integer","title":"Total Agents"},"healthy_agents":{"type":"integer","title":"Healthy Agents"},"health_percentage":{"type":"number","title":"Health Percentage"},"new_agents_this_week":{"type":"integer","title":"New Agents This Week"},"new_agents_this_month":{"type":"integer","title":"New Agents This Month"},"total_skills":{"type":"integer","title":"Total Skills"},"trending_skills":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Trending Skills"},"avg_response_time_ms":{"type":"integer","title":"Avg Response Time Ms"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"}},"type":"object","required":["total_agents","healthy_agents","health_percentage","new_agents_this_week","new_agents_this_month","total_skills","avg_response_time_ms","generated_at"],"title":"RegistryStats","description":"Registry-wide statistics"},"ReviewDecision":{"properties":{"decision":{"type":"string","enum":["approve","reject"],"title":"Decision"},"card_sha256":{"type":"string","title":"Card Sha256"}},"type":"object","required":["decision","card_sha256"],"title":"ReviewDecision"},"Skill":{"properties":{"id":{"type":"string","maxLength":200,"title":"Id"},"name":{"type":"string","maxLength":300,"title":"Name"},"description":{"type":"string","maxLength":4096,"title":"Description"},"tags":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Tags"},"examples":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Examples"},"inputModes":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Inputmodes"},"outputModes":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Outputmodes"}},"type":"object","required":["id","name","description"],"title":"Skill","description":"A2A Protocol Skill definition"},"TaskConformance":{"properties":{"category":{"type":"string","title":"Category"},"passed":{"type":"boolean","title":"Passed"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"response_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Ms"}},"type":"object","required":["category","passed","checked_at"],"title":"TaskConformance","description":"Result of the most recent A2A `message/send` probe.\n\nSeparate from `conformance` (which validates the agent card schema).\nLets clients distinguish \"card looks right\" from \"endpoint actually works\"."},"UptimeMetrics":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"period_days":{"type":"integer","title":"Period Days","default":30},"uptime_percentage":{"type":"number","title":"Uptime Percentage"},"avg_response_time_ms":{"type":"integer","title":"Avg Response Time Ms"},"total_checks":{"type":"integer","title":"Total Checks"},"successful_checks":{"type":"integer","title":"Successful Checks"},"failed_checks":{"type":"integer","title":"Failed Checks"},"last_check":{"type":"string","format":"date-time","title":"Last Check"},"history":{"items":{"$ref":"#/components/schemas/HealthCheck"},"type":"array","title":"History"}},"type":"object","required":["agent_id","uptime_percentage","avg_response_time_ms","total_checks","successful_checks","failed_checks","last_check"],"title":"UptimeMetrics","description":"Historical uptime metrics for an agent"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}