{"openapi":"3.1.0","info":{"title":"Avocado AI agent surface (MCP server and CLI)","version":"1.0.0","summary":"HTTP endpoints behind the Avocado MCP server and CLI: MCP, OAuth discovery, API keys and generation. Not a public developer API.","description":"Avocado AI is an AI creative workspace for ecommerce and DTC brands. One creative system, three ways to work: Studio (you make it), Flows (you repeat it) and Super Agent (Avo does it for you). Brand DNA carries your products, references, visual direction, tone and rules into every result.\n\nThis is not a developer API product. Avocado AI does not sell a public REST API. The HTTP endpoints in this document exist to serve the Avocado MCP server and the Avocado CLI. To use Avocado from an agent, connect the MCP server at https://www.avocadoai.co/mcp or install the CLI (npm package @avocado-ai-co/cli). The generation routes are listed for transparency and have no stable request schema.\n\n## What Avocado AI includes\n\n- Studio: an image workbench (generate, or edit your own product photo, up to 4 variations per run, upscale), a video workbench (text to video, animate a still, start and end frames, reference and motion-control modes), a UGC studio (creator looks, script to talking video, the product in the creator's hand, up to 30s) and an Audio Studio (text to speech, voice design, voice cloning, music, sound effects). One credit balance, one library.\n- Flows: an infinite canvas that chains prompt, LLM, image, video, music and voice nodes and runs them in one click, with Director mode for cutting a commercial. On every paid plan.\n- Super Agent 2.0: an AI marketing teammate that creates on-brand images, videos, music and captions, with Memory, Projects, Skills and a content calendar. After your approval it publishes and schedules posts to Instagram, Facebook, TikTok, LinkedIn, Threads and X (X includes 50 posts per month). It also runs Meta Ads: campaigns are always created paused and every launch needs your approval. Talk to it in the web app, Slack or Telegram. Super Agent is on Growth and Pro; publishing and Meta Ads also need the Connectors add-on (called Operator in the app).\n- Avocado MCP server: 60+ tools for Claude, Codex, Cursor or your own agent, covering image, video, UGC, speech, music, sound effects, Flows, Brand DNA, publishing, content calendar and Meta Ads.\n- Avocado CLI: generate images and videos, list models, track jobs, and install the MCP server into Claude Code or Cursor.\n\n## Current models (examples)\n\n- Image: GPT Image 2.5 Flare (default), GPT Image 2.5 Sunburst, GPT Image 2, Nano Banana 2, Seedream 5.0 Pro, Krea v2, Krea v3, Recraft v4.1, Luma Uni-1 Max, Grok Imagine.\n- Video: Seedance 2.5 and Seedance 2.0 (including Faces variants that accept real human faces), Kling 3.0 and Kling o3 4K, MiniMax H3, H3 MAX and H3 MAX Turbo, Google Veo 3.1, Gemini Omni Flash, Grok Imagine Video.\n- Audio: Fish Audio S2 Pro (default voice), ElevenLabs, Seed Audio, MiniMax Music 3, ElevenLabs Music, sound effects.\n\n## Plans (EUR per month, yearly billing is 20% off)\n\n- Intro: EUR 19.99, 100 credits\n- Starter: EUR 39, 300 credits\n- Growth: EUR 99, 800 credits, adds Super Agent\n- Pro: EUR 249, 2,000 credits\n\nEvery plan includes commercial rights and no watermarks, and credits roll over for up to one year. Details: https://www.avocadoai.co/pricing\n\n## Links\n\n- Pricing: https://www.avocadoai.co/pricing\n- Knowledge base: https://www.avocadoai.co/knowledge-base\n- MCP server: https://www.avocadoai.co/mcp\n- Agent index: https://www.avocadoai.co/llms.txt\n- Sitemap: https://www.avocadoai.co/sitemap.xml\n\n## Authentication\n\n- /api/mcp: Authorization: Bearer with an OAuth 2.1 access token (PKCE S256, dynamic client registration; discover the authorization server via /.well-known/oauth-protected-resource, metadata mirrored at /.well-known/oauth-authorization-server and /.well-known/openid-configuration) or an Avocado API key (avk_). Unauthenticated calls get 401 with WWW-Authenticate so MCP clients can start OAuth.\n- /api/mcp/public, /api/mcp/resources, /.well-known/*: no auth.\n- /api/mcp/keys: signed-in browser session. Keys are shown once.\n- Generation routes: avk_ API key or signed-in browser session.\n\n## Technical notes\n\n- /api/v1/<route> is a path alias that rewrites to /api/<route>. Responses carry API-Version: 1 and RateLimit headers; 429 responses carry Retry-After.\n- These routes change together with the MCP server and CLI. There is no separate versioning program and no Deprecation or Sunset schedule.","contact":{"url":"https://www.avocadoai.co"}},"servers":[{"url":"https://www.avocadoai.co","description":"Site root. Paths without their own servers entry resolve here."},{"url":"https://www.avocadoai.co/api/v1","description":"Path alias used by the /generate-* paths"}],"tags":[{"name":"Discovery","description":"Machine-readable indexes of the site"},{"name":"MCP","description":"Avocado MCP server (Streamable HTTP, JSON-RPC)"},{"name":"Auth","description":"OAuth discovery and Avocado API keys (avk_) for the MCP server and CLI"},{"name":"Generation","description":"Routes the web app, MCP server and CLI use to start generations. Not a stable public API; prefer the MCP tools."}],"paths":{"/api":{"get":{"tags":["Discovery"],"summary":"Get the API index","description":"JSON index of the agent-facing HTTP surface: OpenAPI, MCP endpoints, OAuth discovery documents, versioning and rate-limit conventions. Carries a Link: rel=\"api-catalog\" header.","operationId":"getApiIndex","responses":{"200":{"description":"API index","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/api-catalog":{"get":{"tags":["Discovery"],"summary":"Get the API catalog (RFC 9727 linkset)","operationId":"getApiCatalog","responses":{"200":{"description":"RFC 9264 linkset of API entry points with service-desc, service-doc, service-meta and status links","content":{"application/linkset+json":{"schema":{"type":"object"}}}}}}},"/openapi.json":{"get":{"tags":["Discovery"],"summary":"Get 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":"Get the 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":"Get the XML sitemap index","operationId":"getSitemap","responses":{"200":{"description":"Sitemap XML","content":{"application/xml":{"schema":{"type":"string"}}}}}}},"/api/mcp":{"post":{"tags":["MCP"],"summary":"Call the authenticated MCP server (JSON-RPC)","description":"Stateless Streamable HTTP Model Context Protocol endpoint used by Claude, Codex, Cursor, the Avocado CLI and custom agents. Requires Authorization: Bearer with an OAuth access token or an avk_ API key. Unauthenticated requests return 401 with WWW-Authenticate so OAuth clients can connect. After initialize, call tools/list and tools/call. Generation, publishing and Meta Ads tools spend credits or act on connected accounts only with the user's plan and approvals.","operationId":"postMcp","security":[{"bearerAuth":[]},{"oauth2":["openid","profile","email"]}],"responses":{"200":{"description":"MCP JSON-RPC response 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"}}}},"503":{"description":"Authentication could not be checked right now. Retry."}}},"get":{"tags":["MCP"],"summary":"Probe the authenticated MCP server","description":"Returns 401 with WWW-Authenticate without a valid token, and 405 with a valid one: this stateless server only accepts JSON-RPC over POST.","operationId":"getMcp","security":[{"bearerAuth":[]},{"oauth2":["openid","profile","email"]}],"responses":{"401":{"description":"Missing or invalid token"},"405":{"description":"Use POST"}}}},"/mcp":{"post":{"tags":["MCP"],"summary":"Call the MCP server at its public URL","description":"Alias of /api/mcp. MCP protocol requests to /mcp are forwarded to the authenticated server, so the same Bearer rules and 401 OAuth challenge apply. For unauthenticated discovery use /api/mcp/public.","operationId":"postPublicMcp","security":[{"bearerAuth":[]},{"oauth2":["openid","profile","email"]}],"responses":{"200":{"description":"MCP JSON-RPC response or SSE stream"},"401":{"description":"Missing or invalid token"}}},"get":{"tags":["MCP"],"summary":"Get the MCP landing page (HTML) or forward an MCP request","description":"Browsers get the MCP landing page. Requests with MCP headers or Accept: application/json are forwarded to /api/mcp. The server manifest lives at /.well-known/mcp.json.","operationId":"getMcpManifest","responses":{"200":{"description":"HTML landing page"},"401":{"description":"Forwarded MCP request without a valid token"}}}},"/api/mcp/public":{"get":{"tags":["MCP"],"summary":"Get the public MCP server manifest (no auth)","operationId":"getPublicMcpManifest","responses":{"200":{"description":"JSON server manifest plus public resource list","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["MCP"],"summary":"Call the public discovery MCP server (no auth)","description":"Stateless MCP server for unauthenticated discovery: initialize, resources/list, resources/read and discovery tools. It cannot generate or publish; use /api/mcp with a token for that.","operationId":"postPublicMcpDiscovery","responses":{"200":{"description":"MCP JSON-RPC response"}}}},"/.well-known/mcp.json":{"get":{"tags":["MCP"],"summary":"Get the MCP server card","operationId":"getWellKnownMcp","responses":{"200":{"description":"JSON MCP server card (Streamable HTTP) with public resources","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/resources":{"get":{"tags":["MCP"],"summary":"List public MCP resources (no auth)","operationId":"listMcpResources","responses":{"200":{"description":"Resource descriptors agents can fetch over HTTP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResourceList"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"tags":["Auth"],"summary":"Get OAuth protected-resource metadata (RFC 9728)","description":"Tells MCP clients which authorization server issues tokens for the Avocado MCP server.","operationId":"getOAuthProtectedResource","responses":{"200":{"description":"Protected-resource metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"tags":["Auth"],"summary":"Get OAuth authorization-server metadata (RFC 8414)","description":"Proxied copy of the authorization server's metadata, for MCP clients that look for it on the resource server.","operationId":"getOAuthAuthorizationServer","responses":{"200":{"description":"Authorization-server metadata","content":{"application/json":{"schema":{"type":"object"}}}},"502":{"description":"Upstream metadata unavailable"}}}},"/.well-known/openid-configuration":{"get":{"tags":["Auth"],"summary":"Get OpenID Connect discovery metadata","description":"Proxied copy of the authorization server's OpenID Connect Discovery 1.0 document (RFC 8414 members plus userinfo_endpoint, claims_supported and id_token signing algorithms).","operationId":"getOpenIdConfiguration","responses":{"200":{"description":"OpenID Provider metadata","content":{"application/json":{"schema":{"type":"object"}}}},"502":{"description":"Upstream metadata unavailable"}}}},"/.well-known/oauth-protected-resource/api/mcp":{"get":{"tags":["Auth"],"summary":"Get OAuth protected-resource metadata for the MCP path (RFC 9728 section 3.1)","description":"Same document as /.well-known/oauth-protected-resource, at the path-suffixed URL derived from the resource identifier.","operationId":"getOAuthProtectedResourceForMcp","responses":{"200":{"description":"Protected-resource metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp/keys":{"get":{"tags":["Auth"],"summary":"List your Avocado API keys","description":"Requires a signed-in browser session. Returns key metadata, never the secret.","operationId":"listApiKeys","security":[{"clerkSession":[]}],"responses":{"200":{"description":"Key list","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Not signed in"}}},"post":{"tags":["Auth"],"summary":"Create an Avocado API key (avk_) for the MCP server or CLI","description":"Requires a signed-in browser session. The full key is returned once. Up to 5 active keys per user. Body: { name?, scope?: \"current\" | \"personal\" }.","operationId":"createApiKey","security":[{"clerkSession":[]}],"responses":{"200":{"description":"New key (shown once)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid name or scope, or 5 active keys already"},"401":{"description":"Not signed in"}}},"delete":{"tags":["Auth"],"summary":"Revoke an Avocado API key","description":"Pass ?id=<keyId>. Works with a signed-in session, or with the same avk_ key as Bearer to revoke itself.","operationId":"revokeApiKey","security":[{"clerkSession":[]},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"},"400":{"description":"Missing key id"},"401":{"description":"Unauthorized"},"404":{"description":"Key not found"}}}},"/generate-image":{"servers":[{"url":"https://www.avocadoai.co/api/v1","description":"Path alias that rewrites /api/v1/<route> to /api/<route>"}],"post":{"tags":["Generation"],"summary":"Start an image generation or edit (via the /api/v1 alias)","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":{"servers":[{"url":"https://www.avocadoai.co/api/v1","description":"Path alias that rewrites /api/v1/<route> to /api/<route>"}],"post":{"tags":["Generation"],"summary":"Start a video generation (via the /api/v1 alias)","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":{"servers":[{"url":"https://www.avocadoai.co/api/v1","description":"Path alias that rewrites /api/v1/<route> to /api/<route>"}],"post":{"tags":["Generation"],"summary":"Start a music generation (via the /api/v1 alias)","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":"Start an image generation or edit","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":"Start a video generation","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":"Start a music generation","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":"Optional. The only value is 1, matching the API-Version: 1 response header. The /api/v1/ path alias wins 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."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization code with PKCE (S256). Public clients register dynamically at the registration_endpoint published in /.well-known/oauth-authorization-server. Refresh tokens need the offline_access scope.","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.avocadoai.co/oauth/authorize","tokenUrl":"https://clerk.avocadoai.co/oauth/token","refreshUrl":"https://clerk.avocadoai.co/oauth/token","scopes":{"openid":"OpenID Connect identity","profile":"Name and avatar","email":"Email address","offline_access":"Refresh tokens"}}}},"clerkSession":{"type":"apiKey","in":"cookie","name":"__session","description":"Signed-in browser 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":"Knowledge base (setup guides for the MCP server and CLI, plans, policies)","url":"https://www.avocadoai.co/knowledge-base"}}