API Reference

The YNS REST API provides programmatic access to your store's data. All endpoints are scoped to the authenticated store and served under /api/v1/.

Base URL

All API requests are made to your store's domain:

https://your-store.yns.store/api/v1/

Authentication

Every request requires a Bearer token in the Authorization header. API keys are managed in your store's admin settings under Settings → API → API keys.

curl https://your-store.yns.store/api/v1/products \
  -H "Authorization: Bearer your_api_key"

Each API key is scoped to a single store. All data returned is isolated to that store. Keys can also be scoped to specific capabilities – see API Key Scopes for the full list.

Request Format

• Content-Type: application/json for POST, PATCH, and PUT requests
• Query parameters for filtering and pagination on GET requests
• Path parameters use UUID v7 identifiers or URL slugs (e.g. /products/classic-tee)

Response Format

All responses return JSON. Successful list responses use this shape:

{
  "data": [
    { "id": "019...", "name": "Classic Tee", "slug": "classic-tee" }
  ],
  "meta": {
    "count": 42
  }
}

Single resource responses return the object directly:

{
  "id": "019...",
  "name": "Classic Tee",
  "slug": "classic-tee"
}

Pagination

List endpoints support offset-based pagination:

Some endpoints (inventory) use cursor-based pagination with a cursor parameter instead.

Error Responses

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": "Invalid request data",
  "details": [
    {
      "code": "too_small",
      "minimum": 1,
      "message": "Product name is required",
      "path": ["name"]
    }
  ]
}

OpenAPI Spec

The full OpenAPI 3.1 specification is available at:

GET /api/v1/openapi

This spec is auto-generated from the actual Zod schemas used in route handlers, so it's always in sync with the API.

MCP Server

Every store is also reachable over the Model Context Protocol at https://yns.store/mcp, so an agent can run store operations without you building an integration first. Authentication, the two tools it exposes and a ready-to-paste client config are on the MCP Server page.

Public Content API

Distinct from everything above: the marketing site publishes its own keyless API for the documentation, help centre, pricing and changelog, plus three storefront-analysis endpoints. No key, no sign-up, every operation a GET.

Any documentation page or help article also has a markdown representation at its normal URL – send Accept: text/markdown, or append .md:

curl -H "Accept: text/markdown" https://yournextstore.com/docs/api-reference/products
curl https://yournextstore.com/docs/api-reference/products.md

Content API errors

Unlike the Store API above, the content API answers every non-2xx with RFC 9457 problem details, served as application/problem+json:

{
  "type": "https://yournextstore.com/docs/api-reference/overview#content-api-errors",
  "title": "Document not found",
  "status": 404,
  "detail": "The requested documentation page does not exist.",
  "instance": "https://yournextstore.com/api/docs/api-reference/nope",
  "code": "document_not_found",
  "resolution": "List every document available in markdown at https://yournextstore.com/llms.txt.",
  "documentationUrl": "https://yournextstore.com/docs/api-reference/overview#content-api-errors"
}

Branch on code, never on title – title is prose and may be reworded.

Each type below is the anchor of the matching subsection, so a caller can follow it straight to the explanation.

API route not found

404, code: api_route_not_found. No endpoint is served at that path. Discover the real surface through /openapi.json or /.well-known/api-catalog.

Document not found

404, code: document_not_found. The section, category or slug names no page that exists. Every valid pair is listed in /llms.txt and enumerated in /openapi.json.

Missing parameter

400, code: missing_parameter. A required query parameter was absent – in practice always url.

Invalid parameter

400, code: invalid_parameter. A parameter was present but unusable, e.g. a url that is neither an absolute http(s) URL nor a hostname.

Rate limited

429, code: rate_limited. The per-IP window for that endpoint is exhausted. Wait for Retry-After seconds and retry.

Upstream unavailable

502, code: upstream_unavailable. A third party the endpoint depends on – the storefront being scanned, or the PageSpeed API – did not answer usefully. Retrying rarely helps until the upstream recovers.

Available Endpoints