{ "openapi": "3.1.0", "info": { "title": "CaskStack Developer & Companion API", "version": "1.0.0", "description": "Comprehensive API specification for CaskStack B2B Marketing Automation, Edge Compliance (CaaS), Offline-First Mobile Companion Sync, Webhook Ingestion, and Enterprise SCIM 2.0 Identity Provisioning.", "contact": { "name": "CaskStack Developer Ecosystem", "url": "https://caskstack.com", "email": "developers@caskstack.com" }, "license": { "name": "Proprietary / Commercial API" } }, "servers": [ { "url": "https://caskstack.com", "description": "Current Instance API Gateway" } ], "tags": [ { "name": "Mobile & Tasting Room Companion", "description": "Hardware pairing, offline delta catalog synchronization, and batch outbox ingestion for local tasting room registers." }, { "name": "Storefront & Edge Compliance (CaaS)", "description": "Age verification gates, FIPS dry precinct checks, and anonymous telemetry touchpoints." }, { "name": "AI Sommelier & Concierge", "description": "AI tasting notes generator and interactive concierge chat assistants." }, { "name": "Webhook Gateways", "description": "Real-time order completions, POS sync, and reservation webhook ingestion." }, { "name": "Enterprise SCIM 2.0", "description": "RFC 7643 / RFC 7644 user provisioning and directory synchronization." } ], "paths": { "/api/v1/health": { "get": { "tags": [ "Mobile & Tasting Room Companion" ], "summary": "Health & Ping Heartbeat", "description": "Tests connection latency, server timestamp, and resolves tenant name.", "responses": { "200": { "description": "Successful ping response", "content": { "application/json": { "example": { "online": true, "status": "ok", "tenant": "Ch\u00e2teau CaskStack Estate", "subdomain": "chateau", "server_time": "2026-08-29T12:00:00Z" } } } } } } }, "/api/v1/devices/pair": { "post": { "tags": [ "Hardware & Tasting Room Station Companion" ], "summary": "Pair Tasting Room Station Device", "description": "Registers a cellar Mac Mini, packing bench, or counter register, generating a permanent scoped API token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "device_name" ], "properties": { "device_name": { "type": "string", "example": "Cellar Packing Bench Mac Mini #1" }, "app_version": { "type": "string", "example": "1.0.0" }, "device_type": { "type": "string", "example": "desktop_station" }, "device_uuid": { "type": "string", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "settings": { "type": "object", "example": { "thermal_printer": "Zebra ZD421", "auto_sync": true } } } } } } }, "responses": { "200": { "description": "Device paired successfully", "content": { "application/json": { "example": { "device_uuid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "winery_name": "Ch\u00e2teau CaskStack Estate", "tenant_id": "c45ca5e0-1cba-45c1-8408-ff18f1a8c9e5", "subdomain": "chateau", "api_token": "csk_comp_example_token_placeholder", "settings": { "thermal_printer": "Zebra ZD421", "auto_sync": true } } } } }, "401": { "description": "Unauthorized or unknown tenant" } } } }, "/api/v1/companion/sync/pull": { "get": { "tags": [ "Mobile & Tasting Room Companion" ], "summary": "Delta Catalog Sync (Offline Caching)", "description": "Pulls customers and wine SKUs updated since the given timestamp. Supports HTTP ETag / 304 Not Modified.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 timestamp for delta updates" }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Previously received ETag header for 304 caching" } ], "responses": { "200": { "description": "Catalog delta list with ETag header" }, "304": { "description": "Not Modified - Local cache is up-to-date" }, "401": { "description": "Unauthorized device token" } } } }, "/api/v1/companion/sync/push": { "post": { "tags": [ "Mobile & Tasting Room Companion" ], "summary": "Batch Outbox Event Ingestion", "description": "Ingests offline events (club_checkin, customer_note, dispatch_scan) idempotently.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "device_uuid": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "required": [ "uuid", "type" ], "properties": { "uuid": { "type": "string" }, "type": { "type": "string", "enum": [ "club_checkin", "customer_note", "dispatch_scan", "general" ] }, "payload": { "type": "object" } } } } } } } } }, "responses": { "200": { "description": "Ingestion results with synced event UUIDs", "content": { "application/json": { "example": { "success": true, "synced_event_uuids": [ "4c3b52d9-3660-4965-98cf-bfb29b66236b" ], "failed_event_uuids": [] } } } } } } }, "/api/v1/companion/cart/handoff": { "post": { "tags": [ "Mobile & Tasting Room Companion" ], "summary": "Generate Roving POS Cart Handoff Token", "description": "Generates a short code (e.g. HO-82914) with scannable QR/barcode for cashier POS checkout.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array" }, "customer_id": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Handoff token and QR payload created" } } } }, "/api/v1/companion/cart/handoff/{code}": { "get": { "tags": [ "Mobile & Tasting Room Companion" ], "summary": "Retrieve Cached Roving Cart for POS Scanner", "description": "Retrieves the unfulfilled cart payload for cashier scanning.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "example": "HO-82914" } ], "responses": { "200": { "description": "Cart payload found" }, "404": { "description": "Cart token expired or not found" } } } }, "/api/v1/companion/dispatch/evaluate-shipping": { "post": { "tags": [ "Mobile & Tasting Room Companion" ], "summary": "Packing Bench Carrier Routing & Dispatch Evaluation", "description": "Instant delivery zone validation on destination shipping zip code.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination_zip" ], "properties": { "destination_zip": { "type": "string", "example": "94558" }, "order_number": { "type": "string", "example": "CSK-ORD-10928" } } } } } }, "responses": { "200": { "description": "Dispatch routing and safe-to-release status" } } } }, "/api/v1/companion/cellar/barrel/{code}": { "get": { "tags": [ "Mobile & Tasting Room Companion" ], "summary": "Barrel Head & Library Bin Storytelling Specs", "description": "Winemaking specs, harvest brix, and Cooper AI notes for barrel head QR codes.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "example": "BARREL-2021-CAB-04" } ], "responses": { "200": { "description": "Barrel profile and winemaking notes" } } } }, "/api/v1/caas/evaluate-zip": { "post": { "tags": [ "Storefront & Edge Compliance (CaaS)" ], "summary": "Evaluate Shipping Zip & Direct Shipping Status", "description": "Checks recipient zip code against FIPS direct-to-consumer wet/dry status and carrier coverage.", "parameters": [ { "$ref": "#/components/securitySchemes/TenantHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "zip" ], "properties": { "zip": { "type": "string", "example": "94558" } } } } } }, "responses": { "200": { "description": "Route evaluation and thermal hold status" }, "400": { "description": "Missing tenant header or invalid zip" } } } }, "/api/v1/caas/verify-age": { "post": { "tags": [ "Storefront & Edge Compliance (CaaS)" ], "summary": "Storefront 21+ Age Gate Verification", "description": "Verifies visitor legal drinking age and creates signed age gate verification token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dob" ], "properties": { "dob": { "type": "string", "format": "date", "example": "1998-05-14" } } } } } }, "responses": { "200": { "description": "Verification result and session token" } } } }, "/api/v1/telemetry/touchpoint": { "post": { "tags": [ "Storefront & Edge Compliance (CaaS)" ], "summary": "Privacy-Preserving Telemetry Tracker", "description": "Tracks anonymous interaction touchpoints (QR scans, living bottle scans, passport ratings) with PII sanitization.", "responses": { "200": { "description": "Touchpoint recorded successfully" } } } }, "/api/v1/concierge/chat": { "post": { "tags": [ "AI Sommelier & Concierge" ], "summary": "AI Sommelier Interactive Chat", "description": "Synthesizes tasting notes, food pairings, and harvest notes via Google Gemini.", "responses": { "200": { "description": "AI response stream / message" } } } }, "/api/v1/sales-completion": { "post": { "tags": [ "Webhook Gateways" ], "summary": "POS Order Completion Ingestion", "description": "Processes completed sales transactions from Vinoshipper, Commerce7, and Square POS.", "responses": { "200": { "description": "Webhook acknowledged" } } } }, "/api/scim/v2/Users": { "get": { "tags": [ "Enterprise SCIM 2.0" ], "summary": "SCIM 2.0 List Users", "description": "RFC 7644 user directory retrieval for enterprise SSO/SCIM identity providers.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of SCIM User resources" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Token", "description": "Companion Device Token or SCIM Bearer Token." }, "TenantHeader": { "type": "apiKey", "in": "header", "name": "X-Cask-Tenant", "description": "Tenant UUID or Subdomain identifier for multi-tenant context resolution." } } } }