{
  "openapi": "3.1.0",
  "info": {
    "title": "Akwa API",
    "version": "2026-09-15",
    "summary": "Fashion-development intelligence as structured data: garment graphs, tailor briefs, Design Trust, confirmations, exports and Tech Packs for your own designs and Akwa's published house garments.",
    "description": "Every value carries its provenance state (asserted, inferred, unstated). Renders and imagery are never returned. Authenticate with a personal API key from Settings > Developer access on a paid plan (Authorization: Bearer akwa_sk_...), or an OAuth 2.1 access token. Rate limit: 300 requests per 5 minutes per caller. Errors are { error, code } with the HTTP status. This document is generated from the router that serves the API (supabase/functions/_shared/apiV1Router.ts) and a repository test fails when the two disagree.",
    "termsOfService": "https://www.akwa.design/terms",
    "contact": { "name": "Akwa", "url": "https://www.akwa.design/developers", "email": "hello@akwa.design" }
  },
  "servers": [
    { "url": "https://olgggkmqnncdjdxwikml.supabase.co/functions/v1/api-v1", "description": "Akwa API v1. The short form https://www.akwa.design/api/v1 is a rewrite that is not yet documented as supported." }
  ],
  "security": [{ "akwaApiKey": [] }],
  "tags": [
    { "name": "identity", "description": "Who the credential is." },
    { "name": "designs", "description": "Reads over the designs the caller owns." },
    { "name": "garments", "description": "The same reads by permanent garment identity, including published Akwa house garments." },
    { "name": "exports", "description": "Governed construction documents." },
    { "name": "tech-packs", "description": "Tech Pack requests and status." }
  ],
  "paths": {
    "/v1": {
      "get": {
        "tags": ["identity"], "operationId": "index", "security": [],
        "summary": "Route list, documentation URL and the authentication hint.",
        "responses": { "200": { "description": "The route list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Index" } } } } }
      }
    },
    "/v1/me": {
      "get": {
        "tags": ["identity"], "operationId": "me", "summary": "Who this credential is: user id, plan, scopes.",
        "responses": { "200": { "description": "The caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/designs": {
      "get": {
        "tags": ["designs"], "operationId": "listDesigns", "summary": "Your designs, newest first (limit, before).",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1 } },
          { "name": "before", "in": "query", "description": "The next_before cursor from a previous page (an ISO timestamp).", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "A page of designs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignList" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/designs/{designId}/graph": {
      "get": {
        "tags": ["designs"], "operationId": "designGraph", "summary": "Profile-filtered garment graph (profile=technical_designer|factory).",
        "parameters": [{ "$ref": "#/components/parameters/designId" }, { "$ref": "#/components/parameters/profile" }],
        "responses": { "200": { "description": "The garment graph for the profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarmentGraph" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/designs/{designId}/tailor-brief": {
      "get": {
        "tags": ["designs"], "operationId": "designTailorBrief", "summary": "The derived tailor brief.",
        "parameters": [{ "$ref": "#/components/parameters/designId" }],
        "responses": { "200": { "description": "The tailor brief, text keys only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/designs/{designId}/design-trust": {
      "get": {
        "tags": ["designs"], "operationId": "designDesignTrust", "summary": "Design Trust provenance aggregate.",
        "description": "Derived counts over the pack's own rows (callout and BOM provenance, confidence, unresolved count). No score, no grade, no verdict.",
        "parameters": [{ "$ref": "#/components/parameters/designId" }],
        "responses": { "200": { "description": "The provenance aggregate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/designs/{designId}/confirmations": {
      "get": {
        "tags": ["designs"], "operationId": "designConfirmations", "summary": "Values that still need a human decision.",
        "parameters": [{ "$ref": "#/components/parameters/designId" }],
        "responses": { "200": { "description": "Unresolved confirmations. They never block a sample or quotation export; approval is designer-initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/garments/{garmentId}/{resource}": {
      "get": {
        "tags": ["garments"], "operationId": "garmentRead",
        "summary": "The same four reads by permanent garment identity (AKW-n), including published Akwa house garments, which carry facts with epistemic states.",
        "parameters": [
          { "name": "garmentId", "in": "path", "required": true, "description": "A permanent garment identity, AKW-n. Your own minted garments, or a published Akwa house garment such as AKW-1008.", "schema": { "type": "string", "pattern": "^AKW-[0-9]+$" } },
          { "name": "resource", "in": "path", "required": true, "schema": { "type": "string", "enum": ["graph", "tailor-brief", "design-trust", "confirmations"] } },
          { "$ref": "#/components/parameters/profile" }
        ],
        "responses": { "200": { "description": "The resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarmentGraph" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/designs/{designId}/exports": {
      "post": {
        "tags": ["exports"], "operationId": "exportDesign", "summary": "Governed export (illustrator_svg_stage1 | json), one-hour download link.",
        "description": "Needs the export scope. Serves a governed construction document for the caller's own design, never a render.",
        "parameters": [{ "$ref": "#/components/parameters/designId" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } },
        "responses": { "201": { "description": "The export record and its one-hour link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResult" } } } }, "400": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/v1/designs/{designId}/tech-packs": {
      "post": {
        "tags": ["tech-packs"], "operationId": "requestTechPack", "summary": "Request a Tech Pack. Returns 202 composing (included in your plan) or 402 with a checkout link.",
        "description": "Needs the generate scope. A Tech Pack plan allowance is consumed first. Otherwise the pack is EUR 25 plus a fixed surcharge, paid at the checkout link on akwa.design; the response is 409 until that surcharge is configured.",
        "parameters": [{ "$ref": "#/components/parameters/designId" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TechPackRequest" } } } },
        "responses": {
          "202": { "description": "Composition started, included in the plan. Poll GET /v1/tech-packs/{purchaseId}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TechPackComposing" } } } },
          "402": { "description": "Payment required. Complete it at checkout_url, then poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TechPackPaymentRequired" } } } },
          "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "description": "API pricing not configured (code API_PRICING_NOT_CONFIGURED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/tech-packs/{purchaseId}": {
      "get": {
        "tags": ["tech-packs"], "operationId": "techPack", "summary": "Tech Pack status and, when delivered, a one-hour PDF link.",
        "parameters": [{ "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "The purchase, its pack state and, once fulfilled, the PDF link. pack.ready is the one readiness condition; the raw states are for compatibility.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TechPackStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/ScopeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "akwaApiKey": { "type": "http", "scheme": "bearer", "description": "A personal API key (akwa_sk_...) from Settings > Developer access, or an OAuth 2.1 access token. Scopes: read, export, generate." }
    },
    "parameters": {
      "designId": { "name": "designId", "in": "path", "required": true, "description": "A design the caller owns.", "schema": { "type": "string", "format": "uuid" } },
      "profile": { "name": "profile", "in": "query", "required": false, "description": "The reader the graph is filtered for.", "schema": { "type": "string", "enum": ["technical_designer", "factory"], "default": "technical_designer" } }
    },
    "responses": {
      "Unauthenticated": { "description": "No valid credential (code UNAUTHENTICATED). Carries WWW-Authenticate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "ScopeRequired": { "description": "The key does not carry the scope (code SCOPE_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Not found, or not owned by the caller (code NOT_FOUND or a resource-specific code).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Invalid": { "description": "The request was understood and refused (for example an unknown export driver).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "300 requests per 5 minutes per caller (code RATE_LIMITED). Carries Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": { "type": "object", "required": ["error", "code"], "properties": { "error": { "type": "string", "description": "Customer-safe wording." }, "code": { "type": "string" } } },
      "Index": { "type": "object", "properties": { "name": { "type": "string", "const": "Akwa API" }, "version": { "type": "string" }, "documentation": { "type": "string", "format": "uri" }, "authentication": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "scope": { "type": "string" }, "description": { "type": "string" } } } } } },
      "Me": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "via": { "type": "string", "description": "api_key or oauth." }, "scopes": { "type": "array", "items": { "type": "string", "enum": ["read", "export", "generate"] } }, "plan": { "type": "string" } } },
      "DesignSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": ["string", "null"] }, "garment_category": { "type": ["string", "null"] }, "sgg_garment_id": { "type": ["string", "null"], "description": "The permanent AKW-n identity once minted." }, "created_at": { "type": "string", "format": "date-time" } } },
      "DesignList": { "type": "object", "properties": { "designs": { "type": "array", "items": { "$ref": "#/components/schemas/DesignSummary" } }, "next_before": { "type": ["string", "null"] } } },
      "Resource": { "type": "object", "description": "A governed read. Every value carries its provenance state; shapes are documented at https://www.akwa.design/developers#model and in the MCP tool descriptions.", "additionalProperties": true },
      "GarmentGraph": { "type": "object", "description": "Nodes in a public shape (no raw source paths) plus, for published house garments, facts with epistemic states (asserted, inferred, unstated). Never imagery.", "additionalProperties": true },
      "ExportRequest": { "type": "object", "properties": { "profile": { "type": "string", "enum": ["technical_designer", "factory"], "default": "technical_designer" }, "driver": { "type": "string", "enum": ["illustrator_svg_stage1", "json"], "default": "illustrator_svg_stage1" } } },
      "ExportResult": { "type": "object", "description": "The export record and a one-hour download_url.", "additionalProperties": true },
      "TechPackRequest": { "type": "object", "properties": { "brand": { "type": "string" }, "sizeSelection": { "type": "object", "additionalProperties": true }, "designerNotes": { "type": "string" }, "pieceScope": { "type": "string" } } },
      "TechPackComposing": { "type": "object", "properties": { "status": { "type": "string", "const": "composing" }, "purchase_id": { "type": ["string", "null"] }, "design_id": { "type": "string" }, "message": { "type": "string" } } },
      "TechPackPaymentRequired": { "type": "object", "properties": { "status": { "type": "string", "const": "payment_required" }, "purchase_id": { "type": ["string", "null"] }, "checkout_url": { "type": "string", "format": "uri" }, "amount": { "type": ["number", "null"] }, "currency": { "type": "string" }, "label": { "type": ["string", "null"] }, "message": { "type": "string" } } },
      "TechPackStatus": { "type": "object", "properties": { "purchase_id": { "type": "string" }, "status": { "type": "string" }, "design_id": { "type": ["string", "null"] }, "amount": { "type": ["number", "null"] }, "currency": { "type": ["string", "null"] }, "pack": { "type": ["object", "null"], "properties": { "id": { "type": "string" }, "version": { "type": ["integer", "null"] }, "ready": { "type": "boolean" }, "composer_status": { "type": ["string", "null"] }, "compose_status": { "type": ["string", "null"] } } }, "pdf": { "type": ["object", "null"], "properties": { "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } }, "paid_at": { "type": ["string", "null"] }, "fulfilled_at": { "type": ["string", "null"] } } }
    }
  }
}