openapi: 3.1.0 info: title: TRYGO Commerce API version: 0.2.0 summary: Authenticated contracts for the widget, consumer app bridge, merchant portal, internal OS, public discovery and the hub interface. description: | All endpoints live on the TRYGO Commerce runtime (`ecosystem/server`). Sessions are bearer tokens issued server-side (local test roles, the Base44 `commerceBridge`, Shopify app proxy, or extension pairing). A browser never supplies its own identity or role. Every merchant, job, asset and record is tenant-scoped. Rendering is queued; poll job status. Local mode returns `simulated: true` jobs and never fabricates an image. Rate limits, quotas and spend caps are enforced server-side regardless of the client. servers: - url: https://{host}/v1 description: Your TRYGO address, given during onboarding (HTTPS only) variables: { host: { default: commerce.trygo.example } } - url: http://localhost:4310/v1 description: Local simulation on a developer's own computer (loopback only) security: - bearer: [] components: securitySchemes: bearer: { type: http, scheme: bearer, description: Session token (1 h; 30 days for paired extensions). } hub: { type: http, scheme: bearer, description: TRYGO_HUB_TOKEN for the umbrella hub. } bridge: { type: http, scheme: bearer, description: TRYGO_BRIDGE_SECRET, server-to-server only. } schemas: Error: { type: object, properties: { error: { type: string } }, required: [error] } Job: type: object properties: id: { type: string } status: { type: string, enum: [queued, running, succeeded, failed, cancelled, expired] } variantId: { type: string } resultAssetId: { type: [string, 'null'] } simulated: { type: boolean, description: True in local mode. No image of the shopper exists. } error: { type: [string, 'null'] } reconciliation: { type: string, enum: [none, required], description: required when a paid submission outcome is unknown; admin must reconcile before any new paid request. } Variant: type: object properties: { id: { type: string }, product_id: { type: string }, tenant_id: { type: string }, title: { type: string }, category: { type: string, enum: [tops, bottoms, one-pieces, accessories] }, color: { type: string }, size: { type: string }, image_path: { type: string }, price_cents: { type: integer }, stock: { type: integer }, supported: { type: integer }, store_url: { type: string } } PublicVariant: type: object properties: { id: { type: string }, productId: { type: string }, tenantId: { type: string }, title: { type: string }, category: { type: string }, color: { type: string }, size: { type: string }, image: { type: string }, priceCents: { type: integer }, inStock: { type: boolean }, supported: { type: boolean }, storeUrl: { type: string } } Record: type: object description: Typed operating record. `data` keys are validated against the module definition returned by GET /modules. properties: { id: { type: string }, tenant_id: { type: string }, module: { type: string }, title: { type: string, maxLength: 200 }, status: { type: string }, data: { type: object }, version: { type: integer }, archived_at: { type: [integer, 'null'] }, created_at: { type: integer }, updated_at: { type: integer } } RecordWrite: type: object required: [title, status] properties: { title: { type: string }, status: { type: string }, data: { type: object }, version: { type: integer, description: Required on PATCH; optimistic concurrency. } } Queue: type: object properties: { key: { type: string }, owner: { type: string }, ownerAssigned: { type: boolean }, threshold: { type: string }, action: { type: string }, items: { type: array, items: { type: object, properties: { resource: { type: string }, title: { type: string }, detail: { type: object } } } } } Checklist: type: object properties: { key: { type: string }, label: { type: object, properties: { en: { type: string }, fr: { type: string } } }, done: { type: boolean }, detail: { type: string } } paths: /health: get: { security: [], summary: Runtime mode and provider, responses: { '200': { description: OK } } } /local-session: post: security: [] summary: Local test role (loopback only, disabled in configured mode) requestBody: { content: { application/json: { schema: { type: object, properties: { role: { type: string, enum: [shopper, merchant, support, admin] } } } } } } responses: { '201': { description: token }, '403': { description: disabled } } /bridge-session: post: security: [{ bridge: [] }] summary: Server-to-server shopper session for the Base44 commerceBridge requestBody: { content: { application/json: { schema: { type: object, required: [userId, tenantId], properties: { userId: { type: string }, tenantId: { type: string } } } } } } responses: { '201': { description: shopper token bound to the verified app user }, '401': { description: bridge secret missing } } /extension/pair: post: security: [] summary: Exchange a one-time pairing code (from /account/pairing) for a 30-day shopper session requestBody: { content: { application/json: { schema: { type: object, required: [code], properties: { code: { type: string, pattern: '^[A-F0-9]{8}$' } } } } } } responses: { '201': { description: token + tenantId }, '404': { description: invalid, used or expired } } /enquiries: post: security: [] summary: Merchant enquiry (website form). Saves a CRM record; sends nothing. requestBody: { content: { application/json: { schema: { type: object, required: [name, email, company], properties: { name: { type: string }, email: { type: string }, company: { type: string }, website: { type: string }, message: { type: string }, marketing_opt_in: { type: string } } } } } } responses: { '201': { description: saved }, '429': { description: rate limited }, '503': { description: intake tenant not configured } } /public/brands: get: { security: [], summary: Discoverable brands (active, opted in), responses: { '200': { description: list } } } /public/brands/{id}: get: { security: [], parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Brand with supported in-stock items, responses: { '200': { description: brand }, '404': { description: not found } } } /public/products/{variantId}: get: { security: [], parameters: [{ name: variantId, in: path, required: true, schema: { type: string } }], summary: Supported variant with siblings and same-store complete-the-look items, responses: { '200': { description: product, content: { application/json: { schema: { $ref: '#/components/schemas/PublicVariant' } } } }, '404': { description: not found or unsupported } } } /public/collections: get: { security: [], summary: Published collections and stories from the TRYGO house tenant CMS, responses: { '200': { description: list } } } /public/collections/{slug}: get: { security: [], parameters: [{ name: slug, in: path, required: true, schema: { type: string } }], responses: { '200': { description: collection }, '404': { description: not found } } } /public/creators: get: { security: [], summary: Published creators (empty until contracts exist), responses: { '200': { description: list + program note } } } /public/participating: get: { security: [], summary: Participating store origins and adapter types for the extension, responses: { '200': { description: list } } } /shares/{token}: get: { security: [], summary: One selected look for private voting (hashed capability token), responses: { '200': { description: look + vote counts }, '404': { description: expired or revoked } } } post: { security: [], summary: Cast or change a vote, requestBody: { content: { application/json: { schema: { type: object, required: [choice, voterId], properties: { choice: { type: string, enum: [yes, maybe] }, voterId: { type: string, minLength: 16 } } } } } }, responses: { '200': { description: saved } } } /shares/{token}/image: get: { security: [], summary: Shared result image (live mode only), responses: { '200': { description: image }, '404': { description: none } } } /catalog: get: { summary: Tenant catalog for the current session, responses: { '200': { description: variants, content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Variant' } } } } } } } /consents: post: { summary: Explicit photo consent for this store, requestBody: { content: { application/json: { schema: { type: object, required: [accepted], properties: { accepted: { type: boolean, const: true } } } } } }, responses: { '201': { description: consent id } } } /photos: post: { summary: Private input photo (JPEG/PNG/WebP ≤ 8 MB, ≥ 100 px). Expires after 24 h., requestBody: { content: { application/json: { schema: { type: object, required: [mime, base64], properties: { mime: { type: string }, base64: { type: string } } } } } }, responses: { '201': { description: asset id }, '413': { description: too large }, '415': { description: not an image } } } delete: { summary: Delete own photos, cancel in-flight jobs, revoke consent and share links for this store, responses: { '200': { description: done } } } /tryons: post: summary: Reserve allowance and queue a rendering job (idempotent per Idempotency-Key) parameters: [{ name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 8, maxLength: 128 } }] requestBody: { content: { application/json: { schema: { type: object, required: [variantId, photoAssetId, consentId], properties: { variantId: { type: string }, photoAssetId: { type: string }, consentId: { type: string } } } } } } responses: { '202': { description: queued job, content: { application/json: { schema: { $ref: '#/components/schemas/Job' } } } }, '402': { description: allowance or spend cap reached }, '409': { description: key reused with a different selection }, '422': { description: variant unsupported or out of stock }, '429': { description: two previews already in progress } } /tryons/{id}: get: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Job status, responses: { '200': { description: job, content: { application/json: { schema: { $ref: '#/components/schemas/Job' } } } } } } /tryons/{id}/cancel: post: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Cancel; an already accepted provider submission may still finish and cost money but is not delivered, responses: { '200': { description: job } } } /assets/{id}: get: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Private image (owner + tenant only), responses: { '200': { description: image bytes }, '404': { description: unavailable or expired } } } /recommendations: get: { parameters: [{ name: variant, in: query, required: true, schema: { type: string } }, { name: budget, in: query, schema: { type: integer, description: remaining budget in cents } }], summary: Same-store, in-stock, different-category items within budget, responses: { '200': { description: up to 6 variants } } } /cart-check: post: { summary: Re-verify variant availability before the merchant cart handoff, requestBody: { content: { application/json: { schema: { type: object, required: [variantId], properties: { variantId: { type: string } } } } } }, responses: { '200': { description: variant }, '409': { description: no longer available } } } /looks: get: { summary: Private saved looks, responses: { '200': { description: list } } } post: { summary: Save a succeeded job as a look (result retained 30 days), requestBody: { content: { application/json: { schema: { type: object, required: [jobId], properties: { jobId: { type: string }, title: { type: string }, collection: { type: string } } } } } }, responses: { '201': { description: look id }, '409': { description: job not succeeded } } } /looks/{id}: patch: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Rename or move to a collection, responses: { '200': { description: ok } } } delete: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Archive a look, responses: { '200': { description: ok } } } /looks/{id}/share: post: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Create a 7-day private voting link (token returned once; stored hashed), responses: { '201': { description: token } } } delete: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Revoke every link for the look, responses: { '200': { description: ok } } } /events: post: { summary: Client-side journey events (result_viewed, merchant_return, cart_confirmed only), requestBody: { content: { application/json: { schema: { type: object, required: [name], properties: { name: { type: string, enum: [result_viewed, merchant_return, cart_confirmed] }, jobId: { type: string } } } } } }, responses: { '201': { description: ok } } } /studio/profile: get: { summary: Shopper style preferences, responses: { '200': { description: profile } } } patch: { summary: Update preferences (name, style, occasion, budget, onboarded, alertsRequested), responses: { '200': { description: profile } } } /studio/items: get: { summary: Saved items (wishlist, wardrobe, external), responses: { '200': { description: list } } } post: { summary: Save a catalog variant, an own wardrobe image, or an external page reference from the extension, requestBody: { content: { application/json: { schema: { type: object, required: [kind], properties: { kind: { type: string, enum: [wishlist, wardrobe, external] }, variantId: { type: string }, assetId: { type: string }, title: { type: string }, url: { type: string, format: uri }, imageUrl: { type: string, format: uri }, collection: { type: string } } } } } }, responses: { '201': { description: item id } } } /studio/items/{id}: patch: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { '200': { description: ok } } } delete: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { '200': { description: ok } } } /studio/export: get: { summary: Export preferences and item references (no photos), responses: { '200': { description: json } } } /account: get: { summary: Shopper account summary (identity type, consents, counts, retention), responses: { '200': { description: summary } } } delete: { summary: Delete Commerce media, consents, shares, items and sessions for this shopper, responses: { '200': { description: scope note } } } /account/export: get: { summary: Full shopper export (no photos), responses: { '200': { description: json } } } /account/pairing: post: { summary: One-time 8-character extension pairing code (10 min), responses: { '201': { description: code } } } /merchant/overview: get: { summary: Installation checklist, progress and live-readiness, responses: { '200': { description: overview, content: { application/json: { schema: { type: object, properties: { checklist: { type: array, items: { $ref: '#/components/schemas/Checklist' } }, progress: { type: number }, liveReady: { type: boolean } } } } } } } } /merchant/settings: get: { summary: Appearance, staff, discoverability, theme confirmation, responses: { '200': { description: settings } } } patch: { summary: Update appearance/staff/description within brand rules (max 10 staff, validated emails), responses: { '200': { description: settings } } } /merchant/catalog: get: { summary: Variants with eligibility flags, responses: { '200': { description: list } } } /merchant/catalog/{variantId}: patch: { parameters: [{ name: variantId, in: path, required: true, schema: { type: string } }], summary: Approve/pause a variant (fail-closed; requires stock, exact image and validated category), requestBody: { content: { application/json: { schema: { type: object, properties: { supported: { type: boolean }, category: { type: string } } } } } }, responses: { '200': { description: ok }, '409': { description: not eligible } } } /merchant/usage: get: { summary: Allowance, reserved/used, spend cap, attempts per delivered output, estimated vs verified cost, live latency, 30-day series, responses: { '200': { description: usage } } } /merchant/analytics: get: { summary: 30-day event funnel and top variants (aggregates only; no order attribution), responses: { '200': { description: analytics } } } /merchant/plan: get: { summary: Billing source/state, plan hypothesis, allowance, hosted pricing URL, responses: { '200': { description: plan } } } post: { summary: Request a plan change (recorded for finance; never activates billing), responses: { '200': { description: plan } } } /admin/tenants: get: { summary: All tenants (admin), responses: { '200': { description: list } } } /admin/tenants/{id}: patch: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Set allowance, spend cap (US cents), verified billing state, active flag, reset cap cycle (audited), responses: { '200': { description: ok }, '409': { description: allowance below reserved+used } } } /modules: get: { summary: Module definitions visible to this role (labels EN/FR, statuses, typed fields, derived flag), responses: { '200': { description: list } } } /records/{module}: get: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }, { name: search, in: query, schema: { type: string } }, { name: archived, in: query, schema: { type: boolean } }], summary: List records (derived modules compute rows from live data), responses: { '200': { description: list, content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Record' } } } } } } } post: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }], summary: Create a validated record, requestBody: { content: { application/json: { schema: { $ref: '#/components/schemas/RecordWrite' } } } }, responses: { '200': { description: record }, '400': { description: validation error }, '405': { description: derived module } } } /records/{module}/export.csv: get: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }], summary: CSV export of the module (role-checked), responses: { '200': { description: text/csv } } } /records/{module}/{id}: patch: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }, { name: id, in: path, required: true, schema: { type: string } }], summary: Update with optimistic version, responses: { '200': { description: record }, '409': { description: stale version } } } /records/{module}/{id}/archive: post: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }, { name: id, in: path, required: true, schema: { type: string } }], responses: { '200': { description: ok } } } /records/{module}/{id}/restore: post: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }, { name: id, in: path, required: true, schema: { type: string } }], responses: { '200': { description: ok } } } /records/{module}/{id}/attachments: get: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }, { name: id, in: path, required: true, schema: { type: string } }], responses: { '200': { description: list } } } post: { parameters: [{ name: module, in: path, required: true, schema: { type: string } }, { name: id, in: path, required: true, schema: { type: string } }], summary: Attach PDF/text/PNG/JPEG ≤ 2 MB, responses: { '201': { description: id } } } /attachments/{id}: get: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { '200': { description: bytes } } } /queues: get: { summary: Operational queues with owner, threshold, action and current items (tenant-scoped unless admin), responses: { '200': { description: list, content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Queue' } } } } } } } /queues/owners: patch: { summary: Assign queue owners (admin), responses: { '200': { description: owners } } } /workflow/run: post: { summary: Run an active workflow rule now (admin); result recorded in workflow_runs, requestBody: { content: { application/json: { schema: { type: object, required: [id], properties: { id: { type: string } } } } } }, responses: { '201': { description: run }, '409': { description: paused } } } /workflow/runs: get: { parameters: [{ name: workflow, in: query, schema: { type: string } }], summary: Run history, responses: { '200': { description: list } } } /credits/{id}/apply: post: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }], summary: Apply an approved output credit to a tenant allowance exactly once (admin, audited), responses: { '200': { description: applied }, '409': { description: not approved or already applied } } } /reconcile/{jobId}: post: { parameters: [{ name: jobId, in: path, required: true, schema: { type: string } }], summary: Resolve an ambiguous paid submission with provider evidence (admin), requestBody: { content: { application/json: { schema: { type: object, required: [action, evidence], properties: { action: { type: string, enum: [attach_prediction, confirmed_not_accepted] }, predictionId: { type: string }, evidence: { type: string, minLength: 20 } } } } } }, responses: { '200': { description: ok } } } /metrics: get: { summary: Tenant job counts, attempts, queue, latency, events (staff), responses: { '200': { description: metrics } } } /audit: get: { summary: Last 100 audit entries for the tenant (staff), responses: { '200': { description: list } } } /system: get: { summary: Runtime monitor (admin) — worker heartbeat, queue depth, ambiguous jobs, storage, sessions, alerts, responses: { '200': { description: system } } } /surfaces: get: { summary: Every surface (website, web app, mobile app, widget, Shopify app, extension, portal, API) and connector with real configuration state (staff), responses: { '200': { description: surfaces + connectors } } } /dashboard: get: { summary: Aggregates for the OS dashboard (KPIs, 14-day previews, pipeline, tasks, meetings, recent audit), responses: { '200': { description: dashboard } } } /search: get: { parameters: [{ name: q, in: query, required: true, schema: { type: string, minLength: 2 } }], summary: Cross-module record search plus tenants (admin), scoped to accessible modules, responses: { '200': { description: records + tenants } } } /admin/tenants/{id}/{view}: get: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }, { name: view, in: path, required: true, schema: { type: string, enum: [overview, usage, analytics, catalog, settings, plan, records] } }], summary: Admin drill-down into any merchant using the portal views, responses: { '200': { description: view payload }, '403': { description: admin only } } } patch: { parameters: [{ name: id, in: path, required: true, schema: { type: string } }, { name: view, in: path, required: true, schema: { type: string, enum: [catalog, settings] } }], summary: Admin edits a merchant's catalog approval or settings (audited), responses: { '200': { description: ok } } } /hub/summary: get: { security: [{ hub: [] }, { bearer: [] }], summary: Aggregate business state for the personal umbrella hub (counts only, no personal data), responses: { '200': { description: summary }, '401': { description: token or admin session required } } }