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.

Available Endpoints