{"info":{"title":"AI Data Agent Semantic API","version":"0.1.0"},"openapi":"3.1.0","paths":{"/.well-known/agent-card.json":{"get":{"responses":{"200":{"description":"Agent discovery metadata"}},"summary":"Machine-readable AI Data Agent discovery card for AI agents"}},"/.well-known/agent-demand.json":{"get":{"responses":{"200":{"description":"Demand probe manifest"}},"summary":"Machine-readable instructions for submitting unmet AI/Agent demand signals"}},"/api/v1/admin/access-logs":{"get":{"responses":{"200":{"description":"Recent agent access logs"}},"summary":"List recent external AI agent request logs with demand metadata"}},"/api/v1/admin/agent-demand":{"get":{"parameters":[{"in":"query","name":"window_hours","required":false,"schema":{"default":24,"type":"integer"}}],"responses":{"200":{"description":"Demand insight dashboard data"}},"summary":"Aggregate natural AI agent demand signals from search, fetch, payment, and download events"}},"/api/v1/admin/assets":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"api_auth_type":{"type":"string"},"api_endpoint_url":{"format":"uri","type":"string"},"api_input_schema":{"type":"string"},"api_method":{"type":"string"},"api_openapi_url":{"format":"uri","type":"string"},"api_output_schema":{"type":"string"},"api_protocol":{"type":"string"},"api_rate_limit":{"type":"string"},"api_usage_example":{"type":"string"},"asset_type":{"enum":["text","image","video","audio","dataset","api"],"type":"string"},"description":{"type":"string"},"license_terms":{"type":"string"},"mime_type":{"type":"string"},"price_amount":{"type":"string"},"price_currency":{"type":"string"},"source_url":{"format":"uri","type":"string"},"title":{"type":"string"}},"required":["title","asset_type"],"type":"object"}}},"required":true},"responses":{"201":{"description":"Asset registered and semantically indexed"}},"summary":"Create a URL-backed data asset or register an API endpoint for Agent discovery"}},"/api/v1/admin/assets/upload":{"post":{"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object"}}},"required":true},"responses":{"201":{"description":"Asset saved and indexed"}},"summary":"Upload a user-owned asset and index the user description as embedding"}},"/api/v1/admin/revenue-events":{"get":{"responses":{"200":{"description":"Revenue event ledger"}},"summary":"List user revenue events created by paid x402 asset deliveries"}},"/api/v1/admin/users":{"get":{"responses":{"200":{"description":"Known upload users"}},"summary":"List asset owners"},"post":{"responses":{"201":{"description":"Created user"}},"summary":"Create an asset owner for payout attribution"}},"/api/v1/agent-demand":{"get":{"parameters":[{"description":"Unmet data, API, tool, or service need","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"in":"query","name":"capability","required":false,"schema":{"type":"string"}},{"in":"query","name":"type","required":false,"schema":{"type":"string"}},{"in":"query","name":"urgency","required":false,"schema":{"type":"string"}},{"in":"query","name":"budget","required":false,"schema":{"type":"string"}},{"in":"query","name":"agent_id","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Probe instructions when no demand text is supplied"},"202":{"description":"Demand signal captured for ranking"}},"summary":"Submit or discover the public unmet-demand probe"},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string"},"asset_type":{"type":"string"},"asset_types":{"items":{"type":"string"},"type":"array"},"budget":{"type":"string"},"callback_url":{"type":"string"},"capability":{"type":"string"},"metadata":{"type":"object"},"need":{"type":"string"},"query":{"type":"string"},"task":{"type":"string"},"urgency":{"type":"string"},"use_case":{"type":"string"}},"type":"object"}}},"required":false},"responses":{"202":{"description":"Demand signal captured for ranking"}},"summary":"Capture an unmet AI/Agent data, tool, API, automation, or service demand signal"}},"/api/v1/agent-paywall":{"get":{"parameters":[{"description":"Paid data, API, tool, automation, or service need","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"capability","required":false,"schema":{"type":"string"}},{"in":"query","name":"type","required":false,"schema":{"type":"string"}},{"in":"query","name":"budget","required":false,"schema":{"type":"string"}},{"in":"query","name":"agent_id","required":false,"schema":{"type":"string"}}],"responses":{"402":{"description":"Paywall hit captured for demand ranking"}},"summary":"Return HTTP 402 and capture a high-intent unmet paid-demand signal"},"post":{"responses":{"402":{"description":"Paywall hit captured for demand ranking"}},"summary":"Capture an unmet paid-demand signal by intentionally returning HTTP 402"}},"/api/v1/assets/download/{asset_id}":{"get":{"parameters":[{"in":"path","name":"asset_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"expires","required":true,"schema":{"type":"integer"}},{"in":"query","name":"signature","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Asset bytes"},"403":{"description":"Invalid signed download URL"},"410":{"description":"Expired signed download URL"}},"summary":"Download a paid asset through a short-lived signed local-server URL"}},"/api/v1/assets/fetch":{"get":{"responses":{"200":{"description":"Paid delivery response"},"402":{"description":"Payment required"}},"summary":"Low-friction asset fetch challenge/payment check"},"post":{"responses":{"200":{"description":"Paid delivery response. delivery.type is signed_url for uploaded data and api_invocation for registered APIs."},"402":{"description":"Payment required"}},"summary":"Verify x402 payment and return signed data delivery or API invocation metadata"}},"/api/v1/assets/search":{"get":{"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"top_k","required":false,"schema":{"default":10,"type":"integer"}},{"in":"query","name":"type","required":false,"schema":{"enum":["text","image","video","audio","dataset","api"],"type":"string"}}],"responses":{"200":{"description":"Search results with metadata previews and x402 actions. API resources return output=api_invocation; data resources return output=signed_url."}},"summary":"Low-friction natural-language registry search for AI agents across data and API resources"},"post":{"responses":{"200":{"description":"Search results with metadata previews and x402 actions"}},"summary":"Hybrid semantic registry search for AI agents with text or 512D vector"}},"/api/v1/auth/login":{"post":{"responses":{"200":{"description":"Auth session"},"401":{"description":"Invalid credentials"}},"summary":"Login and receive a bearer token"}},"/api/v1/auth/me":{"get":{"responses":{"200":{"description":"Authenticated user"},"401":{"description":"Authentication required"}},"summary":"Return the authenticated principal"},"patch":{"responses":{"200":{"description":"Updated auth session"},"401":{"description":"Authentication required"}},"summary":"Update the authenticated user's profile and payout wallet"}},"/api/v1/auth/register":{"post":{"responses":{"201":{"description":"Auth session"}},"summary":"Register an upload user account"}},"/api/v1/capabilities":{"get":{"responses":{"200":{"description":"Capabilities document"}},"summary":"Semantic API capabilities and x402 payment headers"}},"/api/v1/flowers/prices/latest":{"get":{"description":"Capture-layer endpoint advertised for agents requesting latest or real-time fresh cut flower prices by variety, market, grade, unit, currency, and freshness timestamp.","parameters":[{"description":"Popular cut flower variety, for example rose, tulip, lily, carnation, orchid, peony, sunflower, hydrangea","in":"query","name":"variety","required":true,"schema":{"type":"string"}},{"description":"Flower market or city, for example Kunming, Amsterdam, Miami, Tokyo, London","in":"query","name":"market","required":false,"schema":{"type":"string"}},{"in":"query","name":"country","required":false,"schema":{"type":"string"}},{"in":"query","name":"grade","required":false,"schema":{"type":"string"}},{"in":"query","name":"stem_length","required":false,"schema":{"type":"string"}},{"description":"stem, bunch, box, kg, or tray","in":"query","name":"unit","required":false,"schema":{"type":"string"}},{"description":"USD, EUR, CNY, JPY, GBP, or local currency","in":"query","name":"currency","required":false,"schema":{"type":"string"}}],"responses":{"402":{"description":"Fresh cut flower price demand captured for ranking"}},"summary":"Capture latest fresh cut flower price demand"}},"/api/v1/flowers/prices/markets/{market}":{"get":{"description":"Path-style flower market price capture endpoint for latest wholesale and retail price lookup intent.","parameters":[{"in":"path","name":"market","required":true,"schema":{"type":"string"}},{"in":"query","name":"variety","required":false,"schema":{"type":"string"}},{"in":"query","name":"currency","required":false,"schema":{"type":"string"}}],"responses":{"402":{"description":"Flower market price demand captured for ranking"}},"summary":"Capture market-specific flower price demand"}},"/api/v1/flowers/prices/varieties/{variety}":{"get":{"description":"Path-style fresh flower variety price capture endpoint for autonomous sourcing, florist, wholesale, and event-planning agents.","parameters":[{"in":"path","name":"variety","required":true,"schema":{"type":"string"}},{"in":"query","name":"market","required":false,"schema":{"type":"string"}},{"in":"query","name":"currency","required":false,"schema":{"type":"string"}}],"responses":{"402":{"description":"Flower variety price demand captured for ranking"}},"summary":"Capture variety-specific flower price demand"}},"/api/v1/me/assets":{"get":{"responses":{"200":{"description":"User asset list"}},"summary":"List assets owned by the authenticated user"}},"/api/v1/me/finance":{"get":{"responses":{"200":{"description":"Owner finance snapshot"}},"summary":"Finance snapshot scoped to the authenticated owner"}},"/api/v1/me/revenue-events":{"get":{"responses":{"200":{"description":"Owner revenue events"}},"summary":"Revenue events scoped to the authenticated owner"}},"/api/v1/weather/cities/{city}":{"get":{"description":"Path-style city weather capture endpoint for autonomous agents.","parameters":[{"in":"path","name":"city","required":true,"schema":{"type":"string"}}],"responses":{"402":{"description":"Named city weather demand captured for ranking"}},"summary":"Capture named popular city weather demand"}},"/api/v1/weather/current":{"get":{"description":"Capture-layer weather endpoint advertised for agents. It intentionally records demand and returns HTTP 402 until live weather fulfillment exists.","parameters":[{"description":"Popular city name, for example Tokyo, London, New York, Singapore, Dubai","in":"query","name":"city","required":true,"schema":{"type":"string"}},{"in":"query","name":"country","required":false,"schema":{"type":"string"}},{"in":"query","name":"units","required":false,"schema":{"enum":["metric","imperial"],"type":"string"}}],"responses":{"402":{"description":"Weather demand captured for ranking"}},"summary":"Capture global popular city current weather demand"}},"/api/v1/weather/forecast":{"get":{"description":"Capture-layer forecast endpoint for agents requesting hourly or daily weather by city.","parameters":[{"in":"query","name":"city","required":true,"schema":{"type":"string"}},{"in":"query","name":"days","required":false,"schema":{"maximum":14,"minimum":1,"type":"integer"}},{"description":"Comma-separated weather variables such as temperature, rain, wind, air_quality, alerts","in":"query","name":"variables","required":false,"schema":{"type":"string"}}],"responses":{"402":{"description":"Weather forecast demand captured for ranking"}},"summary":"Capture global popular city forecast demand"}},"/api/v1/{capability_path}":{"get":{"description":"Any unknown /api/v1/* path is treated as an unmet capability signal and ranked as high-intent paywall demand.","parameters":[{"in":"path","name":"capability_path","required":true,"schema":{"type":"string"}},{"in":"query","name":"q","required":false,"schema":{"type":"string"}},{"in":"query","name":"query","required":false,"schema":{"type":"string"}},{"in":"query","name":"capability","required":false,"schema":{"type":"string"}},{"in":"query","name":"budget","required":false,"schema":{"type":"string"}}],"responses":{"402":{"description":"Unknown capability demand captured for ranking"}},"summary":"Maximum-coverage fallback: capture unknown AI/Agent capability demand as HTTP 402"},"post":{"description":"Captures query, prompt, messages, URL, operation, tool, action, and other common request fields as demand metadata.","responses":{"402":{"description":"Unknown capability demand captured for ranking"}},"summary":"Maximum-coverage fallback for arbitrary JSON/form/text capability requests"}},"/v1/{capability_path}":{"get":{"responses":{"402":{"description":"Unknown /v1 capability demand captured for ranking"}},"summary":"OpenAI-style fallback: capture unknown /v1/* AI demand as HTTP 402"},"post":{"responses":{"402":{"description":"Unknown /v1 capability demand captured for ranking"}},"summary":"OpenAI-style fallback for arbitrary model/tool requests"}}}}