{"openapi":"3.1.0","info":{"title":"Build with AK API & MCP Service","version":"1.0.0","description":"Official API and Model Context Protocol (MCP) server for authoring, validating, and submitting product showcases to the Build with AK Customer Directory on agentkit.best.","contact":{"name":"AgentKit Support","url":"https://agentkit.best","email":"support@agentkit.best"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://bwak.agentkit.best","description":"Production Cloudflare Worker Edge Server"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["build-with-ak:read"]}],"paths":{"/api/build-with-ak/listing/analytics":{"get":{"summary":"Get owned product page analytics","operationId":"getListingAnalytics","servers":[{"url":"https://agentkit.best"},{"url":"https://staging.agentkit.best"}],"security":[{"ApiKeyAuth":[]}],"description":"Owner-only analytics from first-party PostgreSQL. Optional listingId selects any owned historical listing; omitted selects the active non-rejected/non-archived listing. Inclusive UTC dates default to today and 29 days earlier. Maximum 366 days; to cannot be in the future. Unknown or duplicate parameters, invalid dates, and invalid ranges return 400. Authenticated browser sessions are also accepted by the upstream API. The MCP Worker exposes this through build_with_ak_get_analytics, not a REST proxy.","parameters":[{"name":"listingId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Owned listing UUID; omitted selects the active listing."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive UTC start, YYYY-MM-DD. Defaults to to minus 29 days."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive UTC end, YYYY-MM-DD. Defaults to today; no future dates."}],"responses":{"200":{"description":"Owned listing analytics with ascending, zero-filled daily counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingAnalytics"}}}},"400":{"description":"Invalid, unknown, or duplicate query parameter or invalid date range."},"401":{"description":"Authentication required or invalid API key."},"403":{"description":"Credential is not permitted to access this API."},"404":{"description":"No owned listing found; includes unknown or cross-owner listing IDs."},"429":{"description":"Rate limit exceeded."},"500":{"description":"Analytics retrieval failed."}}}},"/.well-known/oauth-protected-resource/mcp":{"$ref":"#/paths/~1.well-known~1oauth-protected-resource"},"/":{"get":{"summary":"Service Index & Discovery","description":"Returns service capability index, endpoint URLs, and documentation links.","operationId":"getServiceIndex","security":[],"responses":{"200":{"description":"Service index metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceIndex"}}}}}}},"/health":{"get":{"summary":"Health Check","description":"Returns status ok and current timestamp.","operationId":"getHealth","security":[],"responses":{"200":{"description":"Service health status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","format":"date-time"}},"required":["status","timestamp"]}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"summary":"OAuth 2.1 Protected Resource Metadata (RFC 9728)","description":"Exposes resource URI, authorization servers, and supported scopes for OAuth discovery.","operationId":"getOAuthProtectedResourceMetadata","security":[],"responses":{"200":{"description":"RFC 9728 Metadata Document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtectedResourceMetadata"}}}}}}},"/.well-known/ai-plugin.json":{"get":{"summary":"AI Plugin Manifest","description":"OpenAI AI Plugin discovery manifest for ChatGPT and Custom GPT Actions.","operationId":"getAiPluginManifest","security":[],"responses":{"200":{"description":"AI Plugin manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiPluginManifest"}}}}}}},"/openapi.json":{"get":{"summary":"OpenAPI 3.1.0 Specification","description":"Returns this OpenAPI schema definition.","operationId":"getOpenApiSpec","security":[],"responses":{"200":{"description":"OpenAPI schema","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/mcp":{"post":{"summary":"Streamable HTTP MCP Endpoint","description":"Executes Model Context Protocol (MCP) JSON-RPC 2.0 commands over Streamable HTTP.","operationId":"executeMcp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"method":{"type":"string","example":"tools/call"},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"Streamed MCP response or JSON-RPC result","content":{"text/event-stream":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"result":{"type":"object"},"error":{"type":"object"}}}}}},"401":{"description":"Unauthorized — Missing or invalid API key or Bearer token with WWW-Authenticate challenge"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"AgentKit customer API key (ck_live_...)"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 Authorization Code Flow with PKCE (S256)","flows":{"authorizationCode":{"authorizationUrl":"https://agentkit.best/oauth/authorize","tokenUrl":"https://agentkit.best/oauth/token","scopes":{"build-with-ak:read":"Read product showcase draft and live listing","build-with-ak:write":"Create, edit layout blocks, upload media, and submit showcase"}}}}},"schemas":{"AnalyticsMetrics":{"type":"object","required":["views","outboundClicks","referralConversions"],"properties":{"views":{"type":"integer","minimum":0,"description":"Views deduplicated per listing, IP + user agent, and UTC day; not unique people across days."},"outboundClicks":{"type":"integer","minimum":0,"description":"Outbound redirect requests, not unique visitors."},"referralConversions":{"type":"null","description":"Unavailable: conversion tracking is not instrumented. Not external product sales."}}},"ListingAnalytics":{"type":"object","required":["listing","period","source","generatedAt","totals","daily"],"properties":{"listing":{"type":"object","required":["id","slug"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"}}},"period":{"type":"object","required":["from","to","timezone"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"timezone":{"type":"string","const":"UTC"}}},"source":{"type":"string","const":"first_party_postgresql"},"generatedAt":{"type":"string","format":"date-time"},"totals":{"$ref":"#/components/schemas/AnalyticsMetrics"},"daily":{"type":"array","minItems":1,"maxItems":366,"description":"Ascending UTC dates, including zero-count view/click days. Referral conversions are null on every day because tracking is unavailable.","items":{"allOf":[{"$ref":"#/components/schemas/AnalyticsMetrics"},{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date"}}}]}}}},"ServiceIndex":{"type":"object","properties":{"service":{"type":"string","example":"Build with AK MCP Server"},"version":{"type":"string","example":"1.0.0"},"documentation":{"type":"string","format":"uri"},"endpoints":{"type":"object","properties":{"mcp":{"type":"string"},"oauth_metadata":{"type":"string"},"ai_plugin":{"type":"string"},"openapi":{"type":"string"}}}},"required":["service","version","endpoints"]},"ProtectedResourceMetadata":{"type":"object","properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}}},"required":["resource","authorization_servers","scopes_supported","bearer_methods_supported"]},"AiPluginManifest":{"type":"object","properties":{"schema_version":{"type":"string","example":"v1"},"name_for_human":{"type":"string","example":"Build with AK"},"name_for_model":{"type":"string","example":"build_with_ak"},"description_for_human":{"type":"string"},"description_for_model":{"type":"string"},"auth":{"type":"object"},"api":{"type":"object"},"logo_url":{"type":"string","format":"uri"},"contact_email":{"type":"string","format":"email"},"legal_info_url":{"type":"string","format":"uri"}},"required":["schema_version","name_for_human","name_for_model","description_for_human","description_for_model","auth","api","logo_url","contact_email","legal_info_url"]}}}}