{"openapi":"3.1.0","info":{"title":"toolidx","version":"0.1.0","description":"Agent-first MCP server directory. Evaluated, structured, queryable. https://toolidx.dev  \n**Last updated:** 2026-05-11 06:08:44"},"components":{"schemas":{},"parameters":{}},"paths":{"/v1/status":{"get":{"tags":["System"],"summary":"Service status and pipeline health","operationId":"get_StatusEndpoint","responses":{"200":{"description":"Service status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"last_updated":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp of last index update"},"result":{"type":"object","properties":{"service":{"type":"string"},"version":{"type":"string"},"ready":{"type":"boolean"},"description":{"type":"string"}},"required":["service","version","ready","description"]}},"required":["success","last_updated","result"]}}}}}}},"/v1/servers":{"get":{"tags":["Servers"],"summary":"List servers — compact summary, no tool schemas","operationId":"get_ServerList","parameters":[{"schema":{"type":"string","enum":["active","pending","rejected"],"default":"active"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["pending","passed","failed","error","skipped"]},"required":false,"name":"qc_status","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"is_proxy","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"hangs_on_start","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"requires_env_vars","in":"query"},{"schema":{"type":"string","enum":["github","gitlab","local"]},"required":false,"name":"qc_platform","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","minimum":1,"default":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"List of servers (compact — use GET /v1/servers/:id for full record, /v1/servers/:id/tools for schemas)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"repository_url":{"type":["string","null"]},"package_type":{"type":["string","null"]},"package_name":{"type":["string","null"]},"npm_version":{"type":["string","null"]},"install_command":{"type":["string","null"]},"qc_status":{"type":"string"},"tool_count":{"type":["number","null"]},"schema_weight_chars":{"type":["number","null"]},"install_duration_ms":{"type":["number","null"]},"tools_list_duration_ms":{"type":["number","null"]},"requires_env_vars":{"type":["boolean","null"]},"hangs_on_start":{"type":["boolean","null"]},"is_proxy":{"type":["boolean","null"]},"setup_complexity":{"type":["string","null"]},"qc_platform":{"type":["string","null"]},"quality_score":{"type":["number","null"]},"status":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","description","repository_url","package_type","package_name","npm_version","install_command","qc_status","tool_count","schema_weight_chars","install_duration_ms","tools_list_duration_ms","requires_env_vars","hangs_on_start","is_proxy","setup_complexity","qc_platform","quality_score","status","updated_at"]}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"}},"required":["success","result","total","page","limit"]}}}}}},"post":{"tags":["Servers"],"summary":"Create or update a server listing","security":[{"apiKey":[]}],"operationId":"post_ServerCreate","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Omit to derive from repository_url"},"name":{"type":"string"},"description":{"type":"string","default":""},"repository_url":{"type":"string"},"package_name":{"type":"string"},"package_type":{"type":"string","enum":["npm","uvx","pip"]},"install_command":{"type":"string"},"homepage_url":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"sanity_score":{"type":"number","minimum":0,"maximum":10},"quality_score":{"type":"number","minimum":0,"maximum":10},"status":{"type":"string","enum":["active","pending","rejected"],"default":"active"},"source":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"Server created or updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["success","result"]}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"}}}},"/v1/servers/{id}":{"get":{"tags":["Servers"],"summary":"Get a single server listing","operationId":"get_ServerGet","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":["boolean","null"],"default":false},"required":false,"name":"slim","in":"query"}],"responses":{"200":{"description":"Server record","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"repository_url":{"type":["string","null"]},"package_name":{"type":["string","null"]},"package_type":{"type":["string","null"]},"install_command":{"type":["string","null"]},"homepage_url":{"type":["string","null"]},"tags":{"type":["array","null"],"items":{"type":"string"}},"tool_schemas":{},"tool_count":{"type":["number","null"]},"qc_status":{"type":"string"},"qc_error":{"type":["string","null"]},"qc_tested_at":{"type":["string","null"]},"server_version":{"type":["string","null"]},"protocol_version":{"type":["string","null"]},"capabilities":{},"server_instructions":{"type":["string","null"]},"resources_list":{},"prompts_list":{},"has_destructive_tools":{"type":["boolean","null"]},"all_tools_readonly":{"type":["boolean","null"]},"install_duration_ms":{"type":["number","null"]},"tools_list_duration_ms":{"type":["number","null"]},"requires_env_vars":{"type":["boolean","null"]},"hangs_on_start":{"type":["boolean","null"]},"is_proxy":{"type":["boolean","null"]},"schema_weight_chars":{"type":["number","null"]},"qc_platform":{"type":["string","null"]},"sanity_score":{"type":["number","null"]},"quality_score":{"type":["number","null"]},"status":{"type":"string"},"source":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","description","repository_url","package_name","package_type","install_command","homepage_url","tags","tool_count","qc_status","qc_error","qc_tested_at","server_version","protocol_version","server_instructions","has_destructive_tools","all_tools_readonly","install_duration_ms","tools_list_duration_ms","requires_env_vars","hangs_on_start","is_proxy","schema_weight_chars","qc_platform","sanity_score","quality_score","status","source","created_at","updated_at"]}},"required":["success","result"]}}}},"404":{"description":"Not found"}}},"patch":{"tags":["Servers"],"summary":"Partial metadata update for a server (discovery agent use)","security":[{"apiKey":[]}],"operationId":"patch_ServerUpdate","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"install_command":{"type":"string"},"package_type":{"type":"string","enum":["npm","uvx","pip"]},"package_name":{"type":"string"},"npm_version":{"type":"string"},"min_node_version":{"type":"string"},"homepage_url":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","pending","rejected"]},"qc_status":{"type":"string","enum":["pending"]}}}}}},"responses":{"200":{"description":"Server updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["success","result"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/v1/servers/{id}/qc":{"patch":{"tags":["Servers"],"summary":"Update QC test result for a server","security":[{"apiKey":[]}],"operationId":"patch_ServerQcUpdate","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"qc_status":{"type":"string","enum":["passed","failed","error","skipped"]},"qc_error":{"type":["string","null"]},"tool_schemas":{"type":["array","null"],"items":{}},"server_version":{"type":["string","null"]},"protocol_version":{"type":["string","null"]},"capabilities":{"type":["object","null"],"additionalProperties":{}},"server_instructions":{"type":["string","null"]},"resources_list":{"type":["array","null"],"items":{}},"prompts_list":{"type":["array","null"],"items":{}},"has_destructive_tools":{"type":["boolean","null"]},"all_tools_readonly":{"type":["boolean","null"]},"install_duration_ms":{"type":["integer","null"]},"requires_env_vars":{"type":["boolean","null"]},"description_quality_score":{"type":["number","null"],"minimum":0,"maximum":10},"external_deps_detected":{"type":["array","null"],"items":{"type":"string"}},"setup_complexity":{"type":["string","null"],"enum":["low","medium","high"]},"hangs_on_start":{"type":["boolean","null"]},"tools_list_duration_ms":{"type":["integer","null"]},"qc_platform":{"type":["string","null"],"enum":["github","gitlab","cirrus","local","unknown"]},"schema_weight_chars":{"type":["integer","null"]},"failure_class":{"type":["string","null"],"enum":["install_fail_uvx_resolve","install_fail_npm_404","install_fail_npm_timeout","bad_entrypoint_shim","missing_env_vars","missing_external_dep","hangs_on_start","protocol_error","tools_list_empty","tools_list_error","auth_required","unknown"]}},"required":["qc_status"]}}}},"responses":{"200":{"description":"QC result updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["success","result"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/v1/servers/{id}/tools":{"get":{"tags":["Servers"],"summary":"Get tool schemas for a server (lazy load — avoids fetching in list)","operationId":"get_ServerTools","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Tool schemas","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":["object","null"],"properties":{"server_id":{"type":"string"},"tool_count":{"type":["number","null"]},"schema_weight_chars":{"type":["number","null"]},"tools":{"type":"array","items":{}}},"required":["server_id","tool_count","schema_weight_chars","tools"]}},"required":["success","result"]}}}},"404":{"description":"Not found"}}}},"/v1/servers/{id}/qc_tools":{"get":{"tags":["Servers"],"summary":"Get QC-aggregated tool results for a server","operationId":"get_ServerQcTools","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"platform","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":["boolean","null"],"default":true},"required":false,"name":"include_schema","in":"query"}],"responses":{"200":{"description":"QC tool results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"server_id":{"type":"string"},"total":{"type":"number"},"working":{"type":"number"},"broken":{"type":"number"},"needs_auth":{"type":"number"},"not_tested":{"type":"number"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string"},"platforms_agree":{"type":["boolean","null"]},"last_tested_at":{"type":["string","null"]},"not_tested_reason":{"type":["string","null"]},"platforms":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string"},"latency_ms":{"type":["number","null"]},"tested_at":{"type":"string"},"error_class":{"type":["string","null"]},"error_sample":{"type":["string","null"]}},"required":["status","latency_ms","tested_at","error_class","error_sample"]}}},"required":["name","status","platforms_agree","last_tested_at","platforms"]}}},"required":["server_id","total","working","broken","needs_auth","not_tested","tools"]}},"required":["success","result"]}}}},"404":{"description":"Not found"}}}},"/v1/tools":{"get":{"tags":["Tools"],"summary":"Search tools across all verified MCP servers","operationId":"get_ToolsSearch","parameters":[{"schema":{"type":"string","minLength":1,"description":"Search term matched against tool name and description"},"required":true,"description":"Search term matched against tool name and description","name":"q","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","minimum":1,"default":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"Matching tools with their server context","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"array","items":{"type":"object","properties":{"server_id":{"type":"string"},"server_name":{"type":"string"},"install_command":{"type":["string","null"]},"schema_weight_chars":{"type":["number","null"]},"tool":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{},"annotations":{}},"required":["name"]}},"required":["server_id","server_name","install_command","schema_weight_chars","tool"]}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"}},"required":["success","result","total","page","limit"]}}}}}}},"/v1/tools/test_args":{"patch":{"tags":["Tools"],"summary":"Upsert cached test args for a tool schema","security":[{"apiKey":[]}],"operationId":"patch_ToolTestArgs","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schema_hash":{"type":"string"},"args":{"type":"object","additionalProperties":{}},"generated_by":{"type":"string"}},"required":["schema_hash","args","generated_by"]}}}},"responses":{"200":{"description":"Test args saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"schema_hash":{"type":"string"}},"required":["success","schema_hash"]}}}},"401":{"description":"Unauthorized"}}}},"/internal/qc-archive":{"post":{"tags":["Internal"],"summary":"Archive a QC run to Gitea (immutable, forever retention)","security":[{"apiKey":[]}],"operationId":"post_QcArchive","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string"},"server_id":{"type":"string"},"platform":{"type":"string"},"runner_os":{"type":"string"},"runner_arch":{"type":"string"},"runner_runtime_version":{"type":"string"},"status":{"type":"string","enum":["passed","failed","error"]},"install_duration_ms":{"type":["integer","null"]},"tools_list_duration_ms":{"type":["integer","null"]},"tools_tested_count":{"type":["integer","null"]},"started_at":{"type":"string"},"finished_at":{"type":"string"},"error_class":{"type":["string","null"]},"tool_results":{"type":"array","items":{"type":"object","properties":{"tool_name":{"type":"string"},"status":{"type":"string","enum":["working","broken","needs-auth","not-tested","unknown"]},"latency_ms":{"type":["integer","null"]},"error_class":{"type":["string","null"]},"error_sample":{"type":["string","null"],"maxLength":500},"sample_args":{},"tested_at":{"type":"string"}},"required":["tool_name","status","tested_at"]},"default":[]},"tool_schemas":{"type":"array","items":{},"default":[]}},"required":["run_id","server_id","platform","status","started_at"]}}}},"responses":{"200":{"description":"Archived (or already exists)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"path":{"type":"string"},"already_existed":{"type":"boolean"},"gitea_sha":{"type":"string"}},"required":["path","already_existed"]}},"required":["success","result"]}}}},"401":{"description":"Unauthorized"},"502":{"description":"Gitea API error"}}}}},"webhooks":{}}