{"openapi":"3.1.0","info":{"title":"Your Next Store Public Content API","version":"1.0.0","summary":"Read the YNS documentation, help centre, pricing and changelog as structured data.","description":"The public, keyless API of yournextstore.com. Use it to read every documentation page and help\narticle as markdown, to fetch current pricing and the latest release, and to analyse an existing\nstorefront for platform, plugin cost, security headers and AI-crawler visibility.\n\n**No authentication.** Every operation here is a `GET` and needs no credentials. The analysis\nendpoints (`scanStore`, `getPageSpeedReport`, `getPageMetadata`) are rate limited per IP.\n\n**Errors** are RFC 9457 `application/problem+json` with a stable `code` and a `resolution`.\n\n**This is not the Store API.** Reading or writing an actual store's products, orders and customers\nis a different, authenticated API served from the store's own host – its spec is at\n`https://yns.store/api/v1/openapi` and it is also reachable over MCP at `https://yns.store/mcp`.\nBoth are listed in the catalog at `/.well-known/api-catalog`.","contact":{"name":"Your Next Store","email":"hello@yournextstore.com","url":"https://yournextstore.com/contact"},"termsOfService":"https://yournextstore.com/terms"},"servers":[{"url":"https://yournextstore.com","description":"Production"}],"security":[],"externalDocs":{"description":"Public Content API documentation","url":"https://yournextstore.com/docs/api-reference/overview#public-content-api"},"tags":[{"name":"Discovery","description":"Entry points that describe the rest of the surface."},{"name":"Content","description":"Documentation, help articles and release notes as markdown."},{"name":"Pricing","description":"Current plan prices, limits and feature matrix."},{"name":"Analysis","description":"Inspect an existing storefront. Rate limited per IP."}],"paths":{"/sitemap.md":{"get":{"operationId":"getMarkdownSitemap","summary":"Get the markdown sitemap","description":"Returns a table of contents for the whole site as markdown: every section, with human-readable titles and the parent-child nesting an XML sitemap throws away. Links point at the `.md` representation of each page. Per-section sitemaps live at `/docs/sitemap.md`, `/help/sitemap.md`, `/blog/sitemap.md` and `/changelog/sitemap.md`.","tags":["Discovery"],"responses":{"200":{"description":"The site table of contents, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"The site table of contents, as markdown."}}}}}}},"/{section}/sitemap.md":{"get":{"operationId":"getSectionMarkdownSitemap","summary":"Get one section's markdown sitemap","description":"Returns the table of contents for a single section – every page in it, with titles, summaries and nesting, linked as markdown.","tags":["Discovery"],"parameters":[{"in":"path","name":"section","required":true,"description":"Which section's contents to list.","schema":{"type":"string","enum":["docs","help","blog","changelog"]}}],"responses":{"200":{"description":"The section's table of contents, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"The section's table of contents, as markdown."}}}},"404":{"description":"There is no sitemap for that section.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsIndex","summary":"Get the llms.txt discovery index","description":"Returns the agent-facing index of the whole site: what YNS is, when to reach for it, and a `- [title](url): summary` line for every help article and documentation page, each of which can then be read as markdown via `getHelpArticle` or `getDocumentationPage`. Start here.","tags":["Discovery"],"responses":{"200":{"description":"The llms.txt index, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"The llms.txt index, as markdown."}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"Get this OpenAPI document","description":"Returns the OpenAPI 3.1 description of the public content API – this document.","tags":["Discovery"],"responses":{"200":{"description":"An OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/api-catalog":{"get":{"operationId":"getApiCatalog","summary":"List every YNS API","description":"RFC 9727 API catalog. Lists both this public content API and the authenticated Store API, each with a link to its OpenAPI description, its documentation and its service description.","tags":["Discovery"],"responses":{"200":{"description":"An RFC 9264 linkset naming each API and its description document.","content":{"application/linkset+json":{"schema":{"$ref":"#/components/schemas/Linkset"}}}}}}},"/api/index-md":{"get":{"operationId":"getSiteOverviewMarkdown","summary":"Get the site overview as markdown","description":"The homepage rendered as markdown: what YNS is, what the platform does, current plan prices and a link map of the site. The same document is served from `GET /` when the request sends `Accept: text/markdown`.","tags":["Content"],"responses":{"200":{"description":"Site overview, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"Site overview, as markdown."}}}}}}},"/api/docs/{section}/{slug}":{"get":{"operationId":"getDocumentationPage","summary":"Get one documentation page as markdown","description":"Returns the body of a developer documentation page as markdown, frontmatter stripped. Every valid `section`/`slug` pair is listed in `/llms.txt`. The same content is served from `/docs/{section}/{slug}` when the request sends `Accept: text/markdown`, and from `/docs/{section}/{slug}.md`.","tags":["Content"],"parameters":[{"in":"path","name":"section","required":true,"description":"Documentation section.","schema":{"type":"string","enum":["getting-started","storefront","commerce-sdk","api-reference"]}},{"in":"path","name":"slug","required":true,"description":"Page slug within the section.","schema":{"type":"string","enum":["addons","analytics","authentication","availability-notifications","blog-categories","booking-slots","brand-kit","brands","bundles","cart","carts","categories","collections","configuration","contact-messages","coupons","customers","customization","deployment","domain","email-templates","events","feedback-sessions","first-store-setup","images","imports","installation","introduction","inventory","invoices","legal-pages","localization","loyalty","mcp-server","media","newsletters","orders","overview","pickup-locations","post-comments","posts","products","promotions","publish","quick-start","reviews","search","settings","shipping","socials","store","subscribers","subscription-cycles","subscription-plans","support-cases","tax-rates","team","tickets","variants","wishlist"]}}],"responses":{"200":{"description":"The documentation page body, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"The documentation page body, as markdown."}}}},"404":{"description":"No documentation page exists at that section and slug.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/help/{category}/{slug}":{"get":{"operationId":"getHelpArticle","summary":"Get one help centre article as markdown","description":"Returns the body of a help centre article as markdown, frontmatter stripped. Help articles are task-oriented and written for merchants; developer reference lives under `getDocumentationPage` instead. Every valid `category`/`slug` pair is listed in `/llms.txt`.","tags":["Content"],"parameters":[{"in":"path","name":"category","required":true,"description":"Help centre category.","schema":{"type":"string","enum":["getting-started","products","orders","payments","shipping","storefront","localization","marketing","integrations","domains","account"]}},{"in":"path","name":"slug","required":true,"description":"Article slug within the category.","schema":{"type":"string","enum":["abandoned-carts","add-a-product","add-ons","affiliate-program","ai-assistant","ai-design-builder","analytics","api-access","blog","brands","bundles","carriers-poland","carriers-usa","cart-recommendations","categories-and-collections","checkout-settings","compliance","connect-stripe","contact-messages","coupons-and-discounts","create-your-store","currencies","custom-domain","customer-accounts","customers","dashboard-tour","digital-products","email-notifications","events","free-shipping","free-subdomain","fulfill-and-ship","general-settings","get-support","go-live","import-products","invoices","legal-pages","logo-and-branding","loyalty-program","manage-inventory","manage-orders","modules","multi-currency","multi-language","navigation-menus","newsletters-and-subscribers","pages-and-content","pickup-locations","plan-and-billing","product-feeds","product-images","product-reviews","product-subscriptions","product-variants","profit-and-costs","promotions","redirects","refunds-and-returns","restock-notifications","sell-on-allegro","seo","setup-checklist","shipping-methods","social-links","store-chat","store-issues","taxes","team-members","test-mode","themes","tracking-and-pixels","volume-pricing","warehouse","welcome","welcome-offer","wholesale","wishlist"]}}],"responses":{"200":{"description":"The help article body, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"The help article body, as markdown."}}}},"404":{"description":"No help article exists at that category and slug.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/blog/{slug}":{"get":{"operationId":"getBlogPost","summary":"Read one blog post as markdown","description":"Returns the full text of a blog post as markdown, titled from its frontmatter. The same document is served from `/blog/{slug}` when the request carries `Accept: text/markdown`, or from `/blog/{slug}.md`. Every slug is listed in `/blog/sitemap.md`.","tags":["Content"],"parameters":[{"in":"path","name":"slug","required":true,"description":"The post's URL slug, as listed in `/blog/sitemap.md`.","schema":{"type":"string","examples":["agentic-commerce"]}}],"responses":{"200":{"description":"The post, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"The post, as markdown."}}}},"404":{"description":"No post has that slug.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/changelog/{slug}":{"get":{"operationId":"getChangelogEntry","summary":"Read one changelog entry as markdown","description":"Returns one release's notes as markdown, headed by its version and release date. The same document is served from `/changelog/{slug}` when the request carries `Accept: text/markdown`, or from `/changelog/{slug}.md`. Every slug is listed in `/changelog/sitemap.md`.","tags":["Content"],"parameters":[{"in":"path","name":"slug","required":true,"description":"The entry's URL slug – the release date followed by its title, as listed in `/changelog/sitemap.md`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}-.+$","examples":["2026-08-07-store-chat-global-event-search-and-admin-url-redirects"]}}],"responses":{"200":{"description":"The release notes, as markdown.","content":{"text/markdown":{"schema":{"type":"string","description":"The release notes, as markdown."}}}},"404":{"description":"No release has that slug.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/changelog/latest":{"get":{"operationId":"getLatestChangelog","summary":"Get the latest YNS release","description":"Returns the most recent changelog entry: its version, date, headline, the list of fixes, and the full release note as markdown. Use it to answer 'what shipped recently' or to check which version introduced a capability.","tags":["Content"],"responses":{"200":{"description":"The most recent release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntry"}}}}}}},"/api/pricing":{"get":{"operationId":"getPricing","summary":"Get plan pricing and the feature matrix","description":"Returns every plan with its monthly and yearly price, the full feature comparison matrix, usage limits per plan, and the overage policy. Prices are USD. YNS charges no platform transaction fee; Stripe's own processing fees still apply.","tags":["Pricing"],"responses":{"200":{"description":"Plans, feature matrix and usage limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingData"}}}}}}},"/api/pricing-md":{"get":{"operationId":"getPricingMarkdown","summary":"Get plan pricing as markdown tables","description":"The same data as `getPricing`, pre-rendered as markdown tables. Prefer this when the answer goes straight into a chat reply; prefer `getPricing` when you need to compute with the numbers.","tags":["Pricing"],"responses":{"200":{"description":"Pricing, as markdown tables.","content":{"text/markdown":{"schema":{"type":"string","description":"Pricing, as markdown tables."}}}}}}},"/api/store-scan":{"get":{"operationId":"scanStore","summary":"Scan a storefront for platform, plugin cost and AI visibility","description":"Fetches a public storefront and reports which e-commerce platform it runs on, which paid third-party plugins it loads and what they cost per month, its security-header posture, and an AI-visibility score covering server-side rendering, structured data, llms.txt and AI-crawler access in robots.txt. Rate limited to 10 requests per minute per IP.","tags":["Analysis"],"parameters":[{"in":"query","name":"url","required":true,"description":"Absolute http(s) URL of the page to analyse. A bare hostname is accepted and normalised.","schema":{"type":"string","format":"uri","examples":["https://example.com"]}}],"responses":{"200":{"description":"The scan report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreScanReport"}}}},"400":{"description":"`url` was missing or is not a usable http(s) URL.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded for this IP.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"502":{"description":"The target store could not be reached.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/pagespeed":{"get":{"operationId":"getPageSpeedReport","summary":"Run a Lighthouse audit on a page","description":"Runs a mobile and a desktop Lighthouse audit through the PageSpeed Insights API and returns both, including Core Web Vitals and the audits that most often explain a slow storefront. Rate limited to 5 requests per minute per IP; a single call takes several seconds.","tags":["Analysis"],"parameters":[{"in":"query","name":"url","required":true,"description":"Absolute http(s) URL of the page to analyse. A bare hostname is accepted and normalised.","schema":{"type":"string","format":"uri","examples":["https://example.com"]}}],"responses":{"200":{"description":"Mobile and desktop results. Either is `null` when the upstream audit did not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageSpeedReport"}}}},"400":{"description":"`url` was missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded for this IP.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/api/fetch-page-meta":{"get":{"operationId":"getPageMetadata","summary":"Read a page's title, description and OG image","description":"Fetches a public page and extracts its `<title>`, meta description and `og:image`. Each field is `null` when the page does not declare it. Rate limited to 20 requests per minute per IP; results are cached for 10 minutes per URL.","tags":["Analysis"],"parameters":[{"in":"query","name":"url","required":true,"description":"Absolute http(s) URL of the page to analyse. A bare hostname is accepted and normalised.","schema":{"type":"string","format":"uri","examples":["https://example.com"]}}],"responses":{"200":{"description":"The page's metadata, with `null` for anything absent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageMetadata"}}}},"400":{"description":"`url` was missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded for this IP.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}}},"components":{"schemas":{"Problem":{"type":"object","title":"Problem","description":"RFC 9457 problem details. Every non-2xx response on this API uses this shape, served as `application/problem+json`.","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri","description":"Documentation anchor for this error code."},"title":{"type":"string","description":"Short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code, repeated in the body."},"detail":{"type":"string","description":"What went wrong with this specific request."},"instance":{"type":"string","format":"uri","description":"The request URL the problem applies to."},"code":{"type":"string","description":"Stable machine-readable error code – branch on this, not on `title`.","enum":["api_route_not_found","document_not_found","invalid_parameter","missing_parameter","rate_limited","upstream_unavailable"]},"resolution":{"type":"string","description":"The concrete next action that resolves the error."},"documentationUrl":{"type":"string","format":"uri","description":"Where the error model is documented."}}},"Linkset":{"type":"object","title":"Linkset","description":"RFC 9264 JSON linkset, as used by the RFC 9727 API catalog.","required":["linkset"],"properties":{"linkset":{"type":"array","items":{"type":"object","required":["anchor"],"properties":{"anchor":{"type":"string","format":"uri","description":"The API's base URL."},"service-desc":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"service-doc":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"service-meta":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"status":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}}}}},"Link":{"type":"object","title":"Link","required":["href"],"properties":{"href":{"type":"string","format":"uri"},"type":{"type":"string","description":"Media type of the linked document."},"title":{"type":"string"}}},"ChangelogEntry":{"type":"object","title":"ChangelogEntry","required":["version","slug","date","title","markdown","url"],"properties":{"version":{"type":"string","description":"Release version, e.g. `1.330.0`."},"slug":{"type":"string","description":"URL slug of the entry."},"date":{"type":"string","description":"Release date, ISO 8601."},"title":{"type":"string","description":"Headline for the release."},"fixes":{"type":"array","items":{"type":"string"},"description":"Individual fixes shipped in this release."},"markdown":{"type":"string","description":"The full release note, as markdown."},"url":{"type":"string","format":"uri","description":"Canonical URL of the entry."}}},"FeatureValue":{"description":"A cell in the feature matrix: `true`/`false` for included or not, a number or string for a limit, or `{ main, sub }` when the cell carries a qualifier.","anyOf":[{"type":"boolean"},{"type":"string"},{"type":"number"},{"type":"object","required":["main"],"properties":{"main":{"type":"string"},"sub":{"type":"string"}}}]},"Plan":{"type":"object","title":"Plan","required":["name","monthlyPrice","yearlyPrice","description","features","cta","popular"],"properties":{"name":{"type":"string"},"monthlyPrice":{"description":"USD per month billed monthly. `\"Custom\"` on Enterprise.","anyOf":[{"type":"number"},{"type":"string"}]},"yearlyPrice":{"description":"USD per month billed yearly. `\"Custom\"` on Enterprise.","anyOf":[{"type":"number"},{"type":"string"}]},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"cta":{"type":"string","description":"Call-to-action label used on the pricing page."},"popular":{"type":"boolean"}}},"PricingData":{"type":"object","title":"PricingData","required":["plans","featureCategories","usageLimits","usageOveragePricing"],"properties":{"plans":{"type":"object","required":["starter","growth","pro","enterprise"],"properties":{"starter":{"$ref":"#/components/schemas/Plan"},"growth":{"$ref":"#/components/schemas/Plan"},"pro":{"$ref":"#/components/schemas/Plan"},"enterprise":{"$ref":"#/components/schemas/Plan"}}},"featureCategories":{"type":"array","description":"The feature comparison matrix, grouped into sections.","items":{"type":"object","required":["title","features"],"properties":{"title":{"type":"string"},"header":{"type":"string"},"footer":{"type":"string"},"features":{"type":"array","items":{"type":"object","required":["name","starter","growth","pro","enterprise"],"properties":{"name":{"type":"string"},"subtitle":{"type":"string"},"tooltip":{"type":"string"},"bold":{"type":"boolean"},"starter":{"$ref":"#/components/schemas/FeatureValue"},"growth":{"$ref":"#/components/schemas/FeatureValue"},"pro":{"$ref":"#/components/schemas/FeatureValue"},"enterprise":{"$ref":"#/components/schemas/FeatureValue"}}}}}}},"usageLimits":{"type":"array","description":"Per-plan usage allowances.","items":{"type":"object","required":["name","starter","growth","pro","enterprise"],"properties":{"name":{"type":"string"},"starter":{"type":"string"},"growth":{"type":"string"},"pro":{"type":"string"},"enterprise":{"type":"string"}}}},"usageOveragePricing":{"type":"string","description":"What happens past the included usage."}}},"DetectedPlugin":{"type":"object","title":"DetectedPlugin","required":["name","category","estimatedMonthlyCost"],"properties":{"name":{"type":"string"},"category":{"type":"string","description":"e.g. `Email`, `Reviews`, `Analytics`."},"estimatedMonthlyCost":{"type":"number","description":"Mid-tier plan estimate for this plugin, USD per month."}}},"StoreScanReport":{"type":"object","title":"StoreScanReport","required":["url","platform","plugins","pluginCount","security","aiVisibility","stats"],"properties":{"url":{"type":"string","format":"uri","description":"The URL after redirects."},"platform":{"type":"string","description":"Detected e-commerce platform, or `Unknown`."},"plugins":{"type":"array","items":{"$ref":"#/components/schemas/DetectedPlugin"}},"pluginCount":{"type":"integer"},"outdatedPlugins":{"type":"integer","description":"Heuristic estimate, not a version check."},"totalPluginCost":{"type":"number","description":"Sum of plugin estimates, USD per month."},"security":{"type":"object","description":"Security-header posture, with one entry per issue found.","properties":{"issues":{"type":"array","items":{"type":"object"}},"issueCount":{"type":"integer"}}},"aiVisibility":{"type":"object","required":["score","signals"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"signals":{"type":"object","properties":{"serverSideRendered":{"type":"boolean"},"productSchema":{"type":"boolean"},"organizationSchema":{"type":"boolean"},"breadcrumbSchema":{"type":"boolean"},"hasLlmsTxt":{"type":"boolean"},"blockedBotCount":{"type":"integer"}}},"structuredDataTypes":{"type":"array","items":{"type":"string"}},"bots":{"type":"array","description":"Per-crawler robots.txt verdict.","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["allowed","blocked"]}}}},"robotsTxtAvailable":{"type":"boolean"}}},"stats":{"type":"object","properties":{"htmlBytes":{"type":"integer"},"bodyTextChars":{"type":"integer"}}}}},"PageSpeedReport":{"type":"object","title":"PageSpeedReport","required":["mobile","desktop"],"properties":{"mobile":{"description":"Mobile Lighthouse result, or `null` if the audit did not complete.","anyOf":[{"type":"object"},{"type":"null"}]},"desktop":{"description":"Desktop Lighthouse result, or `null` if the audit did not complete.","anyOf":[{"type":"object"},{"type":"null"}]}}},"PageMetadata":{"type":"object","title":"PageMetadata","required":["title","description","ogImage"],"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}},"x-related-apis":[{"name":"YNS Store API","description":"Authenticated REST API for one store's products, orders, customers, inventory and checkout.","openapi":"https://yns.store/api/v1/openapi","mcp":"https://yns.store/mcp","documentation":"https://yournextstore.com/docs/api-reference/overview"}]}