{"openapi": "3.1.0", "info": {"title": "Product Debuts API", "version": "1.0.0", "description": "The Product Debuts API: read every public listing, category, launch and leaderboard; submit your product by URL and edit the AI draft; manage your listings; build orders that end in a checkout link you pay yourself. There is no voting through the API: votes come only from people on the site. Docs: https://productdebuts.com/developers", "contact": {"name": "Product Debuts developers", "url": "https://productdebuts.com/developers", "email": "launch@zinndigital.com"}, "termsOfService": "https://productdebuts.com/developers/terms"}, "servers": [{"url": "https://productdebuts.com/api/v1"}], "tags": [{"name": "Site", "description": "Who this site is and what it offers"}, {"name": "Listings", "description": "Search and read live listings"}, {"name": "Categories", "description": "Categories and subcategories"}, {"name": "Launches", "description": "The launch calendar"}, {"name": "Leaderboards", "description": "Community votes, the paid billboard and Domain Rating boards (separate systems)"}, {"name": "People", "description": "Founders and their stories"}, {"name": "Content", "description": "Blog posts and guides"}, {"name": "Badges", "description": "Embeddable badges and awards"}, {"name": "Account", "description": "Your account (needs sign-in)"}, {"name": "Submit", "description": "Submit a product by URL and edit the AI draft (needs sign-in)"}, {"name": "My listings", "description": "Edit your live listings (needs sign-in)"}, {"name": "Claims", "description": "Claim and verify an existing listing (needs sign-in)"}, {"name": "Orders", "description": "Prices, VAT preview and secure checkout links (needs sign-in to build an order)"}, {"name": "Trophies", "description": "Trophy cabinets, awards and their verification, leaderboards, Hall of Fame, programmes to enter"}], "paths": {"/site": {"get": {"operationId": "get_site_info", "summary": "About this site and its API", "description": "Returns this site's name, what it is for, its public URLs, how many live listings and categories it has, and where the API docs, OpenAPI file and MCP server are. Call this first to orient yourself.", "tags": ["Site"], "x-mcp-tool": "get_site_info", "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/listings": {"get": {"operationId": "search_listings", "summary": "Search and filter listings", "description": "Full-text search over this site's live listings (name, tagline, description, keywords; typo tolerant) with filters. Use `q` for words, or leave it empty to browse. `category` includes its subcategories. `domain` finds the listing of a website. Results are summaries; call get_listing for the full profile.", "tags": ["Listings"], "x-mcp-tool": "search_listings", "parameters": [{"name": "q", "in": "query", "required": false, "schema": {"type": "string", "description": "Search words, e.g. 'invoice software for freelancers'", "maxLength": 200}, "description": "Search words, e.g. 'invoice software for freelancers'"}, {"name": "category", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Category slug (from list_categories)"}, "description": "Category slug (from list_categories)"}, {"name": "stage", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Business stage slug, e.g. idea, mvp, launched, growing"}, "description": "Business stage slug, e.g. idea, mvp, launched, growing"}, {"name": "country", "in": "query", "required": false, "schema": {"type": "string", "description": "ISO 3166 two-letter country code, e.g. GB", "pattern": "^[A-Za-z]{2}$"}, "description": "ISO 3166 two-letter country code, e.g. GB"}, {"name": "pricing_model", "in": "query", "required": false, "schema": {"type": "string", "description": "Pricing model, e.g. Free, Freemium, Subscription", "maxLength": 40}, "description": "Pricing model, e.g. Free, Freemium, Subscription"}, {"name": "domain", "in": "query", "required": false, "schema": {"type": "string", "description": "Website domain, e.g. example.com", "maxLength": 253}, "description": "Website domain, e.g. example.com"}, {"name": "status", "in": "query", "required": false, "schema": {"type": "string", "description": "live (published) or upcoming (scheduled for a future launch week)", "enum": ["live", "upcoming"], "default": "live"}, "description": "live (published) or upcoming (scheduled for a future launch week)"}, {"name": "sort", "in": "query", "required": false, "schema": {"type": "string", "description": "Order of results", "enum": ["relevance", "newest", "votes", "trending", "most_viewed", "most_followed"], "default": "relevance"}, "description": "Order of results"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/listings/{slug}": {"get": {"operationId": "get_listing", "summary": "Get a listing's full profile", "description": "Everything public about one listing: description, features, pricing, categories, founders, FAQs, socials, latest updates, community rating (genuine reviews only), Ahrefs Domain Rating with trend, and links. Paid-only sections (story, milestones, media) appear only when the listing has them unlocked, exactly as on the page. `not_found_on_website` lists facts the company's own site did not state (left blank on purpose).", "tags": ["Listings"], "x-mcp-tool": "get_listing", "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Listing slug (from search_listings)"}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/listings/{slug}/alternatives": {"get": {"operationId": "get_alternatives", "summary": "Alternatives to a listing", "description": "Alternatives to one listing: those the owner approved first (approved=true), then other live listings in the same primary category. Good for 'what else is like X?'.", "tags": ["Listings"], "x-mcp-tool": "get_alternatives", "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Listing slug"}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/compare": {"get": {"operationId": "compare_listings", "summary": "Compare two listings side by side", "description": "A side-by-side comparison of two live listings using their category attributes (stage, pricing, features and more). Empty cells mean the fact is not on either listing.", "tags": ["Listings"], "x-mcp-tool": "compare_listings", "parameters": [{"name": "a", "in": "query", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "First listing slug"}, "description": "First listing slug"}, {"name": "b", "in": "query", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Second listing slug"}, "description": "Second listing slug"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/categories": {"get": {"operationId": "list_categories", "summary": "List categories and subcategories", "description": "The full category tree with live listing counts per category on this site. Every listing has one primary category (and paid listings up to 3 more). Use a slug in search_listings(category=...).", "tags": ["Categories"], "x-mcp-tool": "list_categories", "parameters": [{"name": "include_empty", "in": "query", "required": false, "schema": {"type": "boolean", "description": "Include categories with no live listings yet", "default": true}, "description": "Include categories with no live listings yet"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/categories/{slug}": {"get": {"operationId": "get_category", "summary": "Get a category with its top listings", "description": "One category: description, FAQs, parent, subcategories and its live listings (most voted first).", "tags": ["Categories"], "x-mcp-tool": "get_category", "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Category slug"}}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/launches/weeks/{week}": {"get": {"operationId": "get_launch_week", "summary": "Launches in one week", "description": "The launch calendar for one week (Monday to Sunday): live launches ranked by community votes, and, for a future week, the launches scheduled for it. `week` is this, next, last or any date.", "tags": ["Launches"], "x-mcp-tool": "get_launch_week", "parameters": [{"name": "week", "in": "path", "required": true, "schema": {"type": "string", "description": "this, next, last, or a date YYYY-MM-DD (snapped to its Monday)", "maxLength": 10}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/launches": {"get": {"operationId": "list_launches", "summary": "Launch feed sections", "description": "Launch feeds: launching today, this week, trending (time-decayed votes), most voted, recently launched, most viewed, most followed, or upcoming (scheduled).", "tags": ["Launches"], "x-mcp-tool": "list_launches", "parameters": [{"name": "section", "in": "query", "required": false, "schema": {"type": "string", "description": "Which feed", "enum": ["today", "this-week", "trending", "most-voted", "recent", "most-viewed", "most-followed", "upcoming"], "default": "this-week"}, "description": "Which feed"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/leaderboards/{board}": {"get": {"operationId": "get_leaderboard", "summary": "Get a leaderboard", "description": "One of the separate ranking systems: community votes (weekly or all time), the billboard (a PAID ranking by money contributed; always present it as paid), Ahrefs Domain Rating, or revenue. Each item has its rank, the listing and the metric.", "tags": ["Leaderboards"], "x-mcp-tool": "get_leaderboard", "parameters": [{"name": "board", "in": "path", "required": true, "schema": {"type": "string", "description": "Which board", "enum": ["community-weekly", "community-all-time", "billboard", "domain-rating", "revenue"]}}, {"name": "week", "in": "query", "required": false, "schema": {"type": "string", "description": "community-weekly only: this, last or a date", "maxLength": 10}, "description": "community-weekly only: this, last or a date"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/founders": {"get": {"operationId": "list_founders", "summary": "Find founders", "description": "Founders behind this site's live listings, optionally matched by name or filtered by country.", "tags": ["People"], "x-mcp-tool": "list_founders", "parameters": [{"name": "q", "in": "query", "required": false, "schema": {"type": "string", "description": "Name to look for", "maxLength": 120}, "description": "Name to look for"}, {"name": "country", "in": "query", "required": false, "schema": {"type": "string", "description": "ISO two-letter country code", "pattern": "^[A-Za-z]{2}$"}, "description": "ISO two-letter country code"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/founders/{slug}": {"get": {"operationId": "get_founder", "summary": "Get a founder with companies and stories", "description": "A founder's public profile: bio, socials, their companies listed here and their published stories.", "tags": ["People"], "x-mcp-tool": "get_founder", "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Founder slug"}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/blog": {"get": {"operationId": "list_blog_posts", "summary": "List or search blog posts", "description": "This site's published guides and articles, newest first, or matched by `q`.", "tags": ["Content"], "x-mcp-tool": "list_blog_posts", "parameters": [{"name": "q", "in": "query", "required": false, "schema": {"type": "string", "description": "Search words", "maxLength": 200}, "description": "Search words"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/blog/{slug}": {"get": {"operationId": "get_blog_post", "summary": "Read a blog post", "description": "One published post with its full text (Markdown) and FAQs.", "tags": ["Content"], "x-mcp-tool": "get_blog_post", "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Post slug"}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/awards": {"get": {"operationId": "list_awards", "summary": "Awards won on this site", "description": "Awards given on this site (Launch of the Week #1, #2, #3), newest week first, with the winning listing. Awards follow community votes only.", "tags": ["Badges"], "x-mcp-tool": "list_awards", "parameters": [{"name": "listing", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Only awards of this listing slug"}, "description": "Only awards of this listing slug"}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/listings/{slug}/badges": {"get": {"operationId": "get_badges", "summary": "Badge embed codes for a listing", "description": "The badges a listing may show (Listed on, Launched on, Featured, Verified, Launch of the Week...) with ready-to-paste HTML embed code and SVG image URLs in every style (shape, light/dark/auto, size). Free listings go live once this badge is on their homepage.", "tags": ["Badges"], "x-mcp-tool": "get_badges", "parameters": [{"name": "slug", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,219}$", "description": "Listing slug"}}, {"name": "shape", "in": "query", "required": false, "schema": {"type": "string", "description": "Badge shape", "enum": ["standard", "outline", "pill", "banner", "square"], "default": "standard"}, "description": "Badge shape"}, {"name": "mode", "in": "query", "required": false, "schema": {"type": "string", "description": "Colour mode", "enum": ["light", "dark", "auto"], "default": "auto"}, "description": "Colour mode"}, {"name": "size", "in": "query", "required": false, "schema": {"type": "string", "description": "Size", "enum": ["s", "m", "l"], "default": "m"}, "description": "Size"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/me": {"get": {"operationId": "get_account", "summary": "Your account", "description": "Who you are signed in as on this site, and what your access allows.", "tags": ["Account"], "x-mcp-tool": "get_account", "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}}, "/drafts": {"post": {"operationId": "submit_listing", "summary": "Submit a product by its website URL", "description": "Starts a new listing from a website address. We read the site (respecting robots.txt) and an AI drafts the profile in about a minute, quoting evidence from the site for every value; anything not found there is left blank (never invented). Returns a draft with status 'crawling': poll get_draft every few seconds until status is 'ready', then review and edit it, then call submit_draft. Nothing is published and nothing is charged by this call.", "tags": ["Submit"], "x-mcp-tool": "submit_listing", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "description": "The product's public website, e.g. https://example.com", "maxLength": 2048}}, "required": ["url"], "additionalProperties": false}}}}, "responses": {"201": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"], "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}]}, "get": {"operationId": "list_my_drafts", "summary": "Your drafts on this site", "description": "Drafts you started on this site, newest first, with status and completeness.", "tags": ["Submit"], "x-mcp-tool": "list_my_drafts", "parameters": [{"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}}, "/drafts/{id}": {"get": {"operationId": "get_draft", "summary": "Get a draft (poll while it builds)", "description": "A draft with every profile field: value, state (ai / not_found / edited / manual / override / deleted) and the evidence quotes from the website, plus FAQs, founders, socials, story, milestones, completeness and what is still missing. While status is crawling or drafting, poll again.", "tags": ["Submit"], "x-mcp-tool": "get_draft", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid", "description": "Draft id (from submit_listing)"}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}, "patch": {"operationId": "update_draft", "summary": "Edit a draft", "description": "Edit any part of a draft in one call: profile fields (null removes one), lock fields against AI redrafts, ask the AI to redraft fields from the website evidence, restore the AI value, replace FAQs, socials, founders, story sections, milestones, set the main competitor and SEO text. Only send what you change. Returns the updated draft. If the draft was already submitted, the listing is updated too (call submit_draft again is not needed).", "tags": ["Submit"], "x-mcp-tool": "update_draft", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid", "description": "Draft id (from submit_listing)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"fields": {"type": "object", "properties": {"name": {"type": ["string", "null"], "maxLength": 500, "description": "Company name"}, "tagline": {"type": ["string", "null"], "maxLength": 500, "description": "Tagline"}, "short_description": {"type": ["string", "null"], "maxLength": 500, "description": "Short description"}, "description": {"type": ["string", "null"], "maxLength": 20000, "description": "Description"}, "stage": {"type": ["string", "null"], "maxLength": 500, "description": "Business stage"}, "categories": {"type": ["array", "null"], "items": {"type": "string", "maxLength": 200}, "maxItems": 20, "description": "Categories"}, "tags": {"type": ["array", "null"], "items": {"type": "string", "maxLength": 200}, "maxItems": 20, "description": "Tags"}, "pricing_model": {"type": ["string", "null"], "maxLength": 500, "description": "Pricing model"}, "pricing_summary": {"type": ["string", "null"], "maxLength": 500, "description": "Pricing"}, "country": {"type": ["string", "null"], "maxLength": 500, "description": "Country (ISO code)"}, "city": {"type": ["string", "null"], "maxLength": 500, "description": "City"}, "founded_year": {"type": ["string", "null"], "maxLength": 500, "description": "Founded (year)"}, "features": {"type": ["array", "null"], "items": {"type": "string", "maxLength": 200}, "maxItems": 20, "description": "Features"}, "usps": {"type": ["array", "null"], "items": {"type": "string", "maxLength": 200}, "maxItems": 20, "description": "What makes it different"}, "keywords": {"type": ["array", "null"], "items": {"type": "string", "maxLength": 200}, "maxItems": 20, "description": "Keywords"}, "contact_email": {"type": ["string", "null"], "maxLength": 500, "description": "Contact email"}, "demo_video_url": {"type": ["string", "null"], "maxLength": 500, "description": "Demo video (YouTube)"}, "logo_url": {"type": ["string", "null"], "maxLength": 500, "description": "Logo"}}, "additionalProperties": false, "description": "Set profile fields. A value you type is marked as yours (edited/manual); null removes the field. Categories: names from list_categories (first = primary)."}, "lock_fields": {"type": "array", "description": "Field names to lock against AI redrafts (override)", "items": {"type": "string"}, "maxItems": 20}, "regenerate": {"type": "array", "description": "Field names for the AI to redraft from the website (uses evidence; may take a few seconds)", "items": {"type": "string"}, "maxItems": 5}, "restore": {"type": "array", "description": "Field names to put back to the AI's original value", "items": {"type": "string"}, "maxItems": 20}, "faqs": {"type": "array", "description": "Replace all FAQs (max 5)", "items": {"type": "object", "properties": {"question": {"type": "string", "description": "Question", "maxLength": 300}, "answer": {"type": "string", "description": "Answer", "maxLength": 1500}}, "required": ["question", "answer"], "additionalProperties": false}, "maxItems": 10}, "company_socials": {"type": "object", "description": "Links by platform: linkedin, x, facebook, instagram, tiktok, youtube, threads, pinterest, github, reddit, producthunt, medium, website, custom", "additionalProperties": {"type": "string", "maxLength": 500}}, "founder_socials": {"type": "object", "description": "Links by platform: linkedin, x, facebook, instagram, tiktok, youtube, threads, pinterest, github, reddit, producthunt, medium, website, custom", "additionalProperties": {"type": "string", "maxLength": 500}}, "founders": {"type": "array", "description": "Replace the founders list (first = primary founder)", "items": {"type": "object", "properties": {"name": {"type": "string", "description": "Name", "maxLength": 160}, "title": {"type": "string", "description": "Role", "maxLength": 160}, "bio": {"type": "string", "description": "Short bio", "maxLength": 3000}}, "required": ["name"], "additionalProperties": false}, "maxItems": 6}, "story": {"type": "object", "description": "Founder story sections (each up to 8000 characters): title, story, why_started, problem, journey, challenges, achievements, lessons, whats_next", "properties": {"title": {"type": "string", "maxLength": 8000}, "story": {"type": "string", "maxLength": 8000}, "why_started": {"type": "string", "maxLength": 8000}, "problem": {"type": "string", "maxLength": 8000}, "journey": {"type": "string", "maxLength": 8000}, "challenges": {"type": "string", "maxLength": 8000}, "achievements": {"type": "string", "maxLength": 8000}, "lessons": {"type": "string", "maxLength": 8000}, "whats_next": {"type": "string", "maxLength": 8000}}, "additionalProperties": false}, "milestones": {"type": "array", "description": "Replace milestones", "items": {"type": "object", "properties": {"date": {"type": "string", "description": "YYYY-MM-DD", "format": "date"}, "title": {"type": "string", "description": "Title", "maxLength": 200}, "description": {"type": "string", "description": "Details", "maxLength": 2000}, "url": {"type": "string", "description": "Link (https://...)", "maxLength": 500}}, "required": ["date", "title"], "additionalProperties": false}, "maxItems": 50}, "competitor_url": {"type": "string", "description": "Main competitor's website (we read it and compare); empty to clear", "maxLength": 2048}, "seo": {"type": "object", "properties": {"title": {"type": "string", "description": "SEO title (max 70)", "maxLength": 70}, "meta": {"type": "string", "description": "Meta description (max 170)", "maxLength": 170}}, "required": [], "additionalProperties": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/drafts/{id}/invites": {"post": {"operationId": "invite_cofounder", "summary": "Invite a co-founder", "description": "Emails a co-founder an invite to add their own profile to this listing (up to 10 invites).", "tags": ["Submit"], "x-mcp-tool": "invite_cofounder", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid", "description": "Draft id (from submit_listing)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "description": "Co-founder's email", "format": "email", "maxLength": 254}}, "required": ["email"], "additionalProperties": false}}}}, "responses": {"201": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/drafts/{id}/submit": {"post": {"operationId": "submit_draft", "summary": "Turn a ready draft into your listing", "description": "Saves the draft as your listing on this site (not published yet). Then publish it: either choose_free_listing (free, goes live in a future week once our badge is on your homepage) or create_checkout with the 'launch' product (paid: live at once or in the week you pick, plus extras). Re-running after edits updates the same listing.", "tags": ["Submit"], "x-mcp-tool": "submit_draft", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid", "description": "Draft id (from submit_listing)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/me/listings": {"get": {"operationId": "list_my_listings", "summary": "Your listings on this site", "description": "Every listing you own on this site (any status: draft, awaiting_badge, scheduled, live...).", "tags": ["My listings"], "x-mcp-tool": "list_my_listings", "parameters": [{"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}}, "/me/listings/{listing_id}": {"get": {"operationId": "get_my_listing", "summary": "One of your listings", "description": "Your listing with its status, plan, launch week, unlocked paid sections and everything public.", "tags": ["My listings"], "x-mcp-tool": "get_my_listing", "parameters": [{"name": "listing_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1, "description": "Your listing id (from list_my_listings or submit_draft)"}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}, "patch": {"operationId": "update_my_listing", "summary": "Edit your listing", "description": "Change your listing's facts and wording. Edits publish at once, are kept in the version history and the site team sees a before/after copy. Listings you submitted through a draft can also be edited with update_draft (it keeps the website evidence).", "tags": ["My listings"], "x-mcp-tool": "update_my_listing", "parameters": [{"name": "listing_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1, "description": "Your listing id (from list_my_listings or submit_draft)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"fields": {"type": "object", "properties": {"tagline": {"type": "string", "maxLength": 200}, "short_description": {"type": "string", "maxLength": 300}, "description": {"type": "string", "maxLength": 20000}, "pricing_model": {"type": "string", "maxLength": 40}, "pricing_summary": {"type": "string", "maxLength": 300}, "country": {"type": "string", "maxLength": 2}, "city": {"type": "string", "maxLength": 120}, "founded_year": {"type": ["integer", "null"], "minimum": 1800, "maximum": 2100}, "demo_video_url": {"type": "string", "maxLength": 500}, "contact_email": {"type": "string", "maxLength": 254}, "features": {"type": "array", "items": {"type": "string", "maxLength": 200}, "maxItems": 20}, "usps": {"type": "array", "items": {"type": "string", "maxLength": 200}, "maxItems": 20}, "keywords": {"type": "array", "items": {"type": "string", "maxLength": 200}, "maxItems": 20}, "headline": {"type": "string", "maxLength": 200}, "summary": {"type": "string", "maxLength": 20000}, "seo_title": {"type": "string", "maxLength": 200}, "seo_description": {"type": "string", "maxLength": 320}}, "additionalProperties": false, "description": "Fields to change (company facts + this site's headline/summary/SEO)"}, "socials": {"type": "object", "additionalProperties": {"type": "string", "maxLength": 500}, "description": "Company links by platform (replaces all)"}, "faqs": {"type": "array", "description": "Replace all FAQs", "items": {"type": "object", "properties": {"question": {"type": "string", "description": "Question", "maxLength": 300}, "answer": {"type": "string", "description": "Answer", "maxLength": 1500}}, "required": ["question", "answer"], "additionalProperties": false}, "maxItems": 10}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/me/listings/{listing_id}/updates": {"post": {"operationId": "post_listing_update", "summary": "Post a 'what's new' update", "description": "Publishes a short update on your listing (feeds the site's latest-updates page; followers are told).", "tags": ["My listings"], "x-mcp-tool": "post_listing_update", "parameters": [{"name": "listing_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1, "description": "Your listing id (from list_my_listings or submit_draft)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "description": "Headline", "maxLength": 200}, "body": {"type": "string", "description": "The update (plain text)", "maxLength": 5000}}, "required": ["title", "body"], "additionalProperties": false}}}}, "responses": {"201": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/me/listings/{listing_id}/milestones": {"post": {"operationId": "add_milestone", "summary": "Add a milestone", "description": "Adds a dated milestone (first customer, funding, launch...) to your listing. Milestones show publicly on paid listings (or when the section is unlocked).", "tags": ["My listings"], "x-mcp-tool": "add_milestone", "parameters": [{"name": "listing_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1, "description": "Your listing id (from list_my_listings or submit_draft)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"date": {"type": "string", "description": "YYYY-MM-DD", "format": "date"}, "title": {"type": "string", "description": "Title", "maxLength": 200}, "description": {"type": "string", "description": "Details", "maxLength": 2000}, "url": {"type": "string", "description": "Link https://...", "maxLength": 500}}, "required": ["date", "title"], "additionalProperties": false}}}}, "responses": {"201": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/me/listings/{listing_id}/milestones/{milestone_id}": {"delete": {"operationId": "delete_milestone", "summary": "Delete a milestone", "description": "Removes one milestone from your listing.", "tags": ["My listings"], "x-mcp-tool": "delete_milestone", "parameters": [{"name": "listing_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1, "description": "Your listing id (from list_my_listings or submit_draft)"}}, {"name": "milestone_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "Milestone id", "minimum": 1}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/me/listings/{listing_id}/story": {"put": {"operationId": "set_founder_story", "summary": "Write or update your founder story", "description": "Saves your founder story on this site (sections: story, why_started, problem, journey, challenges, achievements, lessons, whats_next). Your own words only; it is published with your listing.", "tags": ["My listings"], "x-mcp-tool": "set_founder_story", "parameters": [{"name": "listing_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1, "description": "Your listing id (from list_my_listings or submit_draft)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "description": "Story title", "maxLength": 200}, "story": {"type": "string", "description": "story", "maxLength": 8000}, "why_started": {"type": "string", "description": "why started", "maxLength": 8000}, "problem": {"type": "string", "description": "problem", "maxLength": 8000}, "journey": {"type": "string", "description": "journey", "maxLength": 8000}, "challenges": {"type": "string", "description": "challenges", "maxLength": 8000}, "achievements": {"type": "string", "description": "achievements", "maxLength": 8000}, "lessons": {"type": "string", "description": "lessons", "maxLength": 8000}, "whats_next": {"type": "string", "description": "whats next", "maxLength": 8000}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/interview-questions": {"get": {"operationId": "list_interview_questions", "summary": "Founder interview questions", "description": "The interview questions founders can answer on their profile (answer with answer_interview).", "tags": ["My listings"], "x-mcp-tool": "list_interview_questions", "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}, "/me/interview": {"put": {"operationId": "answer_interview", "summary": "Answer founder interview questions", "description": "Saves your answers (your own words) to interview questions on your founder profile.", "tags": ["My listings"], "x-mcp-tool": "answer_interview", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"answers": {"type": "array", "description": "Answers", "items": {"type": "object", "properties": {"question_id": {"type": "integer", "description": "Question id", "minimum": 1}, "answer": {"type": "string", "description": "Your answer", "maxLength": 4000}}, "required": ["question_id", "answer"], "additionalProperties": false}, "maxItems": 30}}, "required": ["answers"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"], "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}]}}, "/me/listings/{listing_id}/free": {"post": {"operationId": "choose_free_listing", "summary": "Publish as a free listing", "description": "Chooses the free plan for a submitted listing: it is queued for a launch week 6-8 weeks out (site setting) and goes live once our badge is found on your homepage (get_badges gives the code). Paid plans go live faster: see list_products and create_checkout.", "tags": ["My listings"], "x-mcp-tool": "choose_free_listing", "parameters": [{"name": "listing_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1, "description": "Your listing id (from list_my_listings or submit_draft)"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/claims": {"post": {"operationId": "claim_listing", "summary": "Claim an existing listing", "description": "Starts claiming a listing of YOUR company (for example one we added for you). Methods: dns (TXT record), meta (tag on your homepage), file (upload a file), email (link sent to an address at your domain). Returns what to publish; then call verify_claim. Verified is not the same as paid.", "tags": ["Claims"], "x-mcp-tool": "claim_listing", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"slug": {"type": "string", "description": "Listing slug", "maxLength": 220}, "method": {"type": "string", "description": "Verification method", "enum": ["dns", "meta", "file", "email"]}, "email": {"type": "string", "description": "For method=email: an address at the company's domain", "format": "email", "maxLength": 254}}, "required": ["slug", "method"], "additionalProperties": false}}}}, "responses": {"201": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"], "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}]}, "get": {"operationId": "list_my_claims", "summary": "Your claims", "description": "Your claims on this site with their status and instructions.", "tags": ["Claims"], "x-mcp-tool": "list_my_claims", "parameters": [{"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}}, "/claims/{claim_id}/verify": {"post": {"operationId": "verify_claim", "summary": "Check a claim now", "description": "Checks the DNS record / meta tag / file for a pending claim. Email claims verify when you open the link in the email instead.", "tags": ["Claims"], "x-mcp-tool": "verify_claim", "parameters": [{"name": "claim_id", "in": "path", "required": true, "schema": {"type": "integer", "description": "Claim id", "minimum": 1}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["listings:write"]}, {"apiKey": []}], "x-required-scopes": ["listings:write"]}}, "/orders/quote": {"post": {"operationId": "quote_order", "summary": "Price an order (with VAT preview)", "description": "Prices a list of products for your listings using the site's current admin prices and validates every option (weeks, categories, billboard minimum). Nothing is saved or charged.", "tags": ["Orders"], "x-mcp-tool": "quote_order", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"items": {"type": "array", "description": "What to buy", "items": {"type": "object", "properties": {"product": {"type": "string", "description": "Product code from list_products, e.g. launch, skip_queue, featured, done_for_you (we list you on other high-value launch sites for you), launch_bundle, extra_categories, relaunch, ai_review, billboard_min", "maxLength": 60}, "listing_id": {"type": "integer", "description": "Your listing id (needed for products with needs_listing=true)", "minimum": 1}, "week": {"type": "string", "description": "Launch week Monday YYYY-MM-DD, one of the weeks list_products shows. launch: optional and free (omit to go live now). skip_queue: required; for FREE listings only, it replaces the free-queue week (a paid launch chooses its week on the launch product at no extra cost). relaunch: required", "maxLength": 10}, "amount_cents": {"type": "integer", "description": "billboard_min only: amount you choose, at least the minimum", "minimum": 1, "maximum": 100000000}, "categories": {"type": "array", "description": "extra_categories only: up to 3 extra category slugs", "items": {"type": "string"}, "maxItems": 10}, "options": {"type": "object", "description": "Products whose list_products entry has 'options' (e.g. trophy cabinet products): the options it describes", "additionalProperties": true, "maxProperties": 20}}, "required": ["product"], "additionalProperties": false}, "minItems": 1, "maxItems": 20}, "billing_country": {"type": "string", "description": "ISO country code for the VAT preview, e.g. GB, DE, US", "pattern": "^[A-Za-z]{2}$"}, "vat_number": {"type": "string", "description": "VAT number for the VAT preview (EU businesses: reverse charge when valid)", "maxLength": 32}}, "required": ["items"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["orders:write"]}, {"apiKey": []}], "x-required-scopes": ["orders:write"]}}, "/orders/checkout": {"post": {"operationId": "create_checkout", "summary": "Get a secure checkout link", "description": "Builds an order and returns `checkout_url`: a secure page on this site where the person reviews the order, enters billing details and pays THEMSELVES (card, Apple/Google Pay, PayPal or crypto). Give the link to the user; never ask them for card details. After payment, get_order shows the status. Send an Idempotency-Key header to make retries safe.", "tags": ["Orders"], "x-mcp-tool": "create_checkout", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"items": {"type": "array", "description": "What to buy", "items": {"type": "object", "properties": {"product": {"type": "string", "description": "Product code from list_products, e.g. launch, skip_queue, featured, done_for_you (we list you on other high-value launch sites for you), launch_bundle, extra_categories, relaunch, ai_review, billboard_min", "maxLength": 60}, "listing_id": {"type": "integer", "description": "Your listing id (needed for products with needs_listing=true)", "minimum": 1}, "week": {"type": "string", "description": "Launch week Monday YYYY-MM-DD, one of the weeks list_products shows. launch: optional and free (omit to go live now). skip_queue: required; for FREE listings only, it replaces the free-queue week (a paid launch chooses its week on the launch product at no extra cost). relaunch: required", "maxLength": 10}, "amount_cents": {"type": "integer", "description": "billboard_min only: amount you choose, at least the minimum", "minimum": 1, "maximum": 100000000}, "categories": {"type": "array", "description": "extra_categories only: up to 3 extra category slugs", "items": {"type": "string"}, "maxItems": 10}, "options": {"type": "object", "description": "Products whose list_products entry has 'options' (e.g. trophy cabinet products): the options it describes", "additionalProperties": true, "maxProperties": 20}}, "required": ["product"], "additionalProperties": false}, "minItems": 1, "maxItems": 20}, "billing_country": {"type": "string", "description": "ISO country code for the VAT preview, e.g. GB, DE, US", "pattern": "^[A-Za-z]{2}$"}, "vat_number": {"type": "string", "description": "VAT number for the VAT preview (EU businesses: reverse charge when valid)", "maxLength": 32}}, "required": ["items"], "additionalProperties": false}}}}, "responses": {"201": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["orders:write"]}, {"apiKey": []}], "x-required-scopes": ["orders:write"], "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}]}}, "/orders": {"get": {"operationId": "list_my_orders", "summary": "Your orders", "description": "Your orders on this site, newest first, with status (pending, paid, ...).", "tags": ["Orders"], "x-mcp-tool": "list_my_orders", "parameters": [{"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number (1-based)"}, "description": "Page number (1-based)"}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page"}, "description": "Items per page"}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}}, "/orders/{number}": {"get": {"operationId": "get_order", "summary": "One order and its status", "description": "An order's status, totals with VAT, lines and whether each was fulfilled.", "tags": ["Orders"], "x-mcp-tool": "get_order", "parameters": [{"name": "number", "in": "path", "required": true, "schema": {"type": "string", "description": "Order number", "maxLength": 32}}], "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}, "security": [{"oauth2": ["account:read"]}, {"apiKey": []}], "x-required-scopes": ["account:read"]}}, "/products": {"get": {"operationId": "list_products", "summary": "Products and prices", "description": "Everything you can buy on this site with its current price in USD cents (set by the site's admin; never hardcode prices). `needs_listing` products are bought for one of your listings. Prices exclude VAT; use quote_order for VAT.", "tags": ["Orders"], "x-mcp-tool": "list_products", "responses": {"200": {"description": "Success", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "security": [{}, {"oauth2": []}, {"apiKey": []}]}}}, "components": {"securitySchemes": {"oauth2": {"type": "oauth2", "description": "OAuth 2.1 authorization code + PKCE (S256). Dynamic client registration and client ID metadata documents are supported.", "flows": {"authorizationCode": {"authorizationUrl": "https://productdebuts.com/oauth/authorize", "tokenUrl": "https://productdebuts.com/oauth/token", "refreshUrl": "https://productdebuts.com/oauth/token", "scopes": {"read": "Read public data (listings, categories, launches, leaderboards, blog). Not needed for anonymous reads.", "account:read": "See your account, your listings, drafts and orders", "listings:write": "Submit new listings and edit your own drafts and listings", "orders:write": "Build orders for paid products and get a checkout link you pay yourself"}}}}, "apiKey": {"type": "http", "scheme": "bearer", "description": "Personal API key from https://productdebuts.com/account/developers"}}, "parameters": {"IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (e.g. a UUID). Retrying with the same key returns the first result instead of doing the work twice (24 h).", "schema": {"type": "string", "maxLength": 200}}}, "schemas": {"Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "status"], "properties": {"code": {"type": "string", "enum": ["invalid_request", "unauthorized", "invalid_token", "insufficient_scope", "forbidden", "not_found", "conflict", "idempotency_mismatch", "rate_limited", "quota_exceeded", "api_disabled", "server_error"]}, "message": {"type": "string"}, "status": {"type": "integer"}, "request_id": {"type": "string"}, "details": {"type": "object"}}}}}}, "responses": {"Error": {"description": "Error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "RateLimited": {"description": "Too many requests", "headers": {"Retry-After": {"schema": {"type": "integer"}, "description": "Seconds to wait"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "x-changelog": [{"version": "1.0.0", "date": "2026-10-02", "changes": "First public version: listings, categories, launches, leaderboards, founders, blog, badges and awards; submit by URL with AI drafts; edit drafts and listings; claims; orders with VAT preview and checkout links; OAuth 2.1 + API keys; MCP server."}]}