{ "openapi": "3.1.0", "info": { "title": "DabDash Tenant API", "version": "0.0.0", "description": "REST facade over the DabDash tenant MCP tools. Every operation here dispatches into the exact same handler the tenant MCP server (/mcp) calls — the two surfaces cannot drift apart. Served from each tenant's own subdomain or mapped custom domain, never from the platform domain." }, "servers": [ { "url": "https://{tenantDomain}", "description": "Your store's subdomain (e.g. your-store-slug.dabdash.com) or mapped custom domain.", "variables": { "tenantDomain": { "default": "your-store-slug.dabdash.com", "description": "Your store's subdomain or custom domain — never the platform domain." } } } ], "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ], "components": { "securitySchemes": { "tenantApiKey": { "type": "http", "scheme": "bearer", "description": "A tenant MCP token (dmcp_...) minted from the vendor dashboard at /admin/settings/mcp." }, "tenantOAuth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://dabdash.com/mcp/tenant/{slug}/oauth/authorize", "tokenUrl": "https://dabdash.com/mcp/tenant/{slug}/oauth/token", "scopes": [] } } } }, "schemas": { "AnalyticsQueryRequest": { "properties": { "report": { "description": "The report to run", "enum": [ "revenue_by_tenant", "orders_by_status", "top_products", "revenue_over_time", "customer_stats" ], "type": "string" }, "date_from": { "description": "Start date for the report period (YYYY-MM-DD, default: 30 days ago)", "type": [ "string", "null" ] }, "date_to": { "description": "End date for the report period (YYYY-MM-DD, default: today)", "type": [ "string", "null" ] } }, "type": "object", "required": [ "report" ] }, "AnalyticsQueryResponse": { "properties": { "report": { "type": "string" }, "period": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "tenant": { "type": "string" }, "results": { "anyOf": [ { "items": { "properties": { "tenant_id": { "type": "integer" }, "status": { "type": "string" }, "date": { "type": "string" }, "product": { "type": "string" }, "orders": { "type": "integer" }, "count": { "type": "integer" }, "units_sold": { "type": "integer" }, "revenue": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "type": "array" }, { "properties": { "new_customers": { "type": "integer" }, "total_customers": { "type": "integer" } }, "type": "object" } ] } }, "type": "object" }, "BundleListRequest": { "properties": { "include_variation_ids": { "description": "Include the list of attached product variation IDs for each bundle. Defaults to false.", "type": [ "boolean", "null" ] }, "only_active": { "description": "Return only is_active bundles. Defaults to false (all bundles).", "type": [ "boolean", "null" ] } }, "type": "object" }, "BundleListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "summary": { "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "zero_discount": { "type": "integer" } }, "type": "object" }, "zero_discount_bundles": { "items": { "type": "string" }, "type": "array" }, "bundles": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "discount_display": { "type": "string" }, "is_active": { "type": "boolean" }, "is_example": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "variation_count": { "type": "integer" }, "variation_ids": { "items": { "type": "integer" }, "type": [ "array", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "BundleUpsertRequest": { "properties": { "bundle_id": { "description": "ID of an existing bundle to update. Omit to create a new bundle.", "type": [ "integer", "null" ] }, "name": { "description": "Bundle name shown to vendors and customers (e.g. \"Any 4 for $77\"). Required when creating.", "type": [ "string", "null" ] }, "quantity": { "description": "Trigger threshold — number of cart units that activates the deal. Min 2. Required when creating.", "type": [ "integer", "null" ] }, "discount_type": { "description": "\"percent\", \"fixed\" (per-unit dollars), or \"fixed_total\" (dollars for the whole set). Required when creating.", "type": [ "string", "null" ] }, "discount_value": { "description": "Percent 0–100 for \"percent\"; dollars for \"fixed\" and \"fixed_total\". Required when creating.", "type": [ "number", "null" ] }, "is_active": { "description": "Whether the bundle is live. Defaults to true on create; left unchanged on update unless passed.", "type": [ "boolean", "null" ] }, "starts_at": { "description": "Optional start datetime (tenant timezone, stored as UTC). Pass null to clear.", "type": [ "string", "null" ] }, "ends_at": { "description": "Optional end datetime (tenant timezone, stored as UTC). Must be on/after starts_at. Pass null to clear.", "type": [ "string", "null" ] }, "variation_ids": { "description": "Product variation IDs to apply the bundle to. Omit to leave membership unchanged.", "type": [ "array", "null" ] }, "variation_mode": { "description": "How to apply variation_ids: \"replace\" (default), \"add\", or \"detach\".", "type": [ "string", "null" ] } }, "type": "object" }, "BundleUpsertResponse": { "properties": { "action": { "type": "string" }, "bundle_id": { "type": "integer" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "discount_value_unit": { "type": "string" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "variation_count": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "CampaignApplyTemplateRequest": { "properties": { "campaign_id": { "description": "ID of the DRAFT campaign to apply the template to.", "type": "integer" }, "template_id": { "description": "System template id (e.g. \"summer-new-arrivals\"). Omit to list available templates.", "type": [ "string", "null" ] } }, "type": "object", "required": [ "campaign_id" ] }, "CampaignApplyTemplateResponse": { "properties": { "error": { "type": [ "string", "null" ] }, "available_templates": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "type": "object" }, "type": [ "array", "null" ] }, "action": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "integer", "null" ] }, "template_id": { "type": [ "string", "null" ] }, "html_body_length": { "type": [ "integer", "null" ] }, "has_unsubscribe_token": { "type": [ "boolean", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "CampaignControlRequest": { "properties": { "campaign_id": { "description": "ID of the campaign to pause or resume.", "type": "integer" }, "action": { "description": "\"pause\" or \"resume\".", "type": "string" }, "dry_run": { "description": "If true (default), report without writing. Pass false to apply.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "campaign_id", "action" ] }, "CampaignControlResponse": { "properties": { "action": { "type": "string" }, "dry_run": { "type": "boolean" }, "tenant_slug": { "type": "string" }, "campaign_id": { "type": "integer" }, "campaign_name": { "type": "string" }, "previous_status": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "CampaignRecipientsRequeueRequest": { "properties": { "campaign_id": { "description": "ID of the campaign to unstick.", "type": "integer" }, "include_failed": { "description": "Reset failed recipients to pending. Default true.", "type": [ "boolean", "null" ] }, "reset_stale_sending": { "description": "Reset stuck status=sending recipients to pending. Default true.", "type": [ "boolean", "null" ] }, "retry_sending_log_errors": { "description": "Retry recipients listed in the campaign sending error log (retryable types only). Default false.", "type": [ "boolean", "null" ] }, "dispatch_limit": { "description": "Max immediate send jobs when retry_sending_log_errors=true (default 200, max 500).", "type": [ "integer", "null" ] }, "dry_run": { "description": "If true (default), report counts without writing. Pass false to apply.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "campaign_id" ] }, "CampaignRecipientsRequeueResponse": { "properties": { "action": { "type": "string" }, "dry_run": { "type": "boolean" }, "tenant_slug": { "type": "string" }, "campaign_id": { "type": "integer" }, "campaign_name": { "type": "string" }, "previous_status": { "type": "string" }, "status": { "type": "string" }, "pending_before": { "type": "integer" }, "failed_before": { "type": "integer" }, "sending_before": { "type": "integer" }, "failed_requeued": { "type": "integer" }, "sending_reset": { "type": "integer" }, "pending_after": { "type": "integer" }, "failed_after": { "type": "integer" }, "sending_log_error_rows": { "type": "integer" }, "sending_log_recipients_matched": { "type": "integer" }, "sending_log_recipients_reset": { "type": "integer" }, "sending_log_jobs_dispatched": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "CampaignSendTestRequest": { "properties": { "campaign_id": { "description": "ID of the campaign to send a test copy of.", "type": "integer" }, "to_email": { "description": "Email address for an email campaign test copy.", "type": [ "string", "null" ] }, "to_phone": { "description": "Phone number for a text campaign test copy (E.164 or local format).", "type": [ "string", "null" ] } }, "type": "object", "required": [ "campaign_id" ] }, "CampaignSendTestResponse": { "properties": { "action": { "type": "string" }, "channel": { "type": "string" }, "campaign_id": { "type": "integer" }, "sent_to": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "CampaignSetImageRequest": { "properties": { "campaign_id": { "description": "ID of the DRAFT campaign to place the image into.", "type": "integer" }, "media_id": { "description": "ID of a public image in the tenant's media library to insert.", "type": "integer" }, "slot_index": { "description": "1-based placeholder to fill when the body has more than one. Defaults to the first.", "type": [ "integer", "null" ] }, "alt_text": { "description": "Override alt text. Defaults to the media asset's own alt text, then the campaign name.", "type": [ "string", "null" ] } }, "type": "object", "required": [ "campaign_id", "media_id" ] }, "CampaignSetImageResponse": { "properties": { "action": { "type": "string" }, "campaign_id": { "type": "integer" }, "media_id": { "type": "integer" }, "image_url": { "type": "string" }, "filled_placeholder": { "type": "boolean" }, "appended": { "type": "boolean" }, "image_in_body": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" }, "CampaignUpsertRequest": { "properties": { "campaign_id": { "description": "ID of an existing campaign to edit. Omit to create a new draft.", "type": [ "integer", "null" ] }, "name": { "description": "Internal campaign name (max 120 chars). Required when creating.", "type": [ "string", "null" ] }, "channel": { "description": "\"email\" (default) or \"sms\" (text blast). Only set on create.", "type": [ "string", "null" ] }, "subject": { "description": "Email subject line shown to recipients (max 200 chars). Required when creating an email campaign.", "type": [ "string", "null" ] }, "html_body": { "description": "Full email HTML. Sanitized on save. Use {{unsubscribe_url}}, {{first_name}}, {{last_name}} tokens.", "type": [ "string", "null" ] }, "sms_body": { "description": "Text message body for SMS campaigns (max 1600 chars). Required when creating a text campaign.", "type": [ "string", "null" ] }, "plain_body": { "description": "Optional plain-text alternative. Auto-derived from the HTML at send time if omitted.", "type": [ "string", "null" ] }, "mode": { "description": "\"smtp\" (default) or \"webhook\". Left unchanged on update unless passed.", "type": [ "string", "null" ] }, "audience_includes_customers": { "description": "Whether to include the tenant's customers in the audience. Defaults to true on create.", "type": [ "boolean", "null" ] } }, "type": "object" }, "CampaignUpsertResponse": { "properties": { "action": { "type": "string" }, "campaign_id": { "type": "integer" }, "name": { "type": "string" }, "channel": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "status": { "type": "string" }, "audience_includes_customers": { "type": "boolean" }, "message": { "type": "string" }, "sms_body_length": { "type": [ "integer", "null" ] }, "html_body_length": { "type": [ "integer", "null" ] }, "has_unsubscribe_token": { "type": [ "boolean", "null" ] } }, "type": "object" }, "CatalogCollapseRequest": { "properties": { "base_name": { "description": "The group to merge, exactly as returned by catalog_flattening_audit (e.g. \"GLITTER BOMB | TOP SHELF FLOWER\").", "type": "string" }, "dry_run": { "description": "Defaults to TRUE — shows the plan without changing anything. Pass false to actually merge.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "base_name" ] }, "CatalogCollapseResponse": { "properties": { "dry_run": { "type": "boolean" }, "base_name": { "type": "string" }, "survivor_product_id": { "type": [ "integer", "null" ] }, "survivor_slug": { "type": "string" }, "products_removed": { "type": "integer" }, "total_grams": { "type": "number" }, "cost_per_gram_cents": { "type": [ "integer", "null" ] }, "tiers": { "items": { "properties": { "label": { "type": "string" }, "weight_grams": { "type": "number" }, "price_cents": { "type": "integer" } }, "type": "object" }, "type": "array" }, "absorbed": { "items": { "properties": { "product_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "notes": { "items": { "type": "string" }, "type": "array" }, "tenant_slug": { "type": "string" }, "next_step": { "type": "string" } }, "type": "object" }, "CatalogFlatteningAuditRequest": { "type": "object", "properties": [] }, "CatalogFlatteningAuditResponse": { "properties": { "tenant_slug": { "type": "string" }, "summary": { "properties": { "flattened_products": { "type": "integer" }, "collapsible_families": { "type": "integer" }, "blocked_families": { "type": "integer" }, "products_removed_if_merged": { "type": "integer" } }, "type": "object" }, "families": { "items": { "properties": { "base_name": { "type": "string" }, "collapsible": { "type": "boolean" }, "blocker": { "type": [ "string", "null" ] }, "members": { "items": { "properties": { "product_id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "weight_grams": { "type": "number" }, "price_cents": { "type": "integer" }, "cost_cents": { "type": [ "integer", "null" ] }, "stock_units": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "CategoryManageRequest": { "properties": { "action": { "description": "\"list\" (default), \"create\", \"update\", or \"delete\".", "type": [ "string", "null" ] }, "category_id": { "description": "ID of an existing category. Required for update and delete.", "type": [ "integer", "null" ] }, "name": { "description": "Category name shown to customers. Required when creating.", "type": [ "string", "null" ] }, "slug": { "description": "URL slug, unique per tenant. Auto-generated from name when omitted on create.", "type": [ "string", "null" ] }, "description": { "description": "Optional category description.", "type": [ "string", "null" ] }, "parent_id": { "description": "Parent category id, or null for a top-level category.", "type": [ "integer", "null" ] }, "sort_order": { "description": "Display order (lower sorts first).", "type": [ "integer", "null" ] }, "is_active": { "description": "Whether the category is visible on the storefront.", "type": [ "boolean", "null" ] }, "is_featured": { "description": "Whether the category appears in the homepage featured grid.", "type": [ "boolean", "null" ] }, "media_id": { "description": "Media library asset id to set as image_path (the branded, customer-facing image).", "type": [ "integer", "null" ] }, "base_media_id": { "description": "Media library asset id to set as base_image_path (the unbranded source canvas).", "type": [ "integer", "null" ] }, "confirm": { "description": "Required (true) for action=delete.", "type": [ "boolean", "null" ] } }, "type": "object" }, "CategoryManageResponse": { "properties": { "action": { "type": "string" }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "total": { "type": [ "integer", "null" ] }, "categories": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": [ "integer", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_featured": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] }, "product_count": { "type": "integer" } }, "type": "object" }, "type": [ "array", "null" ] }, "category": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": [ "integer", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_featured": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "CustomerAddressesRequest": { "properties": { "customer_id": { "description": "Exact customer id (optional)", "type": [ "integer", "null" ] }, "email": { "description": "Exact customer email (optional)", "type": [ "string", "null" ] }, "phone": { "description": "Customer phone number (optional)", "type": [ "string", "null" ] } }, "type": "object" }, "CustomerAddressesResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "customer": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "default_address_id": { "type": [ "integer", "null" ] } }, "type": "object" }, "addresses": { "items": { "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "address": { "type": "string" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "saved_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "detected_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "zone_matches_saved_zone": { "type": [ "boolean", "null" ] }, "is_default": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "CustomerListRequest": { "properties": { "updated_since": { "description": "ISO-8601 timestamp — only return customers updated at or after this time (optional)", "type": [ "string", "null" ] }, "limit": { "description": "Rows per page (default 25, max 100)", "type": [ "integer", "null" ] }, "cursor": { "description": "Opaque cursor from a previous response's next_cursor — omit to start from the first page", "type": [ "string", "null" ] } }, "type": "object" }, "CustomerListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "customers": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "loyalty_points": { "type": "integer" }, "email_verified_at": { "type": [ "string", "null" ] }, "last_login_at": { "type": [ "string", "null" ] }, "id_verified_at": { "type": [ "string", "null" ] }, "medical_record_verified_at": { "type": [ "string", "null" ] }, "phone_verified_at": { "type": [ "string", "null" ] }, "phone_validation_status": { "type": "string" }, "no_loyalty": { "type": "boolean" }, "no_coupons": { "type": "boolean" }, "deletion_requested_at": { "type": [ "string", "null" ] }, "email_opt_out": { "type": "boolean" }, "sms_marketing_opt_out": { "type": "boolean" }, "sms_notifications_muted": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "CustomerLookupRequest": { "properties": { "customer_id": { "description": "Exact customer id (optional)", "type": [ "integer", "null" ] }, "email": { "description": "Exact customer email (optional)", "type": [ "string", "null" ] }, "phone": { "description": "Customer phone number, digits or formatted (optional)", "type": [ "string", "null" ] }, "name": { "description": "Partial customer name (optional)", "type": [ "string", "null" ] }, "limit": { "description": "Number of matches to return (default 10, max 25)", "type": [ "integer", "null" ] } }, "type": "object" }, "CustomerLookupResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "matched_customers": { "type": "integer" }, "customers": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "loyalty_points": { "type": "integer" }, "email_verified_at": { "type": [ "string", "null" ] }, "last_login_at": { "type": [ "string", "null" ] }, "default_address_id": { "type": [ "integer", "null" ] }, "id_verified_at": { "type": [ "string", "null" ] }, "medical_record_verified_at": { "type": [ "string", "null" ] }, "phone_verified_at": { "type": [ "string", "null" ] }, "phone_validation_status": { "type": "string" }, "no_loyalty": { "type": "boolean" }, "no_coupons": { "type": "boolean" }, "deletion_requested_at": { "type": [ "string", "null" ] }, "email_opt_out": { "type": "boolean" }, "sms_marketing_opt_out": { "type": "boolean" }, "sms_notifications_muted": { "type": "boolean" }, "addresses_count": { "type": "integer" }, "orders_count": { "type": "integer" }, "conversation_count": { "type": "integer" }, "addresses": { "items": { "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "address": { "type": "string" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "zone_id": { "type": [ "integer", "null" ] }, "zone_name": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "recent_orders": { "items": { "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "total": { "type": "integer" }, "total_display": { "type": "string" }, "coupon_code": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "CustomerUpdateRequest": { "properties": { "customer_id": { "description": "The customer to update", "type": "integer" }, "name": { "description": "New display name", "type": [ "string", "null" ] }, "email": { "description": "New email address (must be unique within the tenant)", "type": [ "string", "null" ] }, "phone": { "description": "New phone number, digits or formatted", "type": [ "string", "null" ] }, "email_opt_out": { "description": "Set true to suppress marketing email. Cannot be set to false — un-suppression happens in DabDash only.", "type": [ "boolean", "null" ] }, "sms_marketing_opt_out": { "description": "Set true to suppress marketing texts. Cannot be set to false.", "type": [ "boolean", "null" ] }, "sms_notifications_muted": { "description": "Set true to mute transactional/order SMS notifications. Cannot be set to false.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "customer_id" ] }, "CustomerUpdateResponse": { "properties": { "customer": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email_opt_out": { "type": "boolean" }, "sms_marketing_opt_out": { "type": "boolean" }, "sms_notifications_muted": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ] } }, "type": "object" }, "updated_fields": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "GoogleAnalyticsRequest": { "properties": { "report": { "description": "The report type to run", "enum": [ "overview", "top_pages", "traffic_sources", "top_events", "daily_trend" ], "type": "string" }, "days": { "description": "Number of days to look back (default 30, max 365)", "type": [ "integer", "null" ] } }, "type": "object", "required": [ "report" ] }, "GoogleAnalyticsResponse": { "properties": { "scope": { "type": "string" }, "property": { "type": [ "string", "null" ] }, "property_id": { "type": [ "string", "null" ] }, "report": { "type": "string" }, "days": { "type": "integer" }, "results": { "anyOf": [ { "properties": { "sessions": { "type": [ "integer", "null" ] }, "avg_session_duration": { "type": [ "string", "null" ] }, "avg_session_duration_seconds": { "type": [ "number", "null" ] }, "pageviews": { "type": [ "integer", "null" ] }, "bounce_rate": { "type": [ "number", "null" ] }, "users": { "type": [ "integer", "null" ] } }, "type": "object" }, { "items": { "properties": { "path": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "medium": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] }, "pageviews": { "type": [ "integer", "null" ] }, "sessions": { "type": [ "integer", "null" ] }, "users": { "type": [ "integer", "null" ] }, "count": { "type": [ "integer", "null" ] }, "bounce_rate": { "type": [ "number", "null" ] }, "avg_session_duration": { "type": [ "number", "null" ] }, "mobile_pct": { "type": [ "number", "null" ] }, "desktop_pct": { "type": [ "number", "null" ] } }, "type": "object" }, "type": "array" } ] } }, "type": "object" }, "InventoryAuditLookupRequest": { "properties": { "product_ids": { "description": "List of product IDs to look up.", "type": "array" }, "cutoff_iso": { "description": "ISO8601 timestamp. The last quantity_after strictly BEFORE this moment is returned for each variation. Example: \"2026-05-03T00:00:00Z\".", "type": "string" } }, "type": "object", "required": [ "product_ids", "cutoff_iso" ] }, "InventoryAuditLookupResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "cutoff": { "type": "string" }, "not_found_product_ids": { "items": { "type": "integer" }, "type": "array" }, "products": { "items": { "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "product_slug": { "type": "string" }, "current_state": { "properties": { "tracking_type": { "type": "string" }, "inventory_mode": { "type": [ "string", "null" ] }, "pricing_structure_id": { "type": [ "integer", "null" ] }, "product_stock_quantity": { "type": "number" }, "variations": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "stock_quantity": { "type": "number" }, "price_cents": { "type": "integer" }, "weight_value": { "type": [ "number", "null" ] }, "sort_order": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "audit_history": { "items": { "properties": { "variation_id": { "type": [ "integer", "null" ] }, "last_quantity_after_before_cutoff": { "type": [ "number", "null" ] }, "last_action": { "type": [ "string", "null" ] }, "last_notes": { "type": [ "string", "null" ] }, "last_reference_type": { "type": [ "string", "null" ] }, "last_logged_at": { "type": "string" }, "variation_currently_exists": { "type": "boolean" }, "variation_current_name": { "type": [ "string", "null" ] }, "variation_current_stock": { "type": [ "number", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "InventoryStatusRequest": { "properties": { "alert_only": { "description": "If true, return only low-stock and out-of-stock items (default false)", "type": [ "boolean", "null" ] } }, "type": "object" }, "InventoryStatusResponse": { "properties": { "summary": { "properties": { "total_products": { "type": "integer" }, "in_stock": { "type": "integer" }, "low_stock_alerts": { "type": "integer" }, "out_of_stock": { "type": "integer" } }, "type": "object" }, "low_stock_alerts": { "items": { "properties": { "tenant": { "type": "string" }, "product": { "type": "string" }, "quantity": { "type": "number" }, "threshold": { "type": "number" } }, "type": "object" }, "type": "array" }, "out_of_stock": { "items": { "properties": { "tenant": { "type": "string" }, "product": { "type": "string" } }, "type": "object" }, "type": "array" }, "in_stock_items": { "items": { "properties": { "tenant": { "type": "string" }, "product": { "type": "string" }, "quantity": { "type": "number" } }, "type": "object" }, "type": [ "array", "null" ] } }, "type": "object" }, "MailboxInspectRequest": { "properties": { "platform": { "description": "Inspect a platform-owned mailbox (tenant_id IS NULL). When true, tenant_slug is ignored and email_account_id is required.", "type": "boolean" }, "email_account_id": { "description": "Specific EmailAccount id (required for platform=true; optional for tenant_slug — defaults to the tenant's single mailbox).", "type": "integer" } }, "type": "object" }, "MailboxInspectResponse": { "properties": { "account": { "properties": { "id": { "type": "integer" }, "tenant_id": { "type": [ "integer", "null" ] }, "tenant_slug": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "encryption": { "type": "string" }, "folder": { "type": "string" }, "is_active": { "type": "boolean" }, "leave_on_server": { "type": "boolean" } }, "type": "object" }, "sync_state": { "properties": { "last_synced_uid": { "type": [ "integer", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] }, "minutes_since_last_sync": { "type": [ "integer", "null" ] }, "last_sync_error": { "type": [ "string", "null" ] }, "last_sync_error_at": { "type": [ "string", "null" ] }, "minutes_since_last_error": { "type": [ "integer", "null" ] } }, "type": "object" }, "ingestion": { "properties": { "inbound_count": { "type": "integer" }, "outbound_count": { "type": "integer" }, "total_count": { "type": "integer" }, "last_inbound_fetched_at": { "type": [ "string", "null" ] }, "last_inbound_minutes_ago": { "type": [ "integer", "null" ] } }, "type": "object" }, "verdict": { "properties": { "state": { "type": "string" }, "explanation": { "type": "string" }, "suggested_action": { "type": [ "string", "null" ] } }, "type": "object" }, "recent_messages": { "items": { "properties": { "id": { "type": "integer" }, "direction": { "type": "string" }, "from_domain": { "type": [ "string", "null" ] }, "subject_length": { "type": "integer" }, "fetched_at": { "type": [ "string", "null" ] }, "has_attachments": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "MediaComposeRequest": { "properties": { "base_media_id": { "description": "ID of a library image to use as the background. Provide exactly one of base_media_id or base_url.", "type": [ "integer", "null" ] }, "base_url": { "description": "Public http(s) URL of the background image. Provide exactly one of base_media_id or base_url.", "type": [ "string", "null" ] }, "logo_media_id": { "description": "ID of a library image to place on top, unaltered. At most one of logo_media_id or logo_url.", "type": [ "integer", "null" ] }, "logo_url": { "description": "Public http(s) URL of the logo to place on top, unaltered.", "type": [ "string", "null" ] }, "headline": { "description": "Large text under the logo (max 120 chars). Wrapped to at most 2 lines.", "type": [ "string", "null" ] }, "subtitle": { "description": "Smaller text under the headline (max 200 chars). Wrapped to at most 3 lines.", "type": [ "string", "null" ] }, "font": { "description": "Typeface: anton, bebas, oswald, playfair, sans, serif. Defaults to \"sans\".", "type": [ "string", "null" ] }, "logo_position": { "description": "Vertical placement of the whole block: \"top\", \"center\" (default) or \"bottom\".", "type": [ "string", "null" ] }, "logo_width_pct": { "description": "Logo width as a fraction of the base width, 0.05-0.90. Defaults to 0.30.", "type": [ "number", "null" ] }, "text_color": { "description": "Headline colour as #RRGGBB. Defaults to #FFFFFF.", "type": [ "string", "null" ] }, "subtitle_color": { "description": "Subtitle colour as #RRGGBB. Defaults to text_color.", "type": [ "string", "null" ] }, "headline_size_pct": { "description": "Headline size as a fraction of base width, 0.01-0.25. Defaults to 0.07.", "type": [ "number", "null" ] }, "subtitle_size_pct": { "description": "Subtitle size as a fraction of base width, 0.01-0.15. Defaults to 0.035.", "type": [ "number", "null" ] }, "scrim": { "description": "Darkening behind the logo/text for legibility: \"none\", \"soft\" (default) or \"strong\".", "type": [ "string", "null" ] }, "text_shadow": { "description": "Draw a soft shadow under the text. Defaults to true.", "type": [ "boolean", "null" ] }, "filename": { "description": "Filename to record for the new asset (e.g. \"natal-day-hero.png\").", "type": [ "string", "null" ] }, "alt_text": { "description": "Alt text for accessibility and captions (max 500 chars).", "type": [ "string", "null" ] }, "folder": { "description": "Library folder to group the asset under (max 100 chars).", "type": [ "string", "null" ] } }, "type": "object" }, "MediaComposeResponse": { "properties": { "action": { "type": "string" }, "media_id": { "type": "integer" }, "url": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "size_bytes": { "type": "integer" }, "original_filename": { "type": [ "string", "null" ] }, "alt_text": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ] }, "visibility": { "type": "string" }, "composed_layers": { "type": "string" }, "wrapped": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" }, "MediaListRequest": { "properties": { "visibility": { "description": "\"public\" (default), \"private\", or \"all\".", "type": [ "string", "null" ] }, "folder": { "description": "Only return assets in this exact library folder.", "type": [ "string", "null" ] }, "search": { "description": "Filter by a substring of the original filename.", "type": [ "string", "null" ] } }, "type": "object" }, "MediaListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "visibility": { "type": "string" }, "total": { "type": "integer" }, "returned": { "type": "integer" }, "truncated": { "type": "boolean" }, "assets": { "items": { "properties": { "media_id": { "type": "integer" }, "url": { "type": "string" }, "original_filename": { "type": [ "string", "null" ] }, "mime_type": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "orientation": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ] }, "alt_text": { "type": [ "string", "null" ] }, "size_bytes": { "type": "integer" }, "visibility": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "MediaUploadRequest": { "properties": { "source_url": { "description": "Public http(s) URL to fetch the image from. Provide exactly one source.", "type": [ "string", "null" ] }, "source_path": { "description": "Local file path to read the image from. Provide exactly one source.", "type": [ "string", "null" ] }, "source_base64": { "description": "Base64-encoded image bytes (data: prefix optional). Provide exactly one source.", "type": [ "string", "null" ] }, "filename": { "description": "Original filename to record (e.g. \"summer-flyer.png\"). Defaults to a derived name.", "type": [ "string", "null" ] }, "alt_text": { "description": "Alt text for accessibility and captions (max 500 chars).", "type": [ "string", "null" ] }, "folder": { "description": "Optional library folder to group the asset under (max 100 chars).", "type": [ "string", "null" ] } }, "type": "object" }, "MediaUploadResponse": { "properties": { "action": { "type": "string" }, "media_id": { "type": "integer" }, "url": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "size_bytes": { "type": "integer" }, "original_filename": { "type": [ "string", "null" ] }, "alt_text": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ] }, "visibility": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "MetrcDiagnosticsRequest": { "type": "object", "properties": [] }, "MetrcDiagnosticsResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "integration": { "anyOf": [ { "properties": { "status": { "type": "string" } }, "type": "object" }, { "properties": { "status": { "type": "string" }, "mode": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "license_number": { "type": "string" }, "connected_at": { "type": [ "string", "null" ] }, "last_error_at": { "type": [ "string", "null" ] }, "last_error_message": { "type": [ "string", "null" ] } }, "type": "object" } ] }, "sync_states": { "items": { "properties": { "resource": { "type": "string" }, "last_run_at": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "audit_log_counts_by_http_status": { "type": "object" }, "report_counts_by_status": { "type": "object" }, "last_reconciliation_run": { "properties": { "run_at": { "type": "string" }, "matched_count": { "type": "integer" }, "drifted_count": { "type": "integer" }, "note": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" }, "OrderDashboardRequest": { "properties": { "order_number": { "description": "Exact order number (optional)", "type": [ "string", "null" ] }, "customer_email": { "description": "Exact customer email (optional)", "type": [ "string", "null" ] }, "customer_phone": { "description": "Customer phone number, digits or formatted (optional)", "type": [ "string", "null" ] }, "status": { "description": "Filter by order status: pending, confirmed, preparing, out_for_delivery, delivered, cancelled", "enum": [ "pending", "confirmed", "preparing", "out_for_delivery", "delivered", "cancelled" ], "type": [ "string", "null" ] }, "payment_status": { "description": "Filter by payment status: pending, paid, failed, refunded", "enum": [ "pending", "paid", "failed", "refunded" ], "type": [ "string", "null" ] }, "date_from": { "description": "Start date filter (YYYY-MM-DD format)", "type": [ "string", "null" ] }, "date_to": { "description": "End date filter (YYYY-MM-DD format)", "type": [ "string", "null" ] }, "min_total": { "description": "Minimum order total in cents", "type": [ "integer", "null" ] }, "limit": { "description": "Number of orders to return (default 25, max 100)", "type": [ "integer", "null" ] } }, "type": "object" }, "OrderDashboardResponse": { "properties": { "summary": { "properties": { "matched_orders": { "type": "integer" }, "total_revenue_cents": { "type": "integer" }, "total_revenue": { "type": "string" } }, "type": "object" }, "orders": { "items": { "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "tenant": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "subtotal": { "type": "string" }, "total": { "type": "string" }, "customer_email": { "type": [ "string", "null" ] }, "customer_phone": { "type": [ "string", "null" ] }, "coupon_code": { "type": [ "string", "null" ] }, "coupon_discount": { "type": "string" }, "mix_match_discount": { "type": "string" }, "loyalty_discount": { "type": "string" }, "is_asap": { "type": "boolean" }, "scheduled_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureAssignRequest": { "properties": { "structure_id": { "description": "ID of the shared BUNDLE structure to assign. Must NOT be a hidden (inline) structure.", "type": "integer" }, "product_slugs": { "description": "List of product slugs to assign to this structure. Provide product_slugs or product_ids (or both).", "type": [ "array", "null" ] }, "product_ids": { "description": "List of product IDs to assign to this structure. Provide product_slugs or product_ids (or both).", "type": [ "array", "null" ] } }, "type": "object", "required": [ "structure_id" ] }, "PricingStructureAssignResponse": { "properties": { "structure_id": { "type": "integer" }, "structure_name": { "type": "string" }, "tracking_type": { "type": "string" }, "summary": { "properties": { "assigned": { "type": "integer" }, "skipped": { "type": "integer" }, "refused": { "type": "integer" }, "not_found": { "type": "integer" } }, "type": "object" }, "results": { "items": { "properties": { "identifier": { "type": [ "integer", "string" ] }, "product_id": { "type": [ "integer", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "orphaned_structure_deleted": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureDeleteRequest": { "properties": { "structure_ids": { "description": "List of structure IDs to delete. Bundle structures are always accepted; inline structures are only accepted when product_count=0.", "type": "array" }, "force": { "description": "If true, deletes even if products are still assigned (they will be orphaned — use only after migrating products). Requires orphan_products_acknowledged=true alongside.", "type": [ "boolean", "null" ] }, "orphan_products_acknowledged": { "description": "Explicit acknowledgment that force=true will orphan products. Required when force=true and any structure has product_count > 0. Defaults to false.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "structure_ids" ] }, "PricingStructureDeleteResponse": { "properties": { "summary": { "properties": { "deleted": { "type": "integer" }, "refused": { "type": "integer" }, "not_found": { "type": "integer" } }, "type": "object" }, "results": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "product_count": { "type": [ "integer", "null" ] }, "product_count_at_deletion": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureListRequest": { "properties": { "kind": { "description": "Filter by kind: \"inline\" for hidden 1:1 structures, \"bundle\" for shared structures, or omit for all.", "type": [ "string", "null" ] }, "include_tiers": { "description": "Include tier details for each structure. Defaults to false.", "type": [ "boolean", "null" ] }, "include_product_ids": { "description": "Include the list of product IDs assigned to each structure. Defaults to false.", "type": [ "boolean", "null" ] } }, "type": "object" }, "PricingStructureListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "summary": { "properties": { "total": { "type": "integer" }, "bundle_count": { "type": "integer" }, "inline_count": { "type": "integer" } }, "type": "object" }, "structures": { "items": { "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "tracking_type": { "type": "string" }, "family": { "type": "string" }, "is_default": { "type": "boolean" }, "product_count": { "type": "integer" }, "product_ids": { "items": { "type": "integer" }, "type": [ "array", "null" ] }, "tiers": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "weight_grams": { "type": "number" }, "price_cents": { "type": "integer" }, "price_display": { "type": "string" }, "compare_at_price_cents": { "type": [ "integer", "null" ] }, "compare_at_price_display": { "type": [ "string", "null" ] }, "cost_price_cents": { "type": [ "integer", "null" ] }, "mix_match_tags": { "type": [ "array", "null" ] }, "sort_order": { "type": "integer" } }, "type": "object" }, "type": [ "array", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureRestoreRequest": { "properties": { "product_id": { "description": "The product whose pricing structure and variations will be rebuilt.", "type": "integer" }, "tracking_type": { "description": "Tracking type for the new inline structure: simple, unit, weight, matrix, matrix_unit.", "type": "string" }, "inventory_mode": { "description": "Inventory mode override: \"product\" or \"variation\". If omitted, defaults are applied per tracking_type rules (weight→product, matrix→variation).", "type": [ "string", "null" ] }, "product_stock_quantity": { "description": "When inventory_mode=product, the value to set on products.stock_quantity. Ignored otherwise.", "type": [ "number", "null" ] }, "tiers": { "description": "Array of tiers. Each: {name (string, required), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), weight_grams (number, required for weight/matrix), mix_match_tags (array, nullable), stock_quantity (number, required), restore_variation_id (int, optional — re-uses an existing variation row).}", "type": "array" }, "delete_unreferenced": { "description": "If true, hard-deletes variations not referenced in tiers. Default false (deactivates them).", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "product_id", "tracking_type", "tiers" ] }, "PricingStructureRestoreResponse": { "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "new_structure_id": { "type": "integer" }, "tracking_type": { "type": "string" }, "inventory_mode": { "type": "string" }, "tiers": { "items": { "properties": { "tier_name": { "type": "string" }, "variation_id": { "type": "integer" }, "action": { "type": "string" }, "stock_quantity": { "type": "number" } }, "type": "object" }, "type": "array" }, "unreferenced_variations": { "items": { "properties": { "variation_id": { "type": "integer" }, "name": { "type": "string" }, "stock_quantity": { "type": "number" } }, "type": "object" }, "type": "array" }, "unreferenced_action": { "type": "string" } }, "type": "object" }, "PricingStructureUpsertRequest": { "properties": { "structure_id": { "description": "ID of an existing BUNDLE structure to update. Must NOT be a hidden (inline) structure. Omit to create a new bundle or to edit inline via product_slug/product_id.", "type": [ "integer", "null" ] }, "product_slug": { "description": "Product slug for inline (1:1) mode. Identifies which product's hidden structure to edit. Mutually exclusive with structure_id.", "type": [ "string", "null" ] }, "product_id": { "description": "Product id for inline (1:1) mode. Alternative to product_slug. Mutually exclusive with structure_id.", "type": [ "integer", "null" ] }, "name": { "description": "Structure name. Required when creating a bundle. Ignored for inline structures (name is derived from the product name).", "type": [ "string", "null" ] }, "tracking_type": { "description": "Pricing type: simple, weight, unit, matrix, or matrix_unit. Required when creating. For updates, changing tracking_type re-syncs all linked products.", "type": [ "string", "null" ] }, "tiers": { "description": "Replacement tier list. Each tier: {name (string, required), weight_grams (number, required for weight/matrix), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), mix_match_tags (array of strings, nullable)}.", "type": [ "array", "null" ] } }, "type": "object" }, "PricingStructureUpsertResponse": { "properties": { "mode": { "type": "string" }, "structure_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "tracking_type": { "type": [ "string", "null" ] }, "tier_count": { "type": [ "integer", "null" ] }, "products_resynced": { "type": [ "integer", "null" ] }, "warning": { "type": [ "string", "null" ] }, "product_id": { "type": [ "integer", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "ProductInspectRequest": { "properties": { "product_id": { "description": "Exact product id (optional if name_query or sku supplied)", "type": [ "integer", "null" ] }, "name_query": { "description": "Partial product name match (optional if product_id or sku supplied)", "type": [ "string", "null" ] }, "sku": { "description": "Exact SKU of a variation belonging to the product (optional if product_id or name_query supplied). SKUs are unique per tenant.", "type": [ "string", "null" ] } }, "type": "object" }, "ProductInspectResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "mix_match_settings": { "properties": { "default_quantity": { "type": "integer" }, "default_discount_type": { "type": "string" }, "default_discount_value": { "type": "number" }, "rules": { "type": "array" } }, "type": "object" }, "products": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "tracking_type": { "type": "string" }, "inventory_mode": { "type": [ "string", "null" ] }, "stock_quantity": { "type": "number" }, "stock_status": { "type": "string" }, "pricing_structure": { "type": [ "string", "null" ] }, "variations": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "price_cents": { "type": "integer" }, "price_display": { "type": "string" }, "compare_at_price_cents": { "type": [ "integer", "null" ] }, "compare_at_price_display": { "type": [ "string", "null" ] }, "on_sale": { "type": "boolean" }, "mix_match_tags": { "type": [ "array", "null" ] }, "weight_value": { "type": [ "number", "null" ] }, "stock_quantity": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "ProductUpdateBySkuRequest": { "properties": { "sku": { "description": "Exact SKU of the product's variation. SKUs are unique per tenant.", "type": "string" }, "stock_quantity": { "description": "New absolute stock quantity (unit count, not grams). Omit to leave stock unchanged.", "type": [ "number", "null" ] }, "price": { "description": "New price in dollars (e.g. 24.99). Omit to leave price unchanged.", "type": [ "number", "null" ] } }, "type": "object", "required": [ "sku" ] }, "ProductUpdateBySkuResponse": { "properties": { "product_id": { "type": "integer" }, "variation_id": { "type": "integer" }, "sku": { "type": "string" }, "stock_quantity": { "type": [ "number", "null" ] }, "price_cents": { "type": [ "integer", "null" ] }, "updated_fields": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "PromotionAuditRequest": { "properties": { "order_number": { "description": "Optional order number to compare against configured promotions", "type": [ "string", "null" ] }, "include_inactive": { "description": "Include inactive or expired promotions too (optional)", "type": [ "boolean", "null" ] } }, "type": "object" }, "PromotionAuditResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "order": { "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "subtotal": { "type": "integer" }, "delivery_fee": { "type": "integer" }, "service_fee": { "type": "integer" }, "discount_amount": { "type": "integer" }, "coupon_code": { "type": [ "string", "null" ] }, "coupon_type": { "type": [ "string", "null" ] }, "coupon_discount": { "type": "integer" }, "mix_match_discount": { "type": "integer" }, "loyalty_points_redeemed": { "type": "integer" }, "loyalty_discount": { "type": "integer" }, "total": { "type": "integer" }, "zone": { "type": [ "string", "null" ] }, "items": { "items": { "properties": { "product": { "type": [ "string", "null" ] }, "variation": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "line_total": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] }, "storewide_sale": { "properties": { "active": { "type": "boolean" }, "type": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "type": "object" }, "loyalty": { "properties": { "enabled": { "type": "boolean" }, "points_per_dollar": { "type": [ "number", "null" ] }, "redeem_points_per_dollar": { "type": [ "number", "null" ] } }, "type": "object" }, "bundles": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "discount_display": { "type": "string" }, "is_active": { "type": "boolean" }, "variation_count": { "type": "integer" } }, "type": "object" }, "type": "array" }, "mix_match": { "properties": { "note": { "type": "string" }, "rules": { "items": { "properties": { "tag": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" } }, "type": "object" }, "type": "array" }, "tagged_variations": { "items": { "properties": { "variation_id": { "type": "integer" }, "product": { "type": [ "string", "null" ] }, "variation": { "type": "string" }, "price": { "type": "integer" }, "tags": { "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "coupons": { "items": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "number" }, "min_order": { "type": "integer" }, "max_uses": { "type": [ "integer", "null" ] }, "used_count": { "type": "integer" }, "max_uses_per_customer": { "type": "integer" }, "applies_to": { "type": "string" }, "applies_to_ids": { "type": [ "array", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "freebies": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "spend_threshold": { "type": "integer" }, "quantity": { "type": "integer" }, "is_stackable": { "type": "boolean" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "variation": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PushNotificationDiagnosticsRequest": { "properties": { "hours": { "description": "Lookback window for notification history in hours (default 72, max 720)", "type": [ "integer", "null" ] }, "limit": { "description": "Max recent notifications to return (default 50, max 200)", "type": [ "integer", "null" ] } }, "type": "object" }, "PushNotificationDiagnosticsResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "is_active": { "type": "boolean" } }, "type": "object" }, "vendor_user": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "firebase_config": { "properties": { "configured": { "type": "boolean" }, "credentials_source": { "type": "string" }, "project_id": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "type": "object" }, "token_health": { "anyOf": [ { "properties": { "has_token": { "type": "boolean" }, "is_fresh": { "type": "boolean" }, "token_preview": { "type": [ "string", "null" ] }, "token_updated_at": { "type": [ "string", "null" ] }, "token_age_days": { "type": [ "integer", "null" ] }, "freshness_threshold_days": { "type": "integer" }, "status": { "type": "string" }, "status_detail": { "type": "string" } }, "type": "object" } ] }, "notification_settings": { "properties": { "notify_new_order_push": { "type": "boolean" }, "notify_new_order_email": { "type": "boolean" }, "notify_low_stock": { "type": "boolean" }, "notify_restock_request": { "type": "boolean" }, "note": { "type": "string" } }, "type": "object" }, "recent_notifications": { "properties": { "lookback_hours": { "type": "integer" }, "total": { "type": "integer" }, "push_sent_count": { "type": "integer" }, "email_sent_count": { "type": "integer" }, "neither_sent_count": { "type": "integer" }, "push_rate_pct": { "type": [ "number", "null" ] }, "by_type": { "type": "object" }, "entries": { "items": { "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "push_sent": { "type": "boolean" }, "email_sent": { "type": "boolean" }, "is_read": { "type": "boolean" }, "read_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "diagnosis": { "properties": { "overall_status": { "type": "string" }, "blockers": { "items": { "type": "string" }, "type": "array" }, "warnings": { "items": { "type": "string" }, "type": "array" }, "summary": { "type": "string" } }, "type": "object" } }, "type": "object" }, "SearchConsoleRequest": { "properties": { "report": { "description": "The report type to run", "enum": [ "overview", "top_queries", "top_pages", "daily_trend" ], "type": "string" }, "days": { "description": "Number of days to look back (default 30, max 365)", "type": [ "integer", "null" ] } }, "type": "object", "required": [ "report" ] }, "SearchConsoleResponse": { "properties": { "scope": { "type": "string" }, "site_url": { "type": [ "string", "null" ] }, "report": { "type": "string" }, "days": { "type": "integer" }, "results": { "anyOf": [ { "properties": { "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" } }, "type": "object" }, { "items": { "properties": { "query": { "type": "string" }, "page": { "type": "string" }, "date": { "type": "string" }, "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" } }, "type": "object" }, "type": "array" } ] } }, "type": "object" }, "StoreInfoRequest": { "type": "object", "properties": [] }, "StoreInfoResponse": { "properties": { "store": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "country": { "type": "string" }, "on_trial": { "type": "boolean" }, "has_active_subscription": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "WidgetManageRequest": { "properties": { "action": { "description": "\"list\" (default), \"create\", \"update\", or \"delete\".", "type": [ "string", "null" ] }, "widget_id": { "description": "ID of an existing widget. Required for update and delete.", "type": [ "integer", "null" ] }, "title": { "description": "Widget headline. Required when creating.", "type": [ "string", "null" ] }, "subtitle": { "description": "Widget sub-label shown under the headline.", "type": [ "string", "null" ] }, "cta_text": { "description": "Call-to-action button text (e.g. \"Shop Now\").", "type": [ "string", "null" ] }, "link_type": { "description": "\"product\", \"category\", \"mix_match\", or \"featured\". See LINK_TYPE in the tool description.", "type": [ "string", "null" ] }, "product_id": { "description": "Target product id when link_type=product.", "type": [ "integer", "null" ] }, "category_id": { "description": "Target category id when link_type=category.", "type": [ "integer", "null" ] }, "mix_match_tag": { "description": "Target mix & match tag when link_type=mix_match.", "type": [ "string", "null" ] }, "sort_order": { "description": "Display order (lower sorts first).", "type": [ "integer", "null" ] }, "is_active": { "description": "Whether the widget is visible on the storefront.", "type": [ "boolean", "null" ] }, "media_id": { "description": "Media library asset id to set as image_path (the branded, customer-facing image).", "type": [ "integer", "null" ] }, "base_media_id": { "description": "Media library asset id to set as base_image_path (the unbranded source canvas).", "type": [ "integer", "null" ] }, "confirm": { "description": "Required (true) for action=delete.", "type": [ "boolean", "null" ] } }, "type": "object" }, "WidgetManageResponse": { "properties": { "action": { "type": "string" }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "total": { "type": [ "integer", "null" ] }, "widgets": { "items": { "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "subtitle": { "type": [ "string", "null" ] }, "cta_text": { "type": [ "string", "null" ] }, "link_type": { "type": [ "string", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] } }, "type": "object" }, "type": [ "array", "null" ] }, "widget": { "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "subtitle": { "type": [ "string", "null" ] }, "cta_text": { "type": [ "string", "null" ] }, "link_type": { "type": [ "string", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "ZoneDiagnosticsRequest": { "properties": { "customer_address_id": { "description": "Saved customer address id to inspect (optional)", "type": [ "integer", "null" ] }, "order_number": { "description": "Order number whose delivery address should be checked (optional)", "type": [ "string", "null" ] }, "zone_id": { "description": "Specific zone to compare against (optional)", "type": [ "integer", "null" ] }, "latitude": { "description": "Manual latitude to test (optional)", "type": [ "number", "null" ] }, "longitude": { "description": "Manual longitude to test (optional)", "type": [ "number", "null" ] } }, "type": "object" }, "ZoneDiagnosticsResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "source": { "anyOf": [ { "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "address": { "type": "string" } }, "type": "object" }, { "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "order_number": { "type": "string" }, "delivery_address": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "address_coordinates": { "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "type": "object" }, "saved_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "inside": { "type": [ "boolean", "null" ] } }, "type": [ "object", "null" ] }, "detected_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "priority": { "type": "integer" } }, "type": [ "object", "null" ] }, "zones": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "priority": { "type": "integer" }, "delivery_fee": { "type": "integer" }, "service_fee": { "type": "integer" }, "min_order": { "type": "integer" }, "color": { "type": "string" }, "inside": { "type": "boolean" }, "polygon_points": { "type": "integer" }, "polygon": { "type": [ "array", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "paths": { "/api/v1/tools/analytics_query": { "post": { "operationId": "analytics_query", "summary": "Run read-only analytics queries against the production database. Available reports: revenue_by_tenant, orders_by_status, top_products, revenue_over_time, customer_stats.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsQueryRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/AnalyticsQueryResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/bundle_list": { "post": { "operationId": "bundle_list", "summary": "List a tenant's bundle deals (\"mix & match\" — e.g. \"buy 4 for $77\") with id, name, trigger\nquantity, discount type/value, active state, schedule window, and attached variation count.\nBundles are the live cart engine (MixMatchService): a bundle fires when a cart holds at least\n`quantity` units across its attached variations. Always call this before bundle_upsert to get\nthe bundle id and confirm the current discount configuration.\n\nIMPORTANT: this reads the `bundles` table — the source of truth the storefront cart uses. It is\nNOT the legacy `mix_match_rules` tenant setting that promotion_audit / product_inspect surface;\nthose are stale display-only data. Trust this tool for what actually applies at checkout.\n\ndiscount_type:\n percent → discount_value is a percentage 0–100, applied per unit.\n fixed → discount_value is dollars off PER UNIT.\n fixed_total → discount_value is the dollar TOTAL for the whole set (\"$77 for 4\").", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/BundleListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/bundle_upsert": { "post": { "operationId": "bundle_upsert", "summary": "Create or update a bundle deal (mix & match) on behalf of a tenant. Bundles are the live cart\nengine: a bundle fires when a cart holds at least `quantity` units across its attached variations.\n\nUPDATE MODE (bundle_id provided):\n Edits the bundle. Only the fields you pass are changed; omitted fields are left as-is.\n\nCREATE MODE (no bundle_id):\n Creates a new bundle. name, quantity, discount_type, and discount_value are required.\n\nDISCOUNT VALUE UNITS — read carefully, this is the common mistake:\n discount_type = \"percent\" → discount_value is a percentage 0–100 (e.g. 20 = 20% off each unit).\n discount_type = \"fixed\" → discount_value is DOLLARS off PER UNIT (e.g. 5 = $5 off each).\n discount_type = \"fixed_total\" → discount_value is the DOLLARS TOTAL for the whole set\n (e.g. quantity=4, discount_value=77 → \"any 4 for $77\").\n For fixed and fixed_total, pass dollars (e.g. 77 or 77.00) — the tool stores cents internally.\n For percent, pass the percentage (e.g. 20), NOT a fraction.\n\nVARIATIONS:\n variation_ids + variation_mode control which product variations the bundle applies to.\n mode \"replace\" (default) sets membership to exactly variation_ids; \"add\" attaches them to the\n existing set; \"detach\" removes them. Variations not owned by the tenant are ignored.\n Omit variation_ids entirely to leave membership untouched.\n\nSCHEDULE:\n starts_at / ends_at are interpreted in the tenant's timezone and stored as UTC. Pass null/omit\n for an always-on bundle.\n\nAlways call bundle_list first to get the bundle_id and confirm the current configuration.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/BundleUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_apply_template": { "post": { "operationId": "campaign_apply_template", "summary": "Apply a built-in system email template to a DRAFT campaign, replacing its html_body with the\nrendered, tenant-branded design. This mirrors the \"Choose template\" action in the vendor admin.\n\nThe template is rendered with the tenant's own branding (theme colour, logo, name, address, phone),\nthen sanitized and written to the campaign's html_body. The {{unsubscribe_url}} token is preserved.\nThe design ships with placeholder copy ([Product name], $00, \"Your headline here\", etc.) — after\napplying, use campaign_upsert to set the real html_body with this tenant's products, prices, and\noffers, or hand off to the vendor to fill in.\n\nOnly DRAFT campaigns can have a template applied. To discover valid template_id values, omit\ntemplate_id (or pass an unknown one) and the tool returns the list of available templates.\n\nTypical flow: campaign_upsert (create draft) → campaign_apply_template (lay down the design) →\ncampaign_upsert (replace html_body with real data) → campaign_send_test (preview).", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignApplyTemplateRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignApplyTemplateResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_control": { "post": { "operationId": "campaign_control", "summary": "Pause or resume a vendor email/SMS campaign.\n\npause: sets status=paused with paused_reason=manual. Pending recipients stay\npending; the dispatcher skips this campaign so sibling sending campaigns can\nuse the shared per-tenant webhook/SMTP throttle.\n\nresume: sets status=sending, clears paused_reason and webhook_consecutive_failures.\n\ndry_run defaults TRUE. Always confirm tenant_slug and campaign_id first.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignControlRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignControlResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_recipients_requeue": { "post": { "operationId": "campaign_recipients_requeue", "summary": "Unstick a vendor email/SMS campaign that auto-paused or stalled mid-send.\n\nResets failed recipients (and optionally stale \"sending\" rows) back to pending,\nclears webhook_consecutive_failures / paused_reason / last_error, and sets the\ncampaign status to sending so the dispatcher continues. Already-sent recipients\nare never touched.\n\nPass retry_sending_log_errors=true to retry every recipient that appears in the\ncampaign sending log with a retryable error (502/timeout/SMTP soft fail, etc.).\nThose jobs dispatch immediately (up to dispatch_limit) so they are not stuck\nbehind a large pending queue. The log rows stay — they are diagnostic history.\n\nUse when a webhook campaign froze after consecutive endpoint errors (or soft\nSMTP failures that were misclassified before the soft-fail fix) and pending\n+ failed recipients remain.\n\ndry_run defaults to TRUE — first call reports counts only. Pass dry_run=false\nto apply. Always confirm tenant_slug with tenant_list and campaign_id with the vendor.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRecipientsRequeueRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignRecipientsRequeueResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_send_test": { "post": { "operationId": "campaign_send_test", "summary": "Send a single test copy of a campaign so the design and copy can be reviewed before the real send.\n\nEmail campaigns go out through the tenant's own SMTP settings — exactly the path a real send uses.\nPass to_email. Requires complete SMTP settings.\n\nText (SMS) campaigns go out through the tenant's connected Twilio account. Pass to_phone instead of\nto_email. Requires Twilio to be connected.\n\nThis is a preview only: it does NOT start the campaign, does NOT touch the audience, and does NOT\nrecord any send/open/click stats. Personalization tokens render with sample values; unsubscribe links\npoint at harmless test URLs.\n\nWorks on a campaign in any status (a draft preview is the common case). Always confirm the\ncampaign_id with the vendor first.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSendTestRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignSendTestResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_set_image": { "post": { "operationId": "campaign_set_image", "summary": "Drop an image from the tenant's media library into a DRAFT campaign — no link copying, no manual\nHTML. Give it a campaign_id and a media_id (from the tenant's own library) and it fills an image\nplaceholder in the campaign body with that image, using the library image's own public URL and\nalt text. The URL is on the tenant's public disk, so it passes the campaign HTML sanitizer\nuntouched and renders in email clients.\n\nWHICH SLOT IT FILLS:\n System templates render image placeholders labelled \"Add image\". By default this tool fills the\n FIRST remaining placeholder. Pass slot_index (1-based) to target a specific placeholder when a\n template has more than one. If the body has no placeholder left, the image is appended at the end.\n\nREQUIREMENTS:\n - The campaign must be a DRAFT and belong to the tenant.\n - The media asset must belong to the tenant and be public (private assets have no shareable URL).\n\nTypical flow: campaign_upsert (create) → campaign_apply_template (design with placeholders) →\ncampaign_set_image (fill each placeholder) → campaign_upsert (real copy) → campaign_send_test.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSetImageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignSetImageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_upsert": { "post": { "operationId": "campaign_upsert", "summary": "Create or edit a vendor email campaign on behalf of a tenant. This is the vendor → their-customers\ncampaign universe (NOT the platform drip-to-leads system). Completed campaigns cannot be edited.\n\nCREATE MODE (no campaign_id):\n Creates a new draft. For email campaigns, `name` and `subject` are required; `html_body` is optional\n on create — omit it to start blank and apply a system template afterwards with campaign_apply_template.\n For text (SMS) campaigns, set channel to \"sms\" and pass `sms_body` (name required). Twilio must be\n connected on the tenant.\n\nUPDATE MODE (campaign_id provided):\n Edits an existing campaign. Only the fields you pass are changed; omitted fields are left as-is.\n Drafts accept all fields. Sending or paused campaigns accept content fields only — for email that is\n name, subject, html_body, plain_body; for text that is name and sms_body. Sending campaigns keep\n running and unreached recipients get the latest version. Scheduled, cancelled, and failed campaigns\n must be edited from the vendor admin.\n\nHTML BODY (email only):\n Pass the full email HTML in `html_body`. It is sanitized exactly like the vendor admin editor:\n a full document ( / ) keeps its table-based structure; a fragment is run\n through the stricter inline allowlist. Use the literal token {{unsubscribe_url}} where the\n unsubscribe link should appear — it is replaced per-recipient at send time and a List-Unsubscribe\n header is added automatically. Personalization tokens {{first_name}} and {{last_name}} are also\n replaced at send time.\n\nSMS BODY (text only):\n Pass the message in `sms_body` (max 1600 chars). Tokens {{first_name}} and {{last_name}} are\n replaced at send time. Text campaigns only target opted-in shop customers.\n\nAUDIENCE / MODE (email only):\n mode is \"smtp\" (default) or \"webhook\". audience_includes_customers (default true) targets the\n tenant's own customers. This tool does not send anything — use campaign_send_test to preview,\n then the vendor sends from the admin.\n\nAlways confirm the tenant_slug with tenant_list first. To populate a draft from a built-in design,\ncreate it here, then call campaign_apply_template.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/catalog_collapse": { "post": { "operationId": "catalog_collapse", "summary": "Merges a group of size-split products into ONE product with size options.\n\nTurns \"Blue Dream - 3.5G\", \"Blue Dream - 7G\", \"Blue Dream - 28G\" (three separate products,\neach with one \"Default\" option) into a single \"Blue Dream\" product that sells by weight with\n3.5g / 7g / 28g options. Stock is added together into one shared pool, and each old price\nbecomes the price of its size.\n\nRun catalog_flattening_audit first to see the groups and their exact base_name.\n\nSAFETY:\n- dry_run defaults to TRUE. Nothing changes until you pass dry_run=false. The dry run returns\n the exact sizes, prices, stock, and which products would be removed.\n- Past orders are never affected — they keep the product name and price the customer saw.\n- Refused when two products in the group claim the same size, or when any product belongs to\n another store.\n- This removes the duplicate products. It cannot be undone from here.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogCollapseRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CatalogCollapseResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/catalog_flattening_audit": { "post": { "operationId": "catalog_flattening_audit", "summary": "Read-only. Finds products whose sizes were split into separate products instead of tiers.\n\nThis happens when a catalog is imported from a store that put the size in the product NAME\n(\"Blue Dream - 3.5G\", \"Blue Dream - 7G\") instead of a size option column. The importer has no\nsize column to read, so each size becomes its own product with a single \"Default\" option, and\nthe store ends up with a long flat menu that cannot use weight pricing or mix & match deals.\n\nReturns each group of products that belong together (\"family\"), the sizes and prices found,\nand whether the group can be safely merged. A group is NOT mergeable when two of its products\nclaim the same size — that must be resolved by hand first.\n\nNothing is changed. Use catalog_collapse to merge a group.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogFlatteningAuditRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CatalogFlatteningAuditResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/category_manage": { "post": { "operationId": "category_manage", "summary": "List, create, update, or delete a tenant's storefront categories.\n\nACTIONS:\n list (default): return every category with id, name, slug, parent, sort_order,\n is_active, is_featured, and image_url. Always call this first to find a\n category_id before update/delete, and to check for slug collisions before create.\n create: requires name (slug is auto-generated from name if omitted).\n update: requires category_id. Only the fields you pass are changed.\n delete: requires category_id and confirm=true. Refuses if the category still has\n products or children attached (detach or reassign them first).\n\nIMAGES: pass media_id (from media_list / media_upload) to set image_path (the final,\ncustomer-facing image) or base_image_path (the unbranded source canvas SwagImagesService\ncomposites branding onto). Omit both to leave images untouched.\n\nAlways call action=list first to confirm category_id / slug before update or delete.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryManageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CategoryManageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_addresses": { "post": { "operationId": "customer_addresses", "summary": "Return a customer's saved addresses, coordinates, saved zones, and zone mismatch diagnostics.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressesRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerAddressesResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_list": { "post": { "operationId": "customer_list", "summary": "Page through all customers for a tenant, optionally filtered to those updated since a given time. Built for bulk sync — use customer_lookup instead for a single targeted search.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_lookup": { "post": { "operationId": "customer_lookup", "summary": "Find customers by id, email, phone, or name and return their recent addresses, orders, and support context.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLookupRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerLookupResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_update": { "post": { "operationId": "customer_update", "summary": "Update a customer's contact fields (name, email, phone) and/or suppress marketing consent (email_opt_out, sms_marketing_opt_out, sms_notifications_muted — one-way, cannot un-suppress). Verification, loyalty, and other DabDash-owned fields cannot be set here.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerUpdateResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/google_analytics": { "post": { "operationId": "google_analytics", "summary": "Query Google Analytics (GA4) data for the platform (dabdash.com) or a specific tenant with a connected GA integration. Returns traffic overview, top pages, traffic sources, top events, and daily trend.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAnalyticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/GoogleAnalyticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/inventory_audit_lookup": { "post": { "operationId": "inventory_audit_lookup", "summary": "Look up the historical inventory state of a list of products from the inventory_audit_logs table.\n\nFor each product, returns every variation_id ever logged in the audit trail (including variations\nthat have since been deleted), the variation's last known stock_quantity strictly BEFORE the given\ncutoff timestamp, and that variation's most recent action+notes for context.\n\nUse this tool to recover pre-incident stock values when variations have been overwritten or\ndeleted by a destructive operation (e.g. an erroneous pricing structure assignment that wiped\nunit/simple variations and replaced them with weight tiers).\n\nOutput is grouped per product. Each product also includes its CURRENT variations and their stock\nfor comparison so you can see the delta.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryAuditLookupRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/InventoryAuditLookupResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/inventory_status": { "post": { "operationId": "inventory_status", "summary": "Get inventory status across all tenants or a specific tenant. Shows low stock alerts and out-of-stock products.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryStatusRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/InventoryStatusResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/mailbox_inspect": { "post": { "operationId": "mailbox_inspect", "summary": "Inspect a tenant inbound mailbox: sync watermark, last error, recent ingestion counts (inbound/outbound), and a healthy/bootstrap/stalled/quiet verdict. Pass a tenant_slug, or pass platform=true for a platform-owned mailbox (tenant_id IS NULL).", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxInspectRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MailboxInspectResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/media_compose": { "post": { "operationId": "media_compose", "summary": "Build a finished campaign image ON THE SERVER: take a base picture, drop the vendor's logo on\ntop, add a headline and subtitle, and save the result straight into the tenant's media library.\nReturns a media_id + public URL ready for campaign_set_image. Nothing has to be uploaded from\nyour machine — pass IDs and URLs and the server does the artwork.\n\nPROVIDE THE BASE (exactly one):\n - base_media_id — an image already in the tenant's library (see media_list).\n - base_url — a public https image URL, e.g. the output of an image-generation tool.\n\nPROVIDE THE LOGO (optional, at most one):\n - logo_media_id / logo_url — same two options as the base.\n THE LOGO IS NEVER ALTERED. It is scaled to fit (aspect ratio locked) and placed as-is —\n its colours, strokes and transparency are left exactly as supplied. For legibility on busy\n artwork use the `scrim` option, which darkens the area BEHIND the logo and text.\n\nLAYOUT: logo on top, headline under it, subtitle under that — the block is centred\nhorizontally and positioned with logo_position (top / center / bottom). Sizes are given as a\nfraction of the base image width so they scale with any canvas. Long text is word-wrapped\nautomatically; the response's `wrapped` flag tells you when that happened so you can shorten it.\n\nCONSTRAINTS: sources max 5 MB, JPEG/PNG/WebP/GIF, max 8000x8000. The finished image goes\nthrough the same pipeline as media_upload — re-encoded to WebP, resized to fit, de-duplicated\nby content — so identical inputs return the existing media_id instead of a duplicate.\n\nTypical flow: (generate or pick a base image) -> media_compose -> campaign_set_image.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaComposeRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MediaComposeResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/media_list": { "post": { "operationId": "media_list", "summary": "List the images in a tenant's media library — id, public URL, dimensions, filename, folder, and alt\ntext. Use this to find the media_id of an image to place into a campaign with campaign_set_image,\ninstead of guessing. Returns newest first.\n\nFilter with `folder` (exact match) or `search` (filename substring). `visibility` defaults to\n\"public\" (the emailable assets); pass \"all\" or \"private\" to widen. Confirm the tenant_slug with\ntenant_list first.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MediaListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/media_upload": { "post": { "operationId": "media_upload", "summary": "Upload an image into a tenant's media library (the same library the vendor admin uses). The image\nis ingested through the platform's shared media pipeline — re-encoded to WebP, resized to fit, EXIF-\noriented, content-addressed for dedup — and a media_assets row is created. It ALWAYS lands in the\nlibrary, and the tool returns the new media_id and public URL you can then place into a campaign\nwith campaign_set_image.\n\nPROVIDE THE IMAGE ONE OF THREE WAYS (exactly one):\n - source_url — fetch the image from a public http(s) URL.\n - source_path — read a local file path on the server/agent host.\n - source_base64 — raw base64 of the image bytes (no data: prefix needed; a data: prefix is stripped).\n\nCONSTRAINTS: max 5 MB; JPEG, PNG, WebP, or GIF. Identical bytes already in the library are de-duped\n(you get the existing media_id back). Uploads default to public visibility so the image is emailable.\n\nOptional alt_text and folder help organise and caption the asset. Confirm the tenant_slug with\ntenant_list first. To see what's already in the library, use media_list.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MediaUploadResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/metrc_diagnostics": { "post": { "operationId": "metrc_diagnostics", "summary": "Returns a JSON summary of Metrc compliance status for a tenant: integration mode, sync states, audit log counts by HTTP status, and pending/failed report counts. Pass a tenant_slug to inspect a specific tenant.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetrcDiagnosticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MetrcDiagnosticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/order_dashboard": { "post": { "operationId": "order_dashboard", "summary": "Query orders across all tenants. Filter by status, order number, customer clues, date range, amount, or tenant. Returns order list with pricing context.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDashboardRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/OrderDashboardResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_assign": { "post": { "operationId": "pricing_structure_assign", "summary": "Assign a shared bundle pricing structure to one or more products. Re-syncs variations for each\nreassigned product. Automatically deletes orphaned inline (hidden) structures when replacing them.\n\nSAFETY RULES enforced by this tool:\n- The target structure_id must be a BUNDLE (is_hidden=false). Inline structures cannot be assigned\n to products this way — that would violate the 1:1 contract.\n- If a product's current structure is inline (hidden) and this product is its only consumer\n (product_count == 1), the old inline structure is deleted automatically.\n- If a product's current structure is inline but product_count > 1, assignment is refused for that\n product with an explanation — this is a data anomaly that needs manual resolution.\n- Each product result includes a status: assigned | skipped (already on this structure) | refused.\n\nUse pricing_structure_list to get valid structure IDs before calling this tool.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureAssignRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureAssignResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_delete": { "post": { "operationId": "pricing_structure_delete", "summary": "Delete one or more pricing structures by ID.\n\nSAFETY RULES enforced by this tool:\n- BUNDLE structures (is_hidden=false): always deletable unless products are still assigned.\n Pass force=true to delete even when products are assigned (use only after migrating them).\n- INLINE structures (is_hidden=true): only deletable when product_count=0 (orphaned).\n Inline structures with products attached cannot be deleted — use pricing_structure_assign\n to move the product to a bundle first, which auto-cleans the inline structure.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureDeleteRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureDeleteResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_list": { "post": { "operationId": "pricing_structure_list", "summary": "List all pricing structures for a tenant with their kind (inline|bundle), product count, tracking type,\nand tier summary. Always call this before pricing_structure_upsert or pricing_structure_assign to get\nstructure IDs and confirm which structures are bundles vs inline (1:1 product) structures.\n\nkind=inline → hidden 1:1 structure tied to exactly one product (is_hidden=true)\nkind=bundle → shared structure visible on /admin/pricing, used by 0 or more products (is_hidden=false)", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_restore": { "post": { "operationId": "pricing_structure_restore", "summary": "Surgical restore tool. Rebuilds a single product's pricing structure and variations EXACTLY to a\nspecified state. Bypasses the standard syncVariationsForProduct routine — you control every field.\n\nUse this AFTER inventory_audit_lookup has revealed the pre-incident state of variations whose\nnames/prices/stock were destroyed by an erroneous bundle reassignment.\n\nBehaviour:\n- Creates a NEW inline (hidden, 1:1) pricing structure with the given tracking_type, tier\n definitions, and a name like \"Product: (Hidden)\". Old structure linkage is\n replaced. The previous structure is NOT deleted by this tool.\n- For each tier in the spec, finds-or-creates a variation. Matching is by `restore_variation_id`\n if provided, else by name. If found, the variation is updated in place (preserving its id and\n its audit-log history). If not found, a new variation is created.\n- Stock_quantity is set EXACTLY to the value specified — this is the whole point of the tool.\n- Sets product.tracking_type, product.inventory_mode, product.base_unit per the new structure.\n- Variations on the product not referenced by any tier in the spec are DEACTIVATED (is_active=false)\n so they stop being shown but their audit history is retained. Pass `delete_unreferenced=true` to\n hard-delete them instead.\n\nSAFETY:\n- Wrap each call in its own transaction.\n- Will refuse if the new tracking_type is incompatible with stored cost data.\n- Inline-only by design — bundles are not recreated by this tool. Use pricing_structure_assign\n to put the product on a bundle if that's what you want.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureRestoreRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureRestoreResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_upsert": { "post": { "operationId": "pricing_structure_upsert", "summary": "Create or edit a pricing structure's tiers, name, and tracking type. Operates in three modes:\n\nBUNDLE MODE (structure_id provided, structure is not hidden):\n Edit a shared bundle structure visible on /admin/pricing. Tiers are replaced and ALL products\n linked to the bundle are re-synced. Returns how many products were affected as a warning.\n\nINLINE MODE (product_slug or product_id provided, no structure_id):\n Edit the hidden 1:1 pricing structure for a single product. Tiers are replaced and variations\n are re-synced for that product only. Refuses if the product currently uses a bundle structure —\n use pricing_structure_assign to detach from the bundle first.\n\nCREATE BUNDLE MODE (no structure_id, no product_slug/product_id):\n Create a new shared bundle structure. Does not link it to any products.\n\nSAFETY RULES enforced by this tool:\n- Never accepts structure_id pointing to a hidden (inline) structure — always go via product_slug/product_id.\n- Tiers for weight/matrix types must have weight_grams > 0.\n- Tiers for simple type: only the first tier is used; name and weight_grams are normalised.\n- Prices are accepted as dollar amounts (e.g. 12.99) and converted to cents internally.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_inspect": { "post": { "operationId": "product_inspect", "summary": "Inspect a specific product including every variation's price, compare_at_price, mix_match_tags, stock, and the tenant's mix & match rule settings. Use this to audit pricing, sale state, and bundle configuration for support tickets.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInspectRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductInspectResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_update_by_sku": { "post": { "operationId": "product_update_by_sku", "summary": "Update a simple product's stock quantity and/or price by SKU — the inventory-sync path for an external POS. v1 scope: SIMPLE products only (single implicit unit, no weight/variant tiers). Every other pricing type (weight, unit, matrix, matrix_unit) is rejected with a clear message; those need per-tier/per-variant targeting that a flat SKU+quantity+price payload cannot express safely. Always call product_inspect with sku first to confirm which product/type you are targeting.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdateBySkuRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductUpdateBySkuResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/promotion_audit": { "post": { "operationId": "promotion_audit", "summary": "Inspect coupons, freebies, mix and match rules, loyalty settings, and storewide sale state for overcharge or missed-discount support tickets.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionAuditRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PromotionAuditResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/push_notification_diagnostics": { "post": { "operationId": "push_notification_diagnostics", "summary": "Diagnose push notification (FCM) delivery for a vendor. Surfaces token health, notification settings, recent send history with push/email flags, and a plain-language diagnosis of why pushes are or are not being delivered.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushNotificationDiagnosticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PushNotificationDiagnosticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/search_console": { "post": { "operationId": "search_console", "summary": "Query Google Search Console data for the platform (dabdash.com) or a specific tenant with a connected GSC integration. Returns search overview, top queries, top pages, and daily trend.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchConsoleRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/SearchConsoleResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/store_info": { "post": { "operationId": "store_info", "summary": "Identify the connected store — name, slug, timezone, currency, country, and subscription status. Use to validate an API token during setup.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreInfoRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/StoreInfoResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/widget_manage": { "post": { "operationId": "widget_manage", "summary": "List, create, update, or delete a tenant's homepage marketing widgets (the hero slider cards\nlinking to a product, category, featured products, or a mix & match tag).\n\nACTIONS:\n list (default): return every widget with id, title, subtitle, link_type, target, sort_order,\n is_active, and image_url. Always call this first to find a widget_id.\n create: requires title. link_type + its matching id/tag is optional but recommended so the\n widget's CTA actually goes somewhere (see LINK_TYPE below). Defaults to \"featured\"\n (no target) when omitted.\n update: requires widget_id. Only the fields you pass are changed.\n delete: requires widget_id and confirm=true.\n\nLINK_TYPE — pairs with exactly one target field:\n \"product\" → product_id\n \"category\" → category_id\n \"mix_match\" → mix_match_tag\n \"featured\" → no target needed (links to the featured-products listing)\n\nIMAGES: pass media_id (from media_list / media_upload) to set image_path (the final,\ncustomer-facing image) or base_image_path (the unbranded source canvas SwagImagesService\ncomposites the headline/logo overlay onto). Omit both to leave images untouched.\n\nAlways call action=list first to confirm widget_id before update or delete.", "tags": [ "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetManageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/WidgetManageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/zone_diagnostics": { "post": { "operationId": "zone_diagnostics", "summary": "Inspect zone polygons against customer or order coordinates to explain why an address is inside or outside delivery coverage.", "tags": [ "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneDiagnosticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ZoneDiagnosticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } } } }