{"openapi":"3.1.0","info":{"title":"Gate402 Registry API","version":"1.0.0","description":"Machine-readable API for Gate402 service discovery and service registration.\n\n🚀 MCP Server Available: For agent integration, use the Gate402 MCP server instead of raw REST API. It provides hosted discovery tools with automatic x402 payment handling where applicable. See https://github.com/gate402/agenthub/tree/main/apps/mcp-server/README.md"},"servers":[{"url":"https://gate402.io"}],"tags":[{"name":"System"},{"name":"Discovery"},{"name":"Services"},{"name":"Well-Known"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Health check","description":"Returns service health/status metadata.","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"ok":{"value":{"status":"ok","service":"agenthub-registry"}}}}}}}}},"/v1/openapi.json":{"get":{"tags":["System"],"summary":"OpenAPI document","description":"Returns this OpenAPI 3.1 spec.","responses":{"200":{"description":"OpenAPI spec JSON","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/search":{"get":{"tags":["Discovery"],"summary":"Search services","description":"Keyword/capability-oriented search with optional filters.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/capability"},{"$ref":"#/components/parameters/chain"},{"$ref":"#/components/parameters/tier"},{"$ref":"#/components/parameters/category"},{"$ref":"#/components/parameters/minPrice"},{"$ref":"#/components/parameters/maxPrice"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"examples":{"default":{"value":{"query":"weather","results":[{"id":"7d8c7304-772b-4ef2-b003-f495f499cf50","name":"WeatherWise API","description":"Real-time weather and 7-day forecast","provider_wallet":"0xabc123","chain":"base","x402_endpoint":"https://api.weatherwise.io/x402","pricing":{"price":"0.001","currency":"USDC"},"capabilities":["weather","forecast"],"category":"Data/Weather","verification_tier":"basic","status":"active","service_type":"native","tier":"pro","created_at":"2026-02-15T14:00:00.000Z","updated_at":"2026-02-15T14:00:00.000Z"}],"limit":25,"offset":0}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/categories":{"get":{"tags":["Discovery"],"summary":"List categories","description":"Returns hierarchical categories with service counts.","responses":{"200":{"description":"Category tree","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"},"examples":{"default":{"value":{"categories":[{"name":"Data","count":12,"subcategories":[{"name":"Weather","count":3,"subcategories":[]}]}],"count":1}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/capabilities":{"get":{"tags":["Discovery"],"summary":"List capability tags","description":"Returns unique capability tags from services.","parameters":[{"name":"limit","in":"query","description":"Max items (1-100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Capabilities list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilitiesResponse"},"examples":{"default":{"value":{"capabilities":["weather","forecast","translation","image-generation"]}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/services":{"post":{"tags":["Services"],"summary":"Create service","description":"Registers a new service. Requires provider auth.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServiceRequest"},"examples":{"native":{"value":{"name":"WeatherWise API","description":"Real-time weather and forecast","chain":"base","url":"https://api.weatherwise.io/x402","category":"Data/Weather","capabilities":["weather","forecast"],"pricing":{"price":"0.001","currency":"USDC"},"serviceType":"native","tier":"pro","manifestUrl":"https://api.weatherwise.io/.well-known/x402/manifest.json"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceMutationResponse"},"examples":{"created":{"value":{"success":true,"serviceId":"7d8c7304-772b-4ef2-b003-f495f499cf50","status":"active","message":"Service registered and discoverable in marketplace"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/services/{id}":{"get":{"tags":["Services"],"summary":"Get service by id","description":"Returns full service details.","parameters":[{"$ref":"#/components/parameters/serviceId"}],"responses":{"200":{"description":"Service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"tags":["Services"],"summary":"Update service","description":"Updates fields for a provider-owned service. Requires provider auth.","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/serviceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServiceRequest"},"examples":{"partial":{"value":{"description":"Real-time weather + severe-alert feed","status":"active","pricing":{"price":"0.002","currency":"USDC"}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceMutationResponse"},"examples":{"updated":{"value":{"success":true,"serviceId":"7d8c7304-772b-4ef2-b003-f495f499cf50"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["Services"],"summary":"Delete service","description":"Deletes a provider-owned service. Requires provider auth.","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/serviceId"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceMutationResponse"},"examples":{"deleted":{"value":{"success":true,"serviceId":"7d8c7304-772b-4ef2-b003-f495f499cf50"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/.well-known/x402":{"get":{"tags":["Well-Known"],"summary":"x402 network metadata","description":"Returns registry x402 payment/discovery metadata.","responses":{"200":{"description":"x402 metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WellKnownX402"},"examples":{"default":{"value":{"name":"Gate402 Registry","description":"x402 service marketplace registry","network":"base","currency":"USDC","facilitator":"https://facilitator.openx402.ai","version":"1.0.0","documentation":"/v1/openapi.json"}}}}}}}}},"/.well-known/cafe":{"get":{"tags":["Well-Known"],"summary":"Café Alpha easter egg","description":"Returns plain text easter egg; optional image via `format=image` or `Accept: image/*`.","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["image"]}}],"responses":{"200":{"description":"Text or image","content":{"text/plain":{"schema":{"type":"string"},"examples":{"text":{"value":"☕ Café Alpha is open..."}}},"image/jpeg":{"schema":{"type":"string","format":"binary"}}}}}}},"/.well-known/agent.json":{"get":{"tags":["Well-Known"],"summary":"Agent discovery metadata","description":"Machine-readable entry point for AI agents.","responses":{"200":{"description":"Agent metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WellKnownAgent"},"examples":{"default":{"value":{"name":"Gate402","description":"x402 service marketplace for AI agents","version":"1.0.0","endpoints":{"search":"/v1/search","categories":"/v1/categories","capabilities":"/v1/capabilities","openapi":"/v1/openapi.json"},"auth":{"type":"x402","network":"base","currency":"USDC"},"docs":{"human":"/docs","agent":"/v1/openapi.json","blog":"/blog"}}}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"serviceId":{"name":"id","in":"path","required":true,"description":"Service UUID","schema":{"type":"string","format":"uuid"}},"q":{"name":"q","in":"query","schema":{"type":"string"},"description":"Search text"},"capability":{"name":"capability","in":"query","schema":{"type":"string"},"description":"Capability/tag filter"},"chain":{"name":"chain","in":"query","schema":{"type":"string","example":"base"},"description":"Chain filter"},"tier":{"name":"tier","in":"query","schema":{"type":"string","enum":["free","pro","enterprise"]},"description":"Tier filter"},"category":{"name":"category","in":"query","schema":{"type":"string"}},"minPrice":{"name":"minPrice","in":"query","schema":{"type":"number","minimum":0}},"maxPrice":{"name":"maxPrice","in":"query","schema":{"type":"number","minimum":0}},"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"offset":{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"value":{"error":"Invalid payload","details":{"fieldErrors":{"name":["Required"]}}}}}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"value":{"error":"Unauthorized"}}}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notFound":{"value":{"error":"Service not found"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"default":{"value":{"error":"Internal server error"}}}}}}},"schemas":{"HealthResponse":{"type":"object","required":["status","service"],"properties":{"status":{"type":"string"},"service":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}},"additionalProperties":true},"Service":{"type":"object","required":["id","name","description"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"provider_wallet":{"type":"string"},"chain":{"type":["string","null"]},"x402_endpoint":{"type":["string","null"]},"pricing":{"type":"object","additionalProperties":true},"capabilities":{"type":"array","items":{}},"category":{"type":["string","null"]},"verification_tier":{"type":"string"},"status":{"type":"string"},"stats":{"type":"object","additionalProperties":true},"manifest":{"type":["object","null"],"additionalProperties":true},"service_type":{"type":"string","enum":["wrapped","native"]},"tier":{"type":"string","enum":["free","pro","enterprise"]},"manifest_url":{"type":["string","null"]},"manifest_validated":{"type":["boolean","null"]},"input_schema":{"type":["string","null"]},"response_format":{"type":["string","null"]},"docs_url":{"type":["string","null"]},"auth_notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"SearchResponse":{"type":"object","required":["query","results","limit","offset"],"properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"CategoryNode":{"type":"object","required":["name","count","subcategories"],"properties":{"name":{"type":"string"},"count":{"type":"integer"},"subcategories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryNode"}}}},"CategoriesResponse":{"type":"object","required":["categories","count"],"properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryNode"}},"count":{"type":"integer"}}},"CapabilitiesResponse":{"type":"object","required":["capabilities"],"properties":{"capabilities":{"type":"array","items":{"type":"string"}}}},"CreateServiceRequest":{"type":"object","required":["name","description"],"properties":{"id":{"type":"string"},"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"provider":{"type":"string"},"chain":{"type":"string"},"url":{"type":"string"},"inputSchema":{"type":"string"},"responseFormat":{"type":"string"},"docsUrl":{"type":"string"},"authNotes":{"type":"string"},"category":{"type":"string"},"pricing":{"type":"object","additionalProperties":true},"capabilities":{"type":"array","items":{}},"endpoints":{"type":"array","items":{}},"version":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"serviceType":{"type":"string","enum":["wrapped","native"],"default":"wrapped"},"manifestUrl":{"type":"string"},"tier":{"type":"string","enum":["free","pro","enterprise"],"default":"free"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"UpdateServiceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"chain":{"type":"string"},"url":{"type":"string"},"inputSchema":{"type":"string"},"responseFormat":{"type":"string"},"docsUrl":{"type":"string"},"authNotes":{"type":"string"},"category":{"type":"string"},"pricing":{"type":"object","additionalProperties":true},"capabilities":{"type":"array","items":{}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string"}},"additionalProperties":false},"ServiceMutationResponse":{"type":"object","required":["success","serviceId"],"properties":{"success":{"type":"boolean"},"serviceId":{"type":"string","format":"uuid"},"status":{"type":"string"},"message":{"type":"string"}}},"WellKnownX402":{"type":"object","required":["name","description","network","currency","facilitator","version","documentation"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"network":{"type":"string"},"currency":{"type":"string"},"facilitator":{"type":"string"},"version":{"type":"string"},"documentation":{"type":"string"}}},"WellKnownAgent":{"type":"object","required":["name","description","version","endpoints","auth","docs"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"auth":{"type":"object","required":["type","network","currency"],"properties":{"type":{"type":"string"},"network":{"type":"string"},"currency":{"type":"string"}}},"docs":{"type":"object","required":["human","agent","blog"],"properties":{"human":{"type":"string"},"agent":{"type":"string"},"blog":{"type":"string"}}}}}}}}