{ "openapi": "3.1.0", "info": { "title": "AgentReady API", "version": "1.0.0", "description": "Yellow Pages for AI Agents — a scored directory of AI-agent-friendly websites and services. Scored across 27+ signals for agent compatibility.", "contact": { "name": "AgentReady", "url": "https://agentready.info" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://agentready.info", "description": "Production" } ], "paths": { "/api/v1/agent/check-in": { "post": { "operationId": "agentCheckIn", "summary": "Register an agent session", "description": "Check in as an AI agent to receive a 1-hour API key for authenticated endpoints.", "tags": ["Agent"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInInput" } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CheckInResponse" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/sites": { "get": { "operationId": "listSites", "summary": "List sites", "description": "Paginated list of sites with optional filters by tier, category, and minimum score.", "tags": ["Sites"], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "tier", "in": "query", "schema": { "$ref": "#/components/schemas/Tier" } }, { "name": "category_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "min_score", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["score", "newest", "name"], "default": "score" }, "description": "Sort order: score (default), newest, name" } ], "responses": { "200": { "description": "Paginated site list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "post": { "operationId": "createSite", "summary": "Submit a new site", "description": "Submit a website for inclusion in the directory. Requires authentication.", "tags": ["Sites"], "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteInput" } } } }, "responses": { "201": { "description": "Site created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Site" } } } } } } } } }, "/api/v1/sites/{slug}": { "get": { "operationId": "getSite", "summary": "Get site details", "description": "Get detailed information about a site including its agent-readiness score and signal breakdown.", "tags": ["Sites"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Site details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Site" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateSite", "summary": "Update a site", "description": "Update site details. Requires ownership or admin role.", "tags": ["Sites"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteInput" } } } }, "responses": { "200": { "description": "Site updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Site" } } } } } } } } }, "/api/v1/search": { "get": { "operationId": "searchSites", "summary": "Search sites", "description": "Full-text search across site names, descriptions, and domains.", "tags": ["Search"], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/categories": { "get": { "operationId": "listCategories", "summary": "List categories", "description": "List all site categories in the directory.", "tags": ["Categories"], "responses": { "200": { "description": "Category list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } } } } }, "/api/v1/categories/{slug}": { "get": { "operationId": "getCategory", "summary": "Get category details", "description": "Get category details with subcategories.", "tags": ["Categories"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Category with subcategories", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CategoryWithSubcategories" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/categories/{slug}/sites": { "get": { "operationId": "categorySites", "summary": "List sites in a category", "description": "Paginated list of sites belonging to a specific category.", "tags": ["Categories"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Sites in category", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/stats": { "get": { "operationId": "getStats", "summary": "Directory statistics", "description": "Get aggregate statistics about the directory.", "tags": ["Stats"], "responses": { "200": { "description": "Directory stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DirectoryStats" } } } } } } } } }, "/api/v1/recommend": { "get": { "operationId": "recommend", "summary": "Get recommendations", "description": "Get site recommendations based on a use case description. Requires agent check-in.", "tags": ["Agent"], "security": [{ "agentAuth": [] }], "parameters": [ { "name": "use_case", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Recommended sites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } } } } } } }, "/api/v1/compare": { "get": { "operationId": "compare", "summary": "Compare sites", "description": "Compare multiple sites side-by-side. Requires agent check-in.", "tags": ["Agent"], "security": [{ "agentAuth": [] }], "parameters": [ { "name": "slugs", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated site slugs (1-5)" } ], "responses": { "200": { "description": "Compared sites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } } } } } } }, "/api/v1/trending": { "get": { "operationId": "trending", "summary": "Trending sites", "description": "Get sites trending by agent activity. Requires agent check-in.", "tags": ["Agent"], "security": [{ "agentAuth": [] }], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "period_hours", "in": "query", "schema": { "type": "integer", "default": 24 } } ], "responses": { "200": { "description": "Trending sites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingSite" } } } } } } } } } }, "/api/v1/auth/register": { "post": { "operationId": "register", "summary": "Register a new user", "tags": ["Auth"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "201": { "description": "User registered" } } } }, "/api/v1/auth/login": { "post": { "operationId": "login", "summary": "Login", "tags": ["Auth"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful, returns access + refresh tokens" } } } }, "/api/v1/auth/me": { "get": { "operationId": "me", "summary": "Get current user", "tags": ["Auth"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Current user info" } } } }, "/api/v1/auth/refresh": { "post": { "operationId": "refreshToken", "summary": "Refresh auth tokens", "description": "Exchange a valid refresh token for a new access token and refresh token pair.", "tags": ["Auth"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["refresh_token"], "properties": { "refresh_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "New token pair returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "integer" } } } } } }, "401": { "description": "Invalid or expired refresh token" } } } }, "/api/v1/auth/password": { "put": { "operationId": "changePassword", "summary": "Change password", "description": "Change the authenticated user's password.", "tags": ["Auth"], "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["current_password", "new_password"], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "200": { "description": "Password changed successfully" }, "401": { "description": "Current password incorrect" } } } }, "/api/v1/auth/profile": { "put": { "operationId": "updateProfile", "summary": "Update profile", "description": "Update the authenticated user's display name and company name.", "tags": ["Auth"], "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "maxLength": 100 }, "company_name": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Profile updated" } } } }, "/api/v1/dashboard": { "get": { "operationId": "getDashboard", "summary": "Dashboard summary", "description": "Get an overview of the authenticated user's sites, payments, and activity.", "tags": ["Dashboard"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Dashboard summary data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total_sites": { "type": "integer" }, "verified_sites": { "type": "integer" }, "enhanced_sites": { "type": "integer" }, "total_payments": { "type": "integer" }, "recent_activity": { "type": "array", "items": { "type": "object" } } } } } } } } } } } }, "/api/v1/dashboard/sites": { "get": { "operationId": "getDashboardSites", "summary": "Dashboard sites list", "description": "List all sites owned by the authenticated user.", "tags": ["Dashboard"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "User's sites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/dashboard/sites/{slug}/analytics": { "get": { "operationId": "getSiteAnalytics", "summary": "Site analytics", "description": "Get analytics data for a specific site owned by the authenticated user.", "tags": ["Dashboard"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["7d", "30d", "90d"], "default": "30d" } } ], "responses": { "200": { "description": "Site analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "views": { "type": "integer" }, "agent_visits": { "type": "integer" }, "score_history": { "type": "array", "items": { "type": "object" } }, "referrers": { "type": "array", "items": { "type": "object" } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/dashboard/payments": { "get": { "operationId": "getDashboardPayments", "summary": "Dashboard payment history", "description": "List payment history for the authenticated user.", "tags": ["Dashboard"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Payment history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/payments": { "get": { "operationId": "listPayments", "summary": "List payments", "description": "List payments made by the authenticated user.", "tags": ["Payments"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "confirmed", "failed"] } } ], "responses": { "200": { "description": "Payment list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Get payment by ID", "description": "Retrieve details of a specific payment.", "tags": ["Payments"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/sites/{slug}/verify": { "post": { "operationId": "initiateSiteVerification", "summary": "Initiate site verification", "description": "Start the verification process for a site. Returns a verification token to place on the target site.", "tags": ["Verification"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "verification_token": { "type": "string" }, "method": { "type": "string", "enum": ["dns", "meta_tag", "file"] }, "instructions": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/api/v1/sites/{slug}/verify/status": { "get": { "operationId": "getVerificationStatus", "summary": "Check verification status", "description": "Check the current verification status of a site.", "tags": ["Verification"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "is_verified": { "type": "boolean" }, "method": { "type": "string" }, "verified_at": { "type": "string", "format": "date-time" }, "pending": { "type": "boolean" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/sites/{slug}/verify/confirm": { "post": { "operationId": "confirmSiteVerification", "summary": "Confirm site verification", "description": "Confirm that the verification token has been placed and trigger server-side validation.", "tags": ["Verification"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Verification token not found on target site" } } } }, "/api/v1/sites/{slug}/enhanced": { "post": { "operationId": "createEnhancedProfile", "summary": "Create enhanced profile", "description": "Create an enhanced listing profile for a site. Requires x402 payment.", "tags": ["Enhanced"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tagline": { "type": "string", "maxLength": 200 }, "long_description": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "use_cases": { "type": "array", "items": { "type": "string" } }, "pricing_info": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "social_links": { "type": "object" } } } } } }, "responses": { "201": { "description": "Enhanced profile created (pending review)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EnhancedProfile" } } } } } }, "402": { "description": "Payment required via x402 protocol", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequirement" } } } } } }, "put": { "operationId": "updateEnhancedProfile", "summary": "Update enhanced profile", "description": "Update an existing enhanced listing profile.", "tags": ["Enhanced"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tagline": { "type": "string", "maxLength": 200 }, "long_description": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "use_cases": { "type": "array", "items": { "type": "string" } }, "pricing_info": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "social_links": { "type": "object" } } } } } }, "responses": { "200": { "description": "Enhanced profile updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EnhancedProfile" } } } } } } } }, "get": { "operationId": "getEnhancedProfile", "summary": "Get enhanced profile", "description": "Retrieve the enhanced listing profile for a site.", "tags": ["Enhanced"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Enhanced profile data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EnhancedProfile" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/admin/enhanced/{id}/review": { "put": { "operationId": "reviewEnhancedProfile", "summary": "Review enhanced profile (admin)", "description": "Approve or reject a pending enhanced profile submission.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["approve", "reject"] }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Enhanced profile reviewed" } } } }, "/api/v1/featured/bid": { "post": { "operationId": "placeFeaturedBid", "summary": "Place featured bid", "description": "Place a bid for a featured slot via Dutch auction. Requires x402 payment.", "tags": ["Featured"], "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["site_slug", "bid_amount_usdc"], "properties": { "site_slug": { "type": "string" }, "bid_amount_usdc": { "type": "string", "description": "Bid amount in USDC (e.g. '150.00')" }, "duration_days": { "type": "integer", "default": 7 } } } } } }, "responses": { "201": { "description": "Bid placed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeaturedSlot" } } } } } }, "402": { "description": "Payment required via x402 protocol", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequirement" } } } } } } }, "/api/v1/featured/displace/{slot_id}": { "post": { "operationId": "displaceFeaturedSlot", "summary": "Displace featured slot", "description": "Displace an existing featured slot by paying the current displacement price. Requires x402 payment.", "tags": ["Featured"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slot_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["site_slug"], "properties": { "site_slug": { "type": "string" } } } } } }, "responses": { "200": { "description": "Slot displaced successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeaturedSlot" } } } } } }, "402": { "description": "Payment required via x402 protocol", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequirement" } } } } } } }, "/api/v1/featured": { "get": { "operationId": "listFeaturedSlots", "summary": "List active featured slots", "description": "Get all currently active featured listing slots.", "tags": ["Featured"], "responses": { "200": { "description": "Active featured slots", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeaturedSlot" } } } } } } } } } }, "/api/v1/featured/{slot_id}": { "get": { "operationId": "getFeaturedSlot", "summary": "Get featured slot details", "description": "Get details of a specific featured slot including current displacement price.", "tags": ["Featured"], "parameters": [ { "name": "slot_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Featured slot details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeaturedSlot" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/public/trending": { "get": { "operationId": "publicTrending", "summary": "Public trending sites", "description": "Get trending sites without authentication. Limited data compared to the agent-authenticated endpoint.", "tags": ["Public"], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Public trending sites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingSite" } } } } } } } } } }, "/api/v1/public/compare": { "get": { "operationId": "publicCompare", "summary": "Public compare sites", "description": "Compare sites without authentication. Limited data compared to the agent-authenticated endpoint.", "tags": ["Public"], "parameters": [ { "name": "slugs", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated site slugs (1-5)" } ], "responses": { "200": { "description": "Compared sites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } } } } } } }, "/api/v1/admin/stats": { "get": { "operationId": "adminStats", "summary": "Admin statistics", "description": "Get comprehensive admin statistics including user counts, revenue, and system health.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Admin statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total_users": { "type": "integer" }, "total_sites": { "type": "integer" }, "pending_sites": { "type": "integer" }, "total_revenue_usdc": { "type": "string" }, "active_featured_slots": { "type": "integer" }, "active_agents": { "type": "integer" } } } } } } } } } } }, "/api/v1/admin/sites": { "get": { "operationId": "adminListSites", "summary": "Admin site listing", "description": "List all sites with admin-level detail including status, owner, and moderation history.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/SiteStatus" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Admin site list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/admin/users": { "get": { "operationId": "adminListUsers", "summary": "Admin user listing", "description": "List all users with admin-level detail.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "role", "in": "query", "schema": { "type": "string", "enum": ["user", "moderator", "admin", "superadmin"] } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/admin/users/{id}/role": { "put": { "operationId": "adminUpdateUserRole", "summary": "Update user role (admin)", "description": "Change a user's role. Requires admin or superadmin.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["role"], "properties": { "role": { "type": "string", "enum": ["user", "moderator", "admin", "superadmin"] } } } } } }, "responses": { "200": { "description": "User role updated" } } } }, "/api/v1/admin/users/{id}/status": { "put": { "operationId": "adminUpdateUserStatus", "summary": "Update user status (admin)", "description": "Activate or suspend a user account.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["active", "suspended"] } } } } } }, "responses": { "200": { "description": "User status updated" } } } }, "/api/v1/admin/enhanced/pending": { "get": { "operationId": "adminListPendingEnhanced", "summary": "List pending enhanced profiles (admin)", "description": "List all enhanced profiles awaiting admin review.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Pending enhanced profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnhancedProfile" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/admin/agents": { "get": { "operationId": "adminListAgents", "summary": "Agent overview (admin)", "description": "List active and recent agent sessions with usage statistics.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "active_only", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Agent sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/admin/payments": { "get": { "operationId": "adminListPayments", "summary": "Admin payments", "description": "List all payments across the platform with filtering.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "confirmed", "failed"] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["enhanced", "featured", "other"] } } ], "responses": { "200": { "description": "Payment list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/admin/featured": { "get": { "operationId": "adminListFeatured", "summary": "Admin featured slots", "description": "List all featured slots including expired ones.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "include_expired", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Featured slots", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeaturedSlot" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/api/v1/admin/featured/{id}": { "delete": { "operationId": "adminForceExpireFeatured", "summary": "Force expire featured slot (admin)", "description": "Forcibly expire a featured slot before its natural expiration.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Featured slot expired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/admin/scan/all-unscored": { "post": { "operationId": "adminScanAllUnscored", "summary": "Scan all unscored sites (admin)", "description": "Enqueue scans for all sites that have not yet been scored.", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Scan jobs enqueued", "content": { "application/json": { "schema": { "type": "object", "properties": { "enqueued": { "type": "integer" } } } } } } } } }, "/api/v1/admin/bootstrap": { "post": { "operationId": "adminBootstrap", "summary": "Bootstrap first admin", "description": "Create the first superadmin account. Only works when no admin users exist in the system.", "tags": ["Admin"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "201": { "description": "First admin created" }, "409": { "description": "Admin user already exists" } } } }, "/api/v1/admin/sites/{slug}/{action}": { "put": { "operationId": "updateSiteStatus", "summary": "Update site status (admin)", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": ["approve", "reject", "suspend"] } } ], "responses": { "200": { "description": "Status updated" } } } }, "/api/v1/admin/scan/{slug}": { "post": { "operationId": "triggerScan", "summary": "Trigger site scan (admin)", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scan enqueued" } } } }, "/api/v1/admin/scan/bulk": { "post": { "operationId": "triggerBulkScan", "summary": "Trigger bulk scan (admin)", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Bulk scan enqueued" } } } }, "/api/v1/admin/scan/queue": { "get": { "operationId": "queueStatus", "summary": "Get scan queue status (admin)", "tags": ["Admin"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Queue status" } } } }, "/api/v1/sites/{slug}/rescan": { "post": { "operationId": "requestRescan", "summary": "Request site rescan", "tags": ["Sites"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rescan enqueued" } } } }, "/api/v1/sites/{slug}/scan-history": { "get": { "operationId": "scanHistory", "summary": "Get scan history for a site", "tags": ["Sites"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scan history" } } } }, "/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "description": "Returns service health status including database and Redis connectivity.", "tags": ["System"], "responses": { "200": { "description": "Service is healthy" } } } }, "/ready": { "get": { "operationId": "readinessCheck", "summary": "Readiness check", "description": "Returns whether the service is ready to accept traffic. Used by load balancers and orchestrators.", "tags": ["System"], "responses": { "200": { "description": "Service is ready" }, "503": { "description": "Service is not ready" } } } }, "/ws": { "get": { "operationId": "webSocketLiveTicker", "summary": "WebSocket live ticker", "description": "WebSocket connection for real-time agent activity, new site submissions, and score changes. Upgrade to WebSocket protocol required.", "tags": ["WebSocket"], "responses": { "101": { "description": "Switching protocols to WebSocket" } } } }, "/graphql": { "post": { "operationId": "graphqlQuery", "summary": "GraphQL endpoint", "description": "Execute GraphQL queries against the AgentReady API.", "tags": ["GraphQL"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string" }, "variables": { "type": "object" }, "operationName": { "type": "string" } } } } } }, "responses": { "200": { "description": "GraphQL response" } } } }, "/mcp": { "post": { "operationId": "mcpEndpoint", "summary": "MCP server endpoint", "description": "Model Context Protocol (MCP) server endpoint using Streamable HTTP transport. Agents can discover and invoke tools for querying the directory.", "tags": ["MCP"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["jsonrpc", "method"], "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "id": { "type": ["string", "integer"] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "MCP JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": ["string", "integer"] }, "result": { "type": "object" }, "error": { "type": "object" } } } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "LLM-friendly documentation", "description": "Returns a plain-text summary of the AgentReady API designed for consumption by large language models.", "tags": ["AI Docs"], "responses": { "200": { "description": "LLM-friendly text documentation", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullTxt", "summary": "Full LLM documentation", "description": "Returns comprehensive plain-text documentation of all AgentReady endpoints, schemas, and usage patterns for LLMs.", "tags": ["AI Docs"], "responses": { "200": { "description": "Full LLM-friendly text documentation", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/.well-known/mcp.json": { "get": { "operationId": "getMcpManifest", "summary": "MCP server manifest", "description": "Returns the MCP server manifest describing available tools, resources, and transport configuration.", "tags": ["AI Docs"], "responses": { "200": { "description": "MCP manifest", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "transport": { "type": "object" } } } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "OpenAPI specification", "description": "Returns this OpenAPI 3.1 specification document.", "tags": ["AI Docs"], "responses": { "200": { "description": "OpenAPI spec", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/ai-plugin.json": { "get": { "operationId": "getAiPluginManifest", "summary": "AI plugin manifest", "description": "Returns the AI plugin manifest for ChatGPT and compatible AI agent platforms.", "tags": ["AI Docs"], "responses": { "200": { "description": "AI plugin manifest", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "string" }, "name_for_human": { "type": "string" }, "name_for_model": { "type": "string" }, "description_for_human": { "type": "string" }, "description_for_model": { "type": "string" }, "api": { "type": "object" }, "auth": { "type": "object" } } } } } } } } }, "/sitemap.xml": { "get": { "operationId": "getSitemap", "summary": "XML sitemap", "description": "Returns an XML sitemap of all public pages for search engine crawlers.", "tags": ["Feeds"], "responses": { "200": { "description": "XML sitemap", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/feed.xml": { "get": { "operationId": "getRssFeed", "summary": "RSS feed", "description": "Returns an RSS feed of recently added and updated sites.", "tags": ["Feeds"], "responses": { "200": { "description": "RSS feed", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "domain": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "subcategory_id": { "type": "string", "format": "uuid" }, "agent_ready_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "tier": { "$ref": "#/components/schemas/Tier" }, "score_breakdown": { "type": "object" }, "last_scanned_at": { "type": "string", "format": "date-time" }, "scan_version": { "type": "integer" }, "status": { "$ref": "#/components/schemas/SiteStatus" }, "is_verified": { "type": "boolean" }, "is_enhanced": { "type": "boolean" }, "logo_url": { "type": "string", "format": "uri" }, "screenshot_url": { "type": "string", "format": "uri" }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "display_order": { "type": "integer" }, "site_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "CategoryWithSubcategories": { "allOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "object", "properties": { "subcategories": { "type": "array", "items": { "$ref": "#/components/schemas/Subcategory" } } } } ] }, "Subcategory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "site_count": { "type": "integer" } } }, "Tier": { "type": "string", "enum": ["platinum", "gold", "silver", "bronze", "basic", "unscored"] }, "SiteStatus": { "type": "string", "enum": ["pending", "active", "rejected", "suspended", "claimed"] }, "CheckInInput": { "type": "object", "required": ["agent_name", "agent_description", "purpose"], "properties": { "agent_name": { "type": "string", "maxLength": 100 }, "agent_description": { "type": "string" }, "purpose": { "type": "string" }, "agent_version": { "type": "string" }, "agent_provider": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "callback_url": { "type": "string", "format": "uri" } } }, "CheckInResponse": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "api_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "rate_limit": { "$ref": "#/components/schemas/RateLimitInfo" }, "welcome": { "type": "string" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointInfo" } } } }, "RateLimitInfo": { "type": "object", "properties": { "requests_per_minute": { "type": "integer" }, "total_session_requests": { "type": "integer" }, "session_duration_minutes": { "type": "integer" } } }, "EndpointInfo": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "description": { "type": "string" } } }, "TrendingSite": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "domain": { "type": "string" }, "tier": { "type": "string" }, "agent_ready_score": { "type": "integer" }, "view_count": { "type": "integer" } } }, "DirectoryStats": { "type": "object", "properties": { "total_sites": { "type": "integer" }, "active_sites": { "type": "integer" }, "pending_sites": { "type": "integer" }, "total_categories": { "type": "integer" }, "total_users": { "type": "integer" }, "platinum_sites": { "type": "integer" }, "gold_sites": { "type": "integer" }, "silver_sites": { "type": "integer" }, "bronze_sites": { "type": "integer" }, "average_score": { "type": "number" } } }, "CreateSiteInput": { "type": "object", "required": ["url", "name"], "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "description": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "UpdateSiteInput": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "PaginationMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "site_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["enhanced", "featured", "other"] }, "amount_usdc": { "type": "string" }, "tx_hash": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "confirmed", "failed"] }, "network": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": "string", "format": "date-time" } } }, "EnhancedProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_id": { "type": "string", "format": "uuid" }, "tagline": { "type": "string" }, "long_description": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "use_cases": { "type": "array", "items": { "type": "string" } }, "pricing_info": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "social_links": { "type": "object" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected"] }, "reviewed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FeaturedSlot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_id": { "type": "string", "format": "uuid" }, "site_name": { "type": "string" }, "site_slug": { "type": "string" }, "slot_position": { "type": "integer" }, "bid_amount_usdc": { "type": "string" }, "displacement_price_usdc": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" } } }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "display_name": { "type": "string" }, "company_name": { "type": "string" }, "role": { "type": "string", "enum": ["user", "moderator", "admin", "superadmin"] }, "status": { "type": "string", "enum": ["active", "suspended"] }, "created_at": { "type": "string", "format": "date-time" }, "last_login_at": { "type": "string", "format": "date-time" } } }, "PaymentRequirement": { "type": "object", "properties": { "x402_version": { "type": "integer" }, "scheme": { "type": "string" }, "network": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "recipient": { "type": "string" }, "resource": { "type": "string" }, "description": { "type": "string" }, "facilitator_url": { "type": "string", "format": "uri" }, "extra": { "type": "object" } } } }, "responses": { "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token from /api/v1/auth/login" }, "agentAuth": { "type": "http", "scheme": "bearer", "description": "Agent API key (ar_live_...) from /api/v1/agent/check-in" } } } }