{"openapi":"3.1.0","info":{"title":"Avocado AI API","version":"1.0.0","summary":"Generate images, video, music, and speech; connect via MCP.","description":"Avocado AI is an ecommerce creative platform (Super Agent, Flows, MCP). Authenticated generation routes accept a Clerk session cookie or an Avocado API key (avk_). Machine-readable indexes: /llms.txt, /openapi.json, /sitemap.xml.\n\nAvocado AI versions the public HTTP API in the URL path.\n\n- Current version: v1, served at https://www.avocadoai.co/api/v1/*\n- Unversioned /api/* generation routes are aliases of /api/v1/* and remain supported for v1.\n- Clients may also send API-Version: 1. The URL path is the source of truth when both are present.\n- Breaking changes ship as /api/v2/. Deprecated versions receive Deprecation: true and a Sunset HTTP-date for at least 180 days before removal.\n- Rate-limit conventions: RateLimit (RFC 9331), RateLimit-Limit / Remaining / Reset, and Retry-After on HTTP 429.\n\n\nDeprecated API versions are announced with Deprecation: true and Sunset (HTTP-date) for a minimum of 180 days.","contact":{"url":"https://www.avocadoai.co"}},"servers":[{"url":"https://www.avocadoai.co/api/v1","description":"API v1 (path versioning)"},{"url":"https://www.avocadoai.co","description":"Site root; /api/* is a v1 alias"}],"tags":[{"name":"Discovery"},{"name":"MCP"},{"name":"Generation"}],"paths":{"/openapi.json":{"get":{"tags":["Discovery"],"summary":"This OpenAPI document","operationId":"getOpenApi","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/llms.txt":{"get":{"tags":["Discovery"],"summary":"Agent-oriented site index","operationId":"getLlmsTxt","responses":{"200":{"description":"Markdown index of public pages","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"tags":["Discovery"],"summary":"XML sitemap index","operationId":"getSitemap","responses":{"200":{"description":"Sitemap XML","content":{"application/xml":{"schema":{"type":"string"}}}}}}},"/api/mcp":{"post":{"tags":["MCP"],"summary":"Authenticated Streamable HTTP MCP server","description":"JSON-RPC Model Context Protocol endpoint. Unauthenticated requests return 401 with WWW-Authenticate so OAuth clients can connect. After connect, call resources/list and tools/list.","operationId":"postMcp","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"MCP JSON-RPC or SSE stream"},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mcp":{"post":{"tags":["MCP"],"summary":"Public Streamable HTTP MCP server","description":"Unauthenticated initialize, resources/list, resources/read, and discovery tools. Generation tools require Authorization. GET with Accept: application/json returns the server manifest. Browsers requesting HTML still receive the marketing page.","operationId":"postPublicMcp","responses":{"200":{"description":"MCP JSON-RPC, SSE stream, or JSON manifest"}}},"get":{"tags":["MCP"],"summary":"MCP server JSON manifest (Accept: application/json) or marketing HTML","operationId":"getMcpManifest","responses":{"200":{"description":"JSON manifest or HTML landing page"}}}},"/.well-known/mcp.json":{"get":{"tags":["MCP"],"summary":"MCP server manifest","operationId":"getWellKnownMcp","responses":{"200":{"description":"JSON MCP server card (Streamable HTTP)","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/resources":{"get":{"tags":["MCP"],"summary":"Public MCP resource catalog (no auth)","operationId":"listMcpResources","responses":{"200":{"description":"Resource descriptors agents can fetch over HTTP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResourceList"}}}}}}},"/generate-image":{"post":{"tags":["Generation"],"summary":"Generate an image (API v1)","operationId":"generateImageV1","security":[{"bearerAuth":[]},{"clerkSession":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Generation accepted or completed"},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/generate-video":{"post":{"tags":["Generation"],"summary":"Generate a video (API v1)","operationId":"generateVideoV1","security":[{"bearerAuth":[]},{"clerkSession":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Generation accepted or completed"},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/generate-music":{"post":{"tags":["Generation"],"summary":"Generate music (API v1)","operationId":"generateMusicV1","security":[{"bearerAuth":[]},{"clerkSession":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Generation accepted or completed"},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/generate-image":{"post":{"tags":["Generation"],"summary":"Generate an image (v1 alias of /api/v1/generate-image)","operationId":"generateImage","security":[{"bearerAuth":[]},{"clerkSession":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Generation accepted or completed"},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/generate-video":{"post":{"tags":["Generation"],"summary":"Generate a video (v1 alias)","operationId":"generateVideo","security":[{"bearerAuth":[]},{"clerkSession":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Generation accepted or completed"},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/generate-music":{"post":{"tags":["Generation"],"summary":"Generate music (v1 alias)","operationId":"generateMusic","security":[{"bearerAuth":[]},{"clerkSession":[]}],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Generation accepted or completed"},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests. Honor Retry-After and RateLimit headers.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"},"RateLimit":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"parameters":{"ApiVersion":{"name":"API-Version","in":"header","required":false,"description":"API major version. Current value is 1. URL path /api/v1/ is authoritative when both are sent.","schema":{"type":"string","enum":["1"],"default":"1"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Avocado API key (avk_) or OAuth access token."},"clerkSession":{"type":"apiKey","in":"cookie","name":"__session","description":"Browser Clerk session cookie."}},"schemas":{"ApiError":{"type":"object","required":["error","code","message","hint","docs","status"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"docs":{"type":"string","format":"uri"},"status":{"type":"integer"}}},"McpResourceList":{"type":"object","required":["resources"],"properties":{"resources":{"type":"array","items":{"type":"object","required":["uri","name","mimeType"],"properties":{"uri":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}}}}}}},"externalDocs":{"description":"Human docs, llms.txt, sitemap, versioning policy","url":"https://www.avocadoai.co/docs"}}