{"openapi":"3.1.0","info":{"title":"Apex A/B Testing API","version":"1.0.0","description":"API for managing A/B testing experiments, variations, goals, webhooks, and screenshots."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"headers":{"ApexApiVersion":{"description":"Apex public API contract version served by this response.","schema":{"type":"string","example":"1"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Shop API key (`apx_sk_...`), user API key (`apx_uk_...`) on user-key routes, or server tracking-source key (`apx_src_...`) on the Worker assignment route."}},"responses":{"BadRequest":{"description":"The request body, query string, or path parameter is invalid.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, malformed, expired, revoked, or unknown API key.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is valid but does not include the required scope.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested resource was not found in the API key's shop scope.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PageLiveImpactConflict":{"description":"The Page write reaches live consumers and has not been acknowledged for the current set. Repeat the request with confirm_live_impact and confirmed_consumer_ids carrying every id listed here.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageLiveImpactError"}}}},"Conflict":{"description":"The request conflicts with the current resource state.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request is valid JSON but violates a resource constraint.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DatabaseBusy":{"description":"The database is briefly overloaded (error code `database_busy`). Retry after the number of seconds in the Retry-After header.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying the request."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimitExceeded":{"description":"Per-key rate limit exceeded. Retry after the reset time.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Configured request limit for the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp when the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"BacklogExperimentLink":{"type":"object","required":["id","backlog_item_id","experiment_id","shop_id","link_type"],"properties":{"id":{"type":"string","format":"uuid"},"backlog_item_id":{"type":"string","format":"uuid"},"experiment_id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"link_type":{"type":"string","enum":["primary","follow_up"]},"created_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"IdeaLinkResponse":{"type":"object","required":["link"],"properties":{"link":{"$ref":"#/components/schemas/BacklogExperimentLink"}}},"IdeaDetachResponse":{"type":"object","required":["detached","backlog_item_id"],"properties":{"detached":{"type":"boolean","enum":[true]},"backlog_item_id":{"type":"string","format":"uuid"}}},"AnalyticsStatsRow":{"type":"object","required":["date","visitors","conversions","revenue"],"properties":{"date":{"type":"string"},"visitors":{"type":"number"},"conversions":{"type":"number"},"revenue":{"type":"number"},"foreign_revenue_buckets":{"type":["array","null"],"items":{"type":"string"}},"converted_revenue":{"type":["number","null"]},"excluded_foreign_revenue":{"type":["number","null"]},"unconverted_revenue":{"type":["number","null"]},"unknown_currency_orders":{"type":["number","null"]},"unknown_currency_revenue":{"type":["number","null"]}}},"AnalyticsStatsResponse":{"type":"object","required":["data","timezone"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsStatsRow"}},"timezone":{"type":"string","example":"Europe/Berlin","description":"The normalized IANA timezone used for the returned calendar dates."},"coverage":{"type":"object","required":["mixed_populations","reasons"],"properties":{"mixed_populations":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string","enum":["consent_gated_sdk","low_order_stitch_rate"]}}}}}},"AnalyticsDataResponse":{"type":"object","required":["data"],"properties":{"data":{"type":["array","object"]}}},"Asset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"file_name":{"type":"string"},"mime_type":{"type":"string"},"size_bytes":{"type":"integer"},"public_url":{"type":["string","null"]},"url_error":{"type":"string","description":"Present when a temporary signed asset URL could not be created."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"},"archived_by":{"type":["string","null"]}},"required":["id","name","file_name","mime_type","size_bytes","created_at","updated_at"]},"LandingPageVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"landing_page_id":{"type":"string","format":"uuid"},"version_number":{"type":"integer"},"spec":{"type":"object"},"brief_id":{"type":["string","null"],"format":"uuid"},"brief_snapshot":{"type":"object"},"gate_report":{"type":"object"},"claims":{"type":"array"},"seo_manifest":{"type":"object"},"render_manifest":{"type":"object"},"r2_prefix":{"type":["string","null"]},"html_key":{"type":["string","null"]},"created_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"}},"required":["id","landing_page_id","version_number","spec","created_at"]},"LandingPagePublish":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"landing_page_id":{"type":"string","format":"uuid"},"version_id":{"type":"string","format":"uuid"},"url":{"type":"string"},"host":{"type":"string"},"path":{"type":"string"},"status":{"type":"string"},"published_by":{"type":["string","null"],"format":"uuid"},"published_at":{"type":"string","format":"date-time"},"error":{"type":["string","null"]}},"required":["id","landing_page_id","version_id","url","host","path","status","published_at"]},"LandingPageQaRun":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"landing_page_id":{"type":"string","format":"uuid"},"version_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"viewports":{"type":"array"},"screenshots":{"type":"object"},"findings":{"type":"array"},"approved_by":{"type":["string","null"],"format":"uuid"},"approved_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","landing_page_id","version_id","status","created_at","updated_at"]},"LandingPageContentBrief":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"landing_page_id":{"type":["string","null"],"format":"uuid"},"source":{"type":"string"},"status":{"type":"string"},"format":{"type":"string"},"angle":{"type":"string"},"audience":{"type":["string","null"]},"traffic_source":{"type":["string","null"]},"keyword_intent":{"type":["string","null"]},"offer_refs":{"type":"array"},"product_refs":{"type":"array"},"objections":{"type":"array"},"proof_points":{"type":"array"},"outline":{"type":"array"},"created_at":{"type":"string","format":"date-time"}},"required":["id","shop_id","source","status","format","angle"]},"LandingPage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"page_type":{"type":"string"},"status":{"type":"string"},"publish_mode":{"type":"string"},"publish_host":{"type":["string","null"]},"publish_path":{"type":["string","null"]},"current_version_id":{"type":["string","null"],"format":"uuid"},"published_version_id":{"type":["string","null"],"format":"uuid"},"created_by":{"type":["string","null"],"format":"uuid"},"current_version":{"oneOf":[{"$ref":"#/components/schemas/LandingPageVersion"},{"type":"null"}]},"published_version":{"oneOf":[{"$ref":"#/components/schemas/LandingPageVersion"},{"type":"null"}]},"versions":{"type":"array","description":"Latest versions, newest first (up to 10).","items":{"$ref":"#/components/schemas/LandingPageVersion"}},"publishes":{"type":"array","description":"Latest publishes, newest first (up to 3).","items":{"$ref":"#/components/schemas/LandingPagePublish"}},"qa_runs":{"type":"array","description":"Latest QA runs, newest first (up to 3), always including the latest approved QA run for the current version when one exists.","items":{"$ref":"#/components/schemas/LandingPageQaRun"}},"content_briefs":{"type":"array","description":"Latest content brief (up to 1).","items":{"$ref":"#/components/schemas/LandingPageContentBrief"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","shop_id","name","slug","page_type","status","publish_mode","publish_host","publish_path","current_version_id","published_version_id","current_version","published_version","versions","publishes","qa_runs","content_briefs","created_at","updated_at"]},"LandingPageSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"page_type":{"type":"string"},"status":{"type":"string"},"publish_mode":{"type":"string"},"publish_host":{"type":["string","null"]},"publish_path":{"type":["string","null"]},"current_version_id":{"type":["string","null"],"format":"uuid"},"published_version_id":{"type":["string","null"],"format":"uuid"},"current_version":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}},"required":["id","created_at"]},{"type":"null"}]},"published_version":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}},"required":["id","created_at"]},{"type":"null"}]},"_count":{"type":"object","properties":{"versions":{"type":"integer"},"publishes":{"type":"integer"},"qa_runs":{"type":"integer"}},"required":["versions","publishes","qa_runs"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","page_type","status","publish_mode","publish_host","publish_path","current_version_id","published_version_id","current_version","published_version","_count","created_at","updated_at"]},"ExternalPixelSnippet":{"type":"object","properties":{"shop_id":{"type":"string","format":"uuid"},"endpoint":{"type":"string","format":"uri"},"provider":{"type":"string"},"handover_param":{"type":"string"},"global_name":{"type":"string"},"snippet":{"type":"string"},"usage":{"type":"object","properties":{"function_name":{"type":"string"},"example":{"type":"string"}},"required":["function_name","example"]}},"required":["shop_id","endpoint","provider","handover_param","global_name","snippet","usage"]},"ShopSummary":{"type":"object","required":["id","name","domain","tier","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string"},"tier":{"type":"string","enum":["self_managed","apex_managed","drip_managed"],"description":"Responses return only self_managed, apex_managed, and drip_managed."},"created_at":{"type":"string","format":"date-time"}}},"Shop":{"type":"object","required":["id","name","domain","origin","currency","tier","operator_enabled","holdout_pct","holdout_v1_enabled","platform","org_id","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string"},"origin":{"type":["string","null"]},"currency":{"type":"string"},"tier":{"type":"string","enum":["self_managed","apex_managed","drip_managed"],"description":"Responses return only self_managed, apex_managed, and drip_managed."},"operator_enabled":{"type":"boolean"},"holdout_pct":{"type":"number","minimum":0,"maximum":10,"default":0},"holdout_v1_enabled":{"type":"boolean","default":false},"platform":{"type":"string"},"org_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}}}},"ServerAssignment":{"type":"object","required":["experiment_id","experiment_name","experiment_type","variation_id","variation_name","variation_index","assignment_epoch","is_control","mutations","redirect_url","css","js"],"properties":{"experiment_id":{"type":"string"},"experiment_name":{"type":["string","null"]},"experiment_type":{"type":"string"},"variation_id":{"type":"string"},"variation_name":{"type":["string","null"]},"variation_index":{"type":"integer"},"assignment_epoch":{"type":["integer","null"]},"is_control":{"type":"boolean"},"archived_at":{"type":["string","null"],"format":"date-time"},"archived_by":{"type":["string","null"]},"mutations":{"type":"array","items":{"type":"object"}},"commerce_price_only":{"type":"boolean"},"redirect_url":{"type":["string","null"]},"css":{"type":["string","null"]},"js":{"type":["string","null"]},"attributable_only":{"type":"boolean","description":"Present and true when the assignment exists only to attribute goals on the current URL. The treatment was not delivered."}}},"AssignGetCustomerIdError":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["customer_id_requires_post"]},"message":{"type":"string","description":"Explains that logged_in_customer_id and customer_id must be sent in a POST JSON body."}}},"ServerAssignmentResponse":{"type":"object","required":["user_id","assignments","commerce_authorization"],"properties":{"user_id":{"type":["string","null"],"description":"The supplied user_id. Null when a gated logged-in assignment uses only a customer id."},"identity_source":{"type":"string","enum":["shopify_customer"],"description":"Present only when the logged-in aggregate-mode gate selected the Shopify customer identity."},"decision_scope":{"type":"string","enum":["aggregate_only"],"description":"Present with identity_source. The assignment cannot support an individual-level decision."},"cohort":{"type":"string","enum":["holdout","active"],"description":"Program cohort for this identity. Present only when global holdout v1 is enabled for the shop and the request is not a forced QA assignment."},"holdout_config_epoch":{"type":"integer","format":"int64","minimum":1,"description":"Unix timestamp in milliseconds of the holdout configuration revision that produced the cohort. Present with cohort when global holdout v1 is enabled for the shop and the request is not a forced QA assignment."},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/ServerAssignment"}},"commerce_authorization":{"type":["string","null"]},"handoff_persisted":{"type":"boolean","description":"Present when the Worker attempted the requested Function hand-off. False means callers must use the client cart-attribute stamp path."},"handoff_stale_risk":{"type":"boolean","description":"Present with handoff_persisted. True means a failed clear may have left an older server stamp on the cart."}}},"StoreProfileResponse":{"type":"object","additionalProperties":false,"required":["schemaReady","shopId","shop","latestRun","brandProfile","brandPromptBlock","technicalProfile","findings","unreviewedCount","latestLearningRun","facts","evidence","suggestedFactsCount","confirmedFactsCount","rejectedFactsCount","openReviewCount","storeProfileContext"],"properties":{"schemaReady":{"type":"boolean","const":true},"shopId":{"type":"string","format":"uuid"},"shop":{"type":["object","null"]},"latestRun":{"type":["object","null"]},"brandProfile":{"type":["object","null"]},"brandPromptBlock":{"type":"string"},"technicalProfile":{"type":["object","null"]},"findings":{"type":"array","items":{"type":"object"}},"unreviewedCount":{"type":"integer","minimum":0},"latestLearningRun":{"type":["object","null"]},"facts":{"type":"array","items":{"type":"object"}},"evidence":{"type":"array","items":{"type":"object"}},"suggestedFactsCount":{"type":"integer","minimum":0},"confirmedFactsCount":{"type":"integer","minimum":0},"rejectedFactsCount":{"type":"integer","minimum":0},"openReviewCount":{"type":"integer","minimum":0},"storeProfileContext":{"type":["object","null"]}}},"AuditLog":{"type":"object","additionalProperties":false,"required":["id","shop_id","org_id","user_id","action","entity_type","entity_id","entity_name","diff","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":["string","null"],"format":"uuid"},"org_id":{"type":["string","null"],"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"action":{"type":"string"},"entity_type":{"type":"string"},"entity_id":{"type":"string","format":"uuid"},"entity_name":{"type":["string","null"]},"diff":{"type":["object","array","string","number","boolean","null"]},"created_at":{"type":"string","format":"date-time"}}},"InboxMessage":{"type":"object","required":["id","role","body","sender_id","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string"},"body":{"type":"string"},"sender_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"RuntimeEnvironment":{"type":"object","required":["key","name","isDefault","subSnippetEnabled","domains"],"additionalProperties":false,"properties":{"key":{"type":"string","pattern":"^[a-z0-9_-]+$","maxLength":48},"name":{"type":"string","maxLength":80},"isDefault":{"type":"boolean"},"subSnippetEnabled":{"type":"boolean"},"domains":{"type":"array","items":{"type":"string"}}}},"DataLayerTriggerWhenCondition":{"oneOf":[{"type":"object","additionalProperties":false,"required":["path","op","value"],"properties":{"path":{"type":"string","pattern":"^[A-Za-z_$][\\w$]*(?:\\.(?:\\d+|[A-Za-z_$][\\w$]*))*$"},"op":{"type":"string","enum":["eq","neq"]},"value":{"type":["string","number","boolean"]}}},{"type":"object","additionalProperties":false,"required":["path","op","value"],"properties":{"path":{"type":"string","pattern":"^[A-Za-z_$][\\w$]*(?:\\.(?:\\d+|[A-Za-z_$][\\w$]*))*$"},"op":{"type":"string","enum":["gt","lt"]},"value":{"type":"number"}}},{"type":"object","additionalProperties":false,"required":["path","op"],"properties":{"path":{"type":"string","pattern":"^[A-Za-z_$][\\w$]*(?:\\.(?:\\d+|[A-Za-z_$][\\w$]*))*$"},"op":{"type":"string","enum":["exists","not_exists"]}}}]},"DataLayerTrigger":{"type":"object","additionalProperties":false,"required":["eventName"],"properties":{"eventName":{"type":"string","minLength":1},"enabled":{"type":"boolean"},"dataLayerName":{"type":"string"},"reEvaluate":{"type":"boolean"},"trackPageview":{"type":"boolean"},"trackEventName":{"type":"string"},"when":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#/components/schemas/DataLayerTriggerWhenCondition"}},"trackRevenue":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"revenueFrom":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"orderIdFrom":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"currencyFrom":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"costFrom":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"profitFrom":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"properties":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"to":{"type":"string"},"valueType":{"type":"string","enum":["string","number","boolean","string_array","json"]},"transform":{"type":"object","additionalProperties":false,"properties":{"trim":{"type":"boolean"},"lowercase":{"type":"boolean"},"map":{"type":"object","maxProperties":20,"propertyNames":{"maxLength":100},"additionalProperties":{"type":"string","maxLength":100}},"scale":{"type":"number","not":{"const":0}},"default":{"type":["string","number","boolean"]}}}}}}}},"properties":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"to":{"type":"string"},"valueType":{"type":"string","enum":["string","number","boolean","string_array","json"]},"transform":{"type":"object","additionalProperties":false,"properties":{"trim":{"type":"boolean"},"lowercase":{"type":"boolean"},"map":{"type":"object","maxProperties":20,"propertyNames":{"maxLength":100},"additionalProperties":{"type":"string","maxLength":100}},"scale":{"type":"number","not":{"const":0}},"default":{"type":["string","number","boolean"]}}}}}},"mappings":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to"],"properties":{"from":{"anyOf":[{"type":"string"},{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}}]},"to":{"type":"string"},"valueType":{"type":"string","enum":["string","number","boolean","string_array","json"]},"ttlDays":{"type":"number"},"persist":{"type":"boolean"},"transform":{"type":"object","additionalProperties":false,"properties":{"trim":{"type":"boolean"},"lowercase":{"type":"boolean"},"map":{"type":"object","maxProperties":20,"propertyNames":{"maxLength":100},"additionalProperties":{"type":"string","maxLength":100}},"scale":{"type":"number","not":{"const":0}},"default":{"type":["string","number","boolean"]}}}}}}}},"Environments":{"type":"object","additionalProperties":false,"properties":{"activeKey":{"type":"string","pattern":"^[a-z0-9_-]+$","maxLength":48},"items":{"type":"array","minItems":1,"maxItems":12,"items":{"$ref":"#/components/schemas/RuntimeEnvironment"}}}},"ExternalTracking":{"type":"object","required":["domains","handoverQueryParam","handoverTtlSeconds","handoverMintTimeoutMs","signed"],"additionalProperties":false,"properties":{"domains":{"type":"array","maxItems":20,"items":{"type":"string"}},"handoverQueryParam":{"type":"string","pattern":"^[a-z_][a-z0-9_]{0,31}$","maxLength":32},"handoverTtlSeconds":{"type":"integer","minimum":30,"maximum":600},"handoverMintTimeoutMs":{"type":"integer","minimum":50,"maximum":2000},"signed":{"type":"boolean","default":true,"description":"Sending false is rejected with 403: turning handover signing off is a platform-support action. Sending true re-enables signing."}}},"ExternalTrackingResponse":{"type":"object","required":["externalTracking","revision"],"additionalProperties":false,"properties":{"externalTracking":{"$ref":"#/components/schemas/ExternalTracking"},"revision":{"type":"string","format":"date-time","nullable":true}}},"ExternalTrackingPatchResponse":{"type":"object","required":["externalTracking","revision","precompile"],"additionalProperties":false,"properties":{"externalTracking":{"$ref":"#/components/schemas/ExternalTracking"},"revision":{"type":"string","format":"date-time"},"precompile":{"type":"object","required":["status","summary"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["ok","warning","error"]},"summary":{"type":"string"}}}}},"EnvironmentsResponse":{"type":"object","required":["environments","version"],"additionalProperties":false,"properties":{"environments":{"$ref":"#/components/schemas/Environments"},"version":{"type":"string","format":"date-time","nullable":true,"description":"Opaque concurrency version. Null when runtime settings have not been persisted yet."}}},"EnvironmentsPatchResponse":{"type":"object","required":["environments","version","precompile"],"additionalProperties":false,"properties":{"environments":{"$ref":"#/components/schemas/Environments"},"version":{"type":"string","format":"date-time","description":"Opaque concurrency version after the settings write and edge precompile complete. Supply this value as expected_version on a subsequent PATCH."},"precompile":{"type":"object","required":["status","summary"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["ok","warning","error"]},"summary":{"type":"string"}}}}},"ConsentSettingsResponse":{"type":"object","required":["consentMode","prerequisites"],"additionalProperties":false,"properties":{"consentMode":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"provider":{"type":"string","enum":["custom","onetrust","usercentrics","cookiebot","ccm19","pandectes","cookiescript","borlabs"]},"getter":{"type":"string"},"requiredGroup":{"type":"string"}}},"prerequisites":{"type":"object","additionalProperties":false,"properties":{"showVariationsRule":{"type":["string","null"]},"startTrackingRule":{"type":["string","null"]}}},"precompile":{"$ref":"#/components/schemas/PrecompileResult"}}},"PrecompileResult":{"type":"object","required":["status","summary"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["ok","warning","error"]},"summary":{"type":"string"}}},"InstallDomainsResponse":{"type":"object","required":["shop_id","domain","additionalDomains","storeOrigins","revision"],"additionalProperties":false,"properties":{"shop_id":{"type":"string","format":"uuid","description":"Shop identifier used by the public Worker config endpoint."},"domain":{"type":"string"},"additionalDomains":{"type":"array","items":{"type":"string"}},"storeOrigins":{"type":"array","items":{"type":"string","format":"uri"}},"revision":{"type":"string","description":"Opaque concurrency token for install-domain writes."},"precompile":{"$ref":"#/components/schemas/PrecompileResult"}}},"ExperimentTargeting":{"type":"object","description":"Experiment audience and page targeting. Page definitions own treatment deactivation behavior.","properties":{"pageMatchMode":{"type":"string","enum":["any","all"],"description":"How included page rules combine; defaults to any when omitted."},"segmentMatchMode":{"type":"string","enum":["any","all"],"description":"How included audience rules combine; defaults to any when omitted."},"surface":{"type":"string","enum":["checkout"],"description":"Selects the Shopify checkout surface for checkout block experiments."},"checkoutBlock":{"type":"object","description":"Checkout block delivery settings.","required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"Enables checkout block delivery for the experiment."}},"additionalProperties":false}},"additionalProperties":true},"WeekdaySchedule":{"type":"object","required":["excludedDays","timezone"],"additionalProperties":false,"properties":{"excludedDays":{"type":"array","minItems":1,"maxItems":6,"uniqueItems":true,"items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]}},"timezone":{"type":"string","description":"IANA timezone used to resolve the local delivery day."}}},"Experiment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"public_id":{"type":["string","null"],"pattern":"^[1-9][0-9]{9}$","description":"10-digit dashboard route id for newly created experiments."},"slug":{"type":"string","nullable":true,"description":"Optional URL-safe slug for GitOps workflows"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"owner_user_id":{"type":["string","null"],"format":"uuid","description":"User ID assigned as the experiment owner."},"status":{"type":"string","enum":["draft","awaiting_client_approval","changes_requested","client_approved","qa","ready_to_launch","running","paused","completed"]},"counting_type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"],"default":"standard"},"delivery_type":{"type":"string","enum":["mutation","redirect"],"default":"mutation"},"type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"],"deprecated":true,"description":"Deprecated alias for counting_type."},"experiment_type":{"type":"string","enum":["mutation","redirect"],"default":"mutation","deprecated":true,"description":"Deprecated alias for delivery_type."},"targeting":{"anyOf":[{"$ref":"#/components/schemas/ExperimentTargeting"},{"type":"null"}]},"weekday_schedule":{"readOnly":true,"anyOf":[{"$ref":"#/components/schemas/WeekdaySchedule"},{"type":"null"}]},"traffic_allocation":{"type":"number","minimum":0,"maximum":1},"experiment_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Experiment-scoped JavaScript that runs before every variation's JavaScript. Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_reset_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Experiment-scoped reset JavaScript that runs once when the experiment resets. Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_css":{"type":"string","nullable":true,"maxLength":200000,"description":"Experiment-scoped CSS injected once for all variations. Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"sequential_testing_enabled":{"type":"boolean","description":"Enable always-valid sequential significance (mSPRT)"},"auto_stop_override":{"$ref":"#/components/schemas/AutoStopOverride"},"guardian_override":{"$ref":"#/components/schemas/GuardianOverride"},"planned_test":{"$ref":"#/components/schemas/PlannedTestSnapshot"},"store_url":{"type":"string","nullable":true},"scheduled_start_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"ended_at":{"type":"string","format":"date-time","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"approval_state":{"readOnly":true,"nullable":true,"type":"object","required":["status","updated_at"],"properties":{"status":{"type":"string","enum":["pending","approved","changes_requested","revoked"]},"updated_at":{"type":"string","format":"date-time"}},"description":"Current design-approval projection. Approval request history remains dashboard-only."},"linked_idea":{"readOnly":true,"type":["object","null"],"required":["key","title","stage"],"properties":{"key":{"type":["string","null"],"description":"Apex backlog key, such as LOC-121"},"title":{"type":"string"},"stage":{"type":"string"}},"description":"The idea this experiment is linked to: the primary link, else the oldest link. Present on single-experiment reads and on create; list responses omit it."},"created_at":{"type":"string","format":"date-time"},"variations":{"type":"array","items":{"$ref":"#/components/schemas/Variation"}},"goals":{"type":"array","items":{}},"goalPageRules":{"type":"array","description":"Page rule definitions used only to scope goals; they do not activate or render the experiment treatment.","items":{"type":"object","additionalProperties":true,"required":["id","includeRules","excludeRules"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"include":{"type":"boolean"},"disabled":{"type":"boolean"},"includeRules":{"type":"array","items":{"type":"object"}},"excludeRules":{"type":"array","items":{"type":"object"}},"advancedCondition":{},"trigger":{"type":"object","additionalProperties":true}}}},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}}},"required":["id","name","status","counting_type","delivery_type","type","experiment_type","traffic_allocation","archived_at","created_at"]},"AutoStopOverride":{"type":"object","properties":{"mode":{"type":"string","enum":["inherit","off","fixed_horizon_planned_end","sequential_significance"]},"min_runtime_minutes":{"type":"integer","minimum":0},"sequential":{"type":"object","nullable":true,"properties":{"min_visitors":{"type":"integer","minimum":1},"min_conversions":{"type":"integer","minimum":1},"action_on_significant":{"type":"string","enum":["pause"]}}},"fixed_horizon":{"type":"object","nullable":true,"properties":{"window_days":{"type":"integer","minimum":1},"mde":{"type":"number","minimum":0.001,"maximum":1},"alpha":{"type":"number","minimum":0.001,"maximum":0.2},"power":{"type":"number","minimum":0.5,"maximum":0.99},"tail":{"type":"string","enum":["two-sided","one-sided"]},"auto_pause_on_inconclusive":{"type":"boolean"}}}},"required":["mode"]},"GuardianOverride":{"type":"object","description":"Per-experiment Guardian safety overrides. Null fields inherit the shop default (Guardian defaults to fully enabled).","properties":{"enabled":{"type":"boolean","nullable":true},"pause_on_broken":{"type":"boolean","nullable":true},"pause_on_harm":{"type":"boolean","nullable":true},"alert_on_data_quality":{"type":"boolean","nullable":true},"delivery_drift":{"type":"object","nullable":true,"properties":{"enabled":{"type":"boolean","nullable":true},"missRateThreshold":{"type":"number","minimum":0,"maximum":1,"nullable":true},"minSamples":{"type":"integer","minimum":1,"nullable":true},"consecutiveChecks":{"type":"integer","minimum":1,"nullable":true},"shouldPause":{"type":"boolean","nullable":true}}},"revenue_loss":{"type":["object","null"],"description":"Per-experiment revenue-loss pause threshold. Null inherits the shop default.","properties":{"enabled":{"type":["boolean","null"]},"threshold_amount":{"type":["number","null"],"exclusiveMinimum":0},"currency":{"type":["string","null"],"minLength":3,"maxLength":3}}}}},"PlannedTestSnapshot":{"type":"object","nullable":true,"properties":{"computed_at":{"type":"string","format":"date-time"},"epoch_started_at":{"type":"string","format":"date-time"},"goal_id":{"type":"string","format":"uuid"},"correction_method":{"type":"string","enum":["none","holm"],"description":"Multiplicity regime the required sample was sized under. \"holm\" sizes multi-treatment plans at the first-step comparison alpha; \"none\" is single-treatment sizing. Absent on plans registered before multi-arm Holm sizing."},"baseline_rate":{"type":"number"},"window_days":{"type":"integer"},"mde":{"type":"number"},"alpha":{"type":"number"},"power":{"type":"number"},"tail":{"type":"string","enum":["two-sided","one-sided"]},"required_sample_per_variant":{"type":"integer"},"required_total_visitors":{"type":"integer"},"estimated_days":{"type":"number"},"endpoint_reached_at":{"type":"string","format":"date-time"},"evaluation":{"type":"object","nullable":true,"properties":{"evaluated_at":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["significant_pause","inconclusive_pause","continue_inconclusive","continue_not_positive"]},"total_visitors_at_evaluation":{"type":"integer"},"winning_variation_id":{"type":"string","format":"uuid","nullable":true},"blocked_reason":{"type":"string","enum":["excluded_currency_residue","measurement_quality_unavailable"]}}},"revenue_evaluation":{"type":"object","nullable":true,"description":"Persisted, single-look revenue verdict evaluated at the registered sample endpoint.","required":["evaluated_at","basis","currency","excluded_currency_percentage","total_visitors_at_evaluation","comparisons"],"properties":{"evaluated_at":{"type":"string","format":"date-time"},"basis":{"type":"string","enum":["shop_money"]},"multiplicity_adjustment":{"type":"string","enum":["none","holm","sidak"],"description":"Multiplicity correction applied to the frozen verdict. Current writes emit only \"none\" or \"holm\"; \"sidak\" is a legacy value that persisted snapshots can still return, since v1 GETs serialize the stored planned_test unchanged."},"currency":{"type":"string","minLength":3,"maxLength":3},"excluded_currency_percentage":{"type":"number","minimum":0,"maximum":100},"total_visitors_at_evaluation":{"type":"integer","minimum":0},"comparisons":{"type":"array","minItems":1,"items":{"type":"object","required":["treatment_variation_id","control_mean","variation_mean","relative_lift","absolute_lift","t_statistic","degrees_of_freedom","p_value","confidence","is_significant","confidence_interval"],"properties":{"treatment_variation_id":{"type":"string","format":"uuid"},"control_mean":{"type":"number"},"variation_mean":{"type":"number"},"relative_lift":{"type":"number"},"absolute_lift":{"type":"number"},"t_statistic":{"type":"number"},"degrees_of_freedom":{"type":"number"},"p_value":{"type":"number","minimum":0,"maximum":1},"confidence":{"type":"number","minimum":0,"maximum":100},"is_significant":{"type":"boolean"},"confidence_interval":{"anyOf":[{"type":"object","required":["lower","upper"],"properties":{"lower":{"type":"number"},"upper":{"type":"number"}}},{"type":"null"}]}}}}}}}},"Mutation":{"type":"object","required":["selector","action"],"properties":{"selector":{"type":"string","description":"CSS selector targeting the element(s)"},"action":{"type":"string","enum":["text","setText","html","style","setStyle","attribute","remove","insertBefore","insertAfter"],"description":"Type of DOM mutation to apply"},"text":{"type":"string","description":"New text content (for text/setText actions)"},"html":{"type":"string","description":"HTML content (for html/insertBefore/insertAfter actions)"},"attribute":{"type":"object","description":"Legacy single-attribute form (kept for backward compatibility)","properties":{"name":{"type":"string"},"value":{"type":"string","nullable":true}},"required":["name","value"]},"attributes":{"type":"object","additionalProperties":{"type":["string","null"]},"description":"Key-value pairs of attributes to set"},"styles":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value pairs of CSS styles to apply"},"description":{"type":"string","description":"Human-readable description"}}},"UrlBlocks":{"type":"array","nullable":true,"maxItems":50,"description":"Ordered per-URL artifacts; the first matching block wins and no match falls back to the flat variation fields.","items":{"type":"object","additionalProperties":false,"required":["id","name","urlRules","mutations"],"properties":{"id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":255},"urlRules":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["type","pattern"],"properties":{"type":{"type":"string","enum":["simple","regex"]},"pattern":{"type":"string","minLength":1,"maxLength":500},"include":{"type":"boolean"}}}},"mutations":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/Mutation"}},"css":{"type":"string","maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"js":{"type":"string","maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."}}}},"Variation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"public_id":{"type":["string","null"],"pattern":"^[1-9][0-9]{9}$","description":"10-digit dashboard route id for newly created variations."},"experiment_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"weight":{"type":"number","minimum":0,"maximum":1},"is_control":{"type":"boolean"},"archived_at":{"type":["string","null"],"format":"date-time"},"archived_by":{"type":["string","null"]},"mutations":{"type":"array","items":{"$ref":"#/components/schemas/Mutation"}},"url_blocks":{"$ref":"#/components/schemas/UrlBlocks"},"custom_css":{"type":"string","nullable":true,"description":"Custom CSS injected as a <style> tag. Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"custom_js":{"type":"string","nullable":true,"description":"Custom JavaScript executed after mutations. Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"redirect_url":{"type":"string","format":"uri","nullable":true,"description":"Redirect destination. Null clears the destination on redirect experiments and is treated as omitted on mutation experiments. Mutations and custom CSS/JavaScript on the same treatment are source-page-only; the destination preserves assignment attribution without applying those artifacts. A destination on the same origin and path as the experiment's positive source URL rules that differs only by query parameters (a template variant, for example a Shopify ?view= alternate template) is accepted; any other destination matching the source rules is rejected."},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}}},"required":["id","experiment_id","name","weight","is_control"]},"GoalCapture":{"type":"object","required":["property","source"],"properties":{"source":{"type":"string","enum":["attribute","textContent","dataset"],"description":"Where to read the value from"},"attribute":{"type":"string","description":"Required when source is attribute or dataset (e.g. href, data-product-id)"},"property":{"type":"string","description":"Property name in event data"}}},"GoalFilterCondition":{"type":"object","additionalProperties":false,"required":["property","operator"],"properties":{"property":{"type":"string","pattern":"^[a-zA-Z0-9_]{1,64}$"},"operator":{"type":"string","enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","in","not_in","gt","gte","lt","lte","exists"]},"value":{"oneOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"array","minItems":1,"maxItems":50,"items":{"oneOf":[{"type":"string"},{"type":"number"}]}}]}}},"GoalLineItemFilterCondition":{"type":"object","additionalProperties":false,"required":["property","operator"],"properties":{"property":{"type":"string","enum":["productId","productTitle","productType","vendor","variantId","sku","quantity","price","revenue"]},"operator":{"$ref":"#/components/schemas/GoalFilterCondition/properties/operator"},"value":{"$ref":"#/components/schemas/GoalFilterCondition/properties/value"}}},"GoalFilter":{"type":"object","additionalProperties":false,"required":["version"],"description":"Versioned event-property filter. lineItems is supported for revenue goals and custom goals whose event_name is exactly checkout_started or add_to_cart.","properties":{"version":{"type":"integer","enum":[1]},"conditions":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/GoalFilterCondition"}},"orderValue":{"type":"array","minItems":1,"maxItems":4,"description":"Order-total conditions, available only for revenue goals. Conditions are ANDed.","items":{"type":"object","additionalProperties":false,"required":["operator","value"],"properties":{"operator":{"type":"string","enum":["gt","gte","lt","lte","equals","not_equals"]},"value":{"type":"number","minimum":0}}}},"lineItems":{"type":"object","additionalProperties":false,"required":["match","conditions"],"properties":{"match":{"type":"string","enum":["any","none","only"]},"missingItems":{"type":"string","enum":["include","exclude"],"default":"exclude","description":"Whether orders without usable product data satisfy the line-item group."},"conditions":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/GoalLineItemFilterCondition"}}}}},"anyOf":[{"required":["conditions"]},{"required":["orderValue"]},{"required":["lineItems"]}]},"BrandContext":{"type":"object","properties":{"hasProfile":{"type":"boolean"},"mode":{"type":"string","enum":["off","balanced","strict"]},"status":{"type":"string"},"summary":{"type":"string"},"voice":{"type":"object","properties":{"adjectives":{"type":"array","items":{"type":"string"}},"weAlways":{"type":"array","items":{"type":"string"}},"weNever":{"type":"array","items":{"type":"string"}},"bannedPhrases":{"type":"array","items":{"type":"string"}},"ctaStyle":{"type":"string"}},"required":["adjectives","weAlways","weNever","bannedPhrases","ctaStyle"]},"guardrails":{"type":"array","items":{"type":"string"}},"proofRequirements":{"type":"array","items":{"type":"string"}},"clientNotes":{"type":"string"},"clientAssetExcerpts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"excerpt":{"type":"string"}},"required":["name","excerpt"]},"description":"Client-provided brand file excerpts. Raw uploaded asset bodies and internal Apex notes are not included."},"guidelinesText":{"type":"string"},"promptBlock":{"type":"string"}},"required":["hasProfile","mode","status","summary","voice","guardrails","proofRequirements","clientNotes","clientAssetExcerpts","guidelinesText","promptBlock"]},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"hasSecret":{"type":"boolean"},"consecutiveFailures":{"type":"integer"},"disabledAt":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"},"archived_by":{"type":["string","null"]}},"required":["id","url","events","active","hasSecret","consecutiveFailures","disabledAt","created_at"]},"WebhookCreated":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Plaintext signing secret returned only when the webhook is created. Store it now; later reads do not return it."}}}]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"webhook_id":{"type":"string","format":"uuid"},"event":{"type":"string"},"status":{"type":"string","enum":["queued","processing","delivered","failed","dead"]},"attempts":{"type":"integer"},"response_status":{"type":"integer","nullable":true},"last_error":{"type":"string","nullable":true},"next_attempt_at":{"type":"string","format":"date-time"},"processing_started_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","webhook_id","event","status","attempts","created_at","updated_at"]},"ScreenshotJob":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"results":{"type":"array","items":{},"nullable":true},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"required":["job_id","status","created_at"]},"Error":{"type":"object","description":"All public API errors use this envelope: error.message is stable enough for humans, error.status mirrors the HTTP status code, error.code identifies machine-actionable failures when present, and 5xx responses include internal error details without a stack trace.","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"details":{"type":"string","description":"Present on unexpected 5xx responses with the internal error name and full message, plus the Sentry event id when available."}},"required":["message","status"]}},"required":["error"]},"PageLiveImpactError":{"type":"object","description":"409 body for a Page write that reaches live consumers. It carries the standard error envelope plus the consumers themselves, whose ids are what a confirming retry echoes in confirmed_consumer_ids.","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"integer"}},"required":["message","status"]},"live_experiments":{"type":"array","description":"Running consumers that target this Page. Despite the field name it also carries feature flags and personalizations; the consumer field says which.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"consumer":{"type":"string","enum":["experiment","feature flag","personalization"]}},"required":["id","name","consumer"]}}},"required":["error","live_experiments"]},"CommercePlanePostCommitPublishError":{"type":"object","additionalProperties":false,"description":"The experiment lifecycle change is committed, but the storefront publish failed. Retry publication against the returned committed state.","properties":{"error":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[502]},"code":{"type":"string","enum":["commerce_plane_post_commit_publish_failed"]}},"required":["message","status","code"]},"persisted":{"type":"boolean","enum":[true]},"retriable":{"type":"boolean","enum":[true]},"committed":{"$ref":"#/components/schemas/Experiment"},"refresh":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["warning","error"]},"summary":{"type":"string"},"details":{"type":"array","items":{"type":"string"}},"retriable":{"type":"boolean"}},"required":["id","label","status","summary","details"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["error","persisted","retriable","committed","refresh","reasons"]},"FeatureFlagInput":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":["string","null"],"maxLength":2000},"delivery_type":{"type":"string","enum":["visual","api"],"default":"visual"},"environment_key":{"type":"string","minLength":1,"maxLength":48,"default":"production"},"rollout_percentage":{"type":"number","minimum":0,"maximum":1,"default":1},"off_value":{},"on_value":{},"targeting":{"type":["object","null"]},"weekday_schedule":{"description":"Days this flag stays dark, resolved in an explicit IANA timezone. Visual delivery only: API-delivery flags reject a schedule because Apex does not evaluate them.","anyOf":[{"$ref":"#/components/schemas/WeekdaySchedule"},{"type":"null"}]},"activate":{"type":"boolean","default":false}},"required":["key","name"]},"FeatureFlagUpdateInput":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":["string","null"],"maxLength":2000},"delivery_type":{"type":"string","enum":["visual","api"]},"environment_key":{"type":"string","minLength":1,"maxLength":48},"rollout_percentage":{"type":"number","minimum":0,"maximum":1},"targeting":{"type":["object","null"]},"weekday_schedule":{"description":"Days this flag stays dark, resolved in an explicit IANA timezone. Visual delivery only: API-delivery flags reject a schedule because Apex does not evaluate them.","anyOf":[{"$ref":"#/components/schemas/WeekdaySchedule"},{"type":"null"}]}}},"FeatureFlag":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"delivery_type":{"type":"string","enum":["visual","api"]},"environment_key":{"type":"string"},"rollout_percentage":{"type":"number","minimum":0,"maximum":1},"targeting":{"type":["object","null"]},"weekday_schedule":{"anyOf":[{"$ref":"#/components/schemas/WeekdaySchedule"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"object"}},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","name","status","delivery_type","environment_key","rollout_percentage","variants","created_at","updated_at"]},"PersonalizationExperienceInput":{"type":"object","additionalProperties":false,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets. Code fields and serialized mutations have a shared limit of 500,000 characters; existing lower field limits still apply.","properties":{"key":{"type":"string","minLength":1,"maxLength":100,"default":"default"},"name":{"type":"string","minLength":1,"maxLength":255,"default":"Personalized experience"},"value":{},"mutations":{"type":"array","items":{"$ref":"#/components/schemas/Mutation"}},"custom_css":{"type":["string","null"]},"custom_js":{"type":["string","null"]},"reset_js":{"type":["string","null"],"maxLength":200000},"anti_flicker_selectors":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":500}},"recommendation_profile":{"type":["string","null"],"maxLength":120}}},"PersonalizationInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"key":{"type":"string","minLength":1,"maxLength":100},"description":{"type":["string","null"],"maxLength":2000},"delivery_type":{"type":"string","enum":["visual","api","recommendation"],"default":"visual"},"surface":{"type":"string","minLength":1,"maxLength":80,"default":"global"},"environment_key":{"type":"string","minLength":1,"maxLength":48,"default":"production"},"priority":{"type":"integer","minimum":0,"maximum":10000,"default":100},"rollout_percentage":{"type":"number","minimum":0,"maximum":1,"default":1},"template_key":{"type":["string","null"],"maxLength":120},"targeting":{"type":["object","null"]},"goal_ids":{"type":"array","maxItems":10,"items":{"type":"string","format":"uuid"}},"primary_goal_id":{"type":"string","format":"uuid"},"activate":{"type":"boolean","default":false},"experience":{"$ref":"#/components/schemas/PersonalizationExperienceInput"}},"required":["name","key"]},"PersonalizationUpdateInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"key":{"type":"string","minLength":1,"maxLength":100},"description":{"type":["string","null"],"maxLength":2000},"delivery_type":{"type":"string","enum":["visual","api","recommendation"]},"surface":{"type":"string","minLength":1,"maxLength":80},"environment_key":{"type":"string","minLength":1,"maxLength":48},"priority":{"type":"integer","minimum":0,"maximum":10000},"rollout_percentage":{"type":"number","minimum":0,"maximum":1},"template_key":{"type":["string","null"],"maxLength":120},"targeting":{"type":["object","null"]},"goal_ids":{"type":"array","maxItems":10,"items":{"type":"string","format":"uuid"}},"primary_goal_id":{"type":"string","format":"uuid"}}},"Personalization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"delivery_type":{"type":"string","enum":["visual","api","recommendation"]},"surface":{"type":"string"},"environment_key":{"type":"string"},"priority":{"type":"integer"},"rollout_percentage":{"type":"number","minimum":0,"maximum":1},"targeting":{"type":["object","null"]},"experiences":{"type":"array","items":{"type":"object"}},"rules":{"type":"array","items":{"type":"object"}},"personalization_goals":{"type":"array","items":{"type":"object"}},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","name","status","delivery_type","surface","environment_key","priority","rollout_percentage","experiences","rules","created_at","updated_at"]},"WorkspaceFile":{"type":"object","properties":{"path":{"type":"string","description":"Canonical workspace path such as src/index.js, metrics.json, targeting.json, goals/primary.json, or segments/audience.json."},"kind":{"type":"string"},"contentType":{"type":"string"},"content":{"type":"string"},"sha256":{"type":"string"},"sizeBytes":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"},"readonly":{"type":"boolean","description":"True when the file is generated by Apex and should not be written back."}},"required":["path","kind","contentType","content","sha256","sizeBytes"]},"ExperimentFilesystemFile":{"type":"object","additionalProperties":false,"properties":{"path":{"type":"string"},"content":{"type":"string"},"sha256":{"type":"string"},"readonly":{"type":"boolean"}},"required":["path","content","sha256"]},"ExperimentFilesystemPlan":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean"},"experimentId":{"type":"string","format":"uuid"},"status":{"type":"string"},"changes":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"path":{"type":"string"},"entity":{"type":"string"},"action":{"type":"string","enum":["create","update","delete","replace","noop"]},"summary":{"type":"string"},"invalidatesQa":{"type":"boolean"}},"required":["entity","action","summary"]}},"errors":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"blockingIssues":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["blocking","warning"]},"message":{"type":"string"},"field":{"type":"string"},"path":{"type":"string"},"variation":{"type":"string","description":"Present for variation-level issues and omitted for experiment-level issues."}},"required":["code","severity","message","path"]}},"invalidatesQa":{"type":"boolean"},"precompileRequired":{"type":"boolean"}},"required":["ok","experimentId","status","changes","errors","warnings","blockingIssues","invalidatesQa","precompileRequired"]},"WorkspacePayload":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schemaVersion":{"type":"integer"},"status":{"type":"string"},"currentRevisionId":{"type":"string","format":"uuid","nullable":true},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","schemaVersion","status","updatedAt"]},"files":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceFile"}}},"required":["workspace","files"]},"WorkspaceRevision":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"title":{"type":"string"},"source":{"type":"string"},"summary":{"type":"string","nullable":true},"changed_paths":{"type":"array","items":{"type":"string"}},"build_result":{"type":"object","nullable":true},"created_by":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","sequence","title","source","changed_paths","created_at"]},"BacklogItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"org_id":{"type":["string","null"],"format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":["string","null"],"maxLength":10000},"status":{"type":"string","enum":["rough_idea","finished_concept","approved"]},"action_type":{"type":"string","enum":["ab_test","price_test","shipping_test","landing_page"]},"source":{"type":"string","minLength":1,"maxLength":80},"source_kind":{"type":"string","enum":["manual","customer","drip","research_hub"]},"source_id":{"type":["string","null"],"maxLength":255},"source_label":{"type":["string","null"],"maxLength":255},"provenance":{},"research_hub_brand_id":{"type":["string","null"],"maxLength":255},"research_hub_idea_id":{"type":["string","null"],"maxLength":255},"logic_map_artifact_id":{"type":["string","null"],"maxLength":255},"logic_map_status":{"type":"string","minLength":1,"maxLength":80},"test_plan_artifact_id":{"type":["string","null"],"maxLength":255},"hypothesis":{"type":["string","null"],"maxLength":10000},"page_label":{"type":["string","null"],"maxLength":255,"description":"Page the idea targets. Free text is mapped to a canonical page: a genome surface id (homepage, plp, pdp, cart, checkout, search, navigation, landing_page, quiz_lead_capture, ads, post_purchase, account, sitewide, other) or one of the shop's own page names. Text that names no known page is stored as null and returned in warnings."},"page_url":{"type":["string","null"],"maxLength":2000},"device":{"type":["string","null"],"maxLength":80,"description":"Device the idea targets. Free text is mapped to all, mobile, or desktop; naming both devices or responsive design maps to all. Text that names no device is stored as null and returned in warnings."},"audience":{"type":["string","null"],"maxLength":255},"psychological_direction":{"type":["string","null"],"maxLength":255},"psychological_tactic":{"type":["string","null"],"maxLength":255},"planned_launch_month":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Planned launch month as YYYY-MM. Drives the season feature in genome predictions."},"neednavigator_tags":{"type":"array","items":{}},"research_type":{"type":"array","items":{}},"research_notes":{"type":["string","null"],"maxLength":20000},"research_indication":{"type":["string","null"],"maxLength":10000},"variation_brief":{"type":["string","null"],"maxLength":20000},"landing_page_brief":{},"price_shipping_brief":{},"expected_revenue_impact":{"type":["number","null"],"minimum":0,"maximum":100},"ease_of_implementation":{"type":["integer","null"],"minimum":0,"maximum":10},"expert_review_score":{"type":["integer","null"],"minimum":0,"maximum":10},"feature_visibility_score":{"type":["integer","null"],"minimum":0,"maximum":10},"research_score":{"type":["number","null"],"minimum":0,"maximum":100},"learning_score":{"type":["number","null"],"minimum":0,"maximum":100},"computed_score":{"type":["number","null"],"minimum":0,"maximum":100},"score_breakdown":{},"score_source":{"type":"string","maxLength":80},"score_version":{"type":["string","null"],"maxLength":80},"due_date":{"type":["string","null"],"format":"date-time"},"campaign_start_at":{"type":["string","null"],"format":"date-time"},"campaign_end_at":{"type":["string","null"],"format":"date-time"},"owner_user_id":{"type":["string","null"],"format":"uuid"},"sketch_refs":{"type":"array","items":{}},"asset_refs":{"type":"array","items":{}},"tags":{"type":"array","items":{}},"metadata":{},"custom_fields":{"type":"object","additionalProperties":true,"description":"Values for the shop's own fields, keyed by field key. Each value is validated against its definition from /backlog/fields; a wrong type answers 422 naming the key. On PATCH, a null clears one value and unnamed fields are left alone."},"score_sources":{"type":"array","readOnly":true,"description":"What builds this item's score, as points earned of points possible. Returned by GET /v1/backlog/{id} only. The maxima depend on the shop's tier and always sum to 100: a drip_managed shop scores a client_priority source and halves the expert source, the self-serve tiers do neither.","items":{"type":"object","properties":{"id":{"type":"string","enum":["win","impact","ease","visibility","expert","client_priority"]},"label":{"type":"string"},"note":{"type":"string"},"got":{"type":"number","description":"Whole points earned, between 0 and max."},"max":{"type":"number"},"kind":{"type":"string","enum":["measured","model","human"]},"editable":{"type":"boolean","description":"True when this tier lets the shop set the input itself."},"readonly":{"type":"boolean"},"hint":{"type":"string","description":"The sentence beside a judgement input: how to read it, or who sets it. Empty on the other rows."},"unavailable":{"type":"boolean","description":"True when no input exists for this source; got is 0."},"step":{"type":["number","null"],"description":"The 1-5 value of a judgement input, null on the other rows."}},"required":["id","label","note","got","max","kind","editable","readonly","hint","unavailable","step"]}},"version":{"type":"string","pattern":"^[1-9][0-9]*$","readOnly":true,"description":"Concurrency version to send as expected_version on a subsequent PATCH."},"taxonomy_version":{"type":["string","null"],"readOnly":true,"description":"Genome taxonomy version the item's page_label, psychological_direction, and psychological_tactic were validated against. Stamped by the server; it is not accepted on write."},"warnings":{"type":"array","readOnly":true,"description":"Present on a create or update response only when a written value named nothing the vocabulary knows. The field was stored as null; ask the caller to choose a page or a device.","items":{"type":"object","required":["field","input"],"properties":{"field":{"type":"string","enum":["device","page_label"]},"input":{"type":"string"}}}},"archived_at":{"type":["string","null"],"format":"date-time"},"archived_by":{"type":["string","null"]},"created_by":{"type":["string","null"],"format":"uuid"},"updated_by":{"type":["string","null"],"format":"uuid"},"ownerUserId":{"type":["string","null"],"format":"uuid"},"owner":{"type":["object","null"],"properties":{"user_id":{"type":"string","format":"uuid"},"email":{"type":["string","null"]},"name":{"type":"string"},"initials":{"type":"string"}},"required":["user_id","email","name","initials"]},"research_hub_round_trip":{},"design":{"$ref":"#/components/schemas/BacklogItemDesign","readOnly":true,"description":"Design board for this idea, normalised through the same reader as GET /backlog/{id}/design, so an item stored before the board existed returns the four empty fields rather than an empty object. Present on the detail read only; the list read omits it. The board is redacted to mockups and client-visible links for a client viewer: a client shop role in the dashboard, and a user API key whose holder holds one. A secret API key reads the whole board. Read-only here: PATCH /backlog/{id}/design is the write path."},"roadmap_decision":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"roadmap_month":{"type":["string","null"]},"note":{"type":["string","null"]},"decided_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"experiment_links":{"type":"array","items":{"type":"object"}},"linked_experiments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"experiment_id":{"type":"string","format":"uuid"},"link_type":{"type":"string"},"test_key":{"type":["string","null"]},"name":{"type":"string"},"status":{"type":"string"},"store_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","version","title","status","action_type","source","source_id","created_at","updated_at","linked_experiments","ownerUserId","owner","research_hub_round_trip"]},"BacklogItemDesign":{"type":"object","additionalProperties":false,"description":"Mockups, links, inspiration images, and internal build notes for one idea. A research_hub mockup stores only the ref of the Research Hub mirror it places; the mirror itself stays in asset_refs. Every read normalises the stored value, so all four fields are always present: an idea created before this board existed reads as four empty values, never as an empty object.","properties":{"mockups":{"type":"array","maxItems":50,"description":"Ids are unique across the list. At most one mockup may set lead; a stored non-empty list always has exactly one, because a list saved without one gets its first entry.","items":{"oneOf":[{"type":"object","additionalProperties":false,"description":"A file uploaded through POST /backlog/{id}/attachments.","properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"kind":{"type":"string","enum":["upload"]},"url":{"type":"string","maxLength":2000,"description":"Serving URL."},"label":{"type":"string","maxLength":200},"order":{"type":"integer","minimum":0,"maximum":999},"lead":{"type":"boolean","description":"Shown first to the client."}},"required":["id","kind","url"]},{"type":"object","additionalProperties":false,"description":"A Research Hub mirror placed by reference. The file itself stays in asset_refs and is never copied here.","properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"kind":{"type":"string","enum":["research_hub"]},"ref":{"type":"string","maxLength":500,"description":"Mirror key: the storage path, or the serving URL when there is none."},"label":{"type":"string","maxLength":200},"order":{"type":"integer","minimum":0,"maximum":999},"lead":{"type":"boolean","description":"Shown first to the client."}},"required":["id","kind","ref"]}]}},"links":{"type":"array","maxItems":50,"description":"Ids are unique across the list.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"kind":{"type":"string","enum":["figma","loom","other"]},"url":{"type":"string","format":"uri","maxLength":2000,"pattern":"^https?://","description":"An http or https URL. Other schemes are rejected: the link is rendered as a clickable href, so a javascript: URL would run script in the dashboard origin."},"label":{"type":"string","maxLength":200},"client_visible":{"type":"boolean","default":false,"description":"Whether the client sees this link. Omitted means false for every kind: the dashboard's add dialog pre-selects it for figma and loom, but a link stored without the flag stays internal."}},"required":["id","kind","url"]}},"inspiration":{"type":"array","maxItems":50,"description":"Internal. Ids are unique across the list; each entry carries a url or a ref, never both.","items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"url":{"type":"string","maxLength":2000},"label":{"type":"string","maxLength":200}},"required":["id","url"]},{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"ref":{"type":"string","maxLength":500},"label":{"type":"string","maxLength":200}},"required":["id","ref"]}]}},"build_notes":{"type":"string","maxLength":20000,"description":"Internal. Never sent to a client-facing read."}},"required":["mockups","links","inspiration","build_notes"]},"BacklogItemDesignPatch":{"type":"object","additionalProperties":false,"description":"Any subset of the design keys, and at least one of them. An absent key is left alone; a present array replaces the stored one wholesale. A body carrying only expected_version is rejected with 400: it changes nothing, and the write would still raise the item version and stale every other editor's token.","properties":{"mockups":{"type":"array","maxItems":50,"description":"Ids are unique across the list. At most one mockup may set lead; a stored non-empty list always has exactly one, because a list saved without one gets its first entry.","items":{"oneOf":[{"type":"object","additionalProperties":false,"description":"A file uploaded through POST /backlog/{id}/attachments.","properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"kind":{"type":"string","enum":["upload"]},"url":{"type":"string","maxLength":2000,"description":"Serving URL."},"label":{"type":"string","maxLength":200},"order":{"type":"integer","minimum":0,"maximum":999},"lead":{"type":"boolean","description":"Shown first to the client."}},"required":["id","kind","url"]},{"type":"object","additionalProperties":false,"description":"A Research Hub mirror placed by reference. The file itself stays in asset_refs and is never copied here.","properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"kind":{"type":"string","enum":["research_hub"]},"ref":{"type":"string","maxLength":500,"description":"Mirror key: the storage path, or the serving URL when there is none."},"label":{"type":"string","maxLength":200},"order":{"type":"integer","minimum":0,"maximum":999},"lead":{"type":"boolean","description":"Shown first to the client."}},"required":["id","kind","ref"]}]}},"links":{"type":"array","maxItems":50,"description":"Ids are unique across the list.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"kind":{"type":"string","enum":["figma","loom","other"]},"url":{"type":"string","format":"uri","maxLength":2000,"pattern":"^https?://","description":"An http or https URL. Other schemes are rejected: the link is rendered as a clickable href, so a javascript: URL would run script in the dashboard origin."},"label":{"type":"string","maxLength":200},"client_visible":{"type":"boolean","default":false,"description":"Whether the client sees this link. Omitted means false for every kind: the dashboard's add dialog pre-selects it for figma and loom, but a link stored without the flag stays internal."}},"required":["id","kind","url"]}},"inspiration":{"type":"array","maxItems":50,"description":"Internal. Ids are unique across the list; each entry carries a url or a ref, never both.","items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"url":{"type":"string","maxLength":2000},"label":{"type":"string","maxLength":200}},"required":["id","url"]},{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"ref":{"type":"string","maxLength":500},"label":{"type":"string","maxLength":200}},"required":["id","ref"]}]}},"build_notes":{"type":"string","maxLength":20000,"description":"Internal. Never sent to a client-facing read."},"expected_version":{"type":["integer","string"],"description":"Version returned by the latest design read. REQUIRED: this endpoint replaces whole lists after reading them, so an unconditional write would drop a concurrent edit. A stale value returns 409 with error.code backlog_item_cas_miss; values above 2147483647 are rejected as invalid."}},"required":["expected_version"],"anyOf":[{"required":["mockups"]},{"required":["links"]},{"required":["inspiration"]},{"required":["build_notes"]}]},"BacklogItemDesignEnvelope":{"type":"object","properties":{"backlog_item_id":{"type":"string","format":"uuid"},"version":{"type":"integer","description":"Send as expected_version on the next design PATCH."},"design":{"$ref":"#/components/schemas/BacklogItemDesign"},"research_hub_mockups":{"type":"array","description":"Every renderable Research Hub mirror on this item, placed or not. A client role receives only the mirrors its own mockups place, because the picker's list is internal.","items":{"$ref":"#/components/schemas/BacklogDesignComparisonRef"}},"shop_name":{"type":"string","description":"The client named in the tab's labels."},"comparison":{"anyOf":[{"$ref":"#/components/schemas/BacklogDesignComparison"},{"type":"null"}],"description":"Server-resolved original and proposed screens for the selected Research Hub variant. Null when no comparison role is present."}},"required":["backlog_item_id","version","design","research_hub_mockups","shop_name","comparison"]},"BacklogDesignComparisonRef":{"type":"object","properties":{"ref":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"},"role":{"type":"string","enum":["original","idea","reference","composite"]},"variantId":{"type":"string"},"device":{"type":"string","enum":["desktop","mobile"]}},"required":["ref","url","label"]},"BacklogDesignComparisonPair":{"type":"object","additionalProperties":false,"properties":{"original":{"anyOf":[{"$ref":"#/components/schemas/BacklogDesignComparisonRef"},{"type":"null"}]},"variant":{"anyOf":[{"$ref":"#/components/schemas/BacklogDesignComparisonRef"},{"type":"null"}]},"device":{"type":["string","null"],"enum":["desktop","mobile",null]}},"required":["original","variant","device"]},"BacklogDesignComparison":{"type":"object","additionalProperties":false,"properties":{"original":{"anyOf":[{"$ref":"#/components/schemas/BacklogDesignComparisonRef"},{"type":"null"}]},"variant":{"anyOf":[{"$ref":"#/components/schemas/BacklogDesignComparisonRef"},{"type":"null"}]},"device":{"type":["string","null"],"enum":["desktop","mobile",null]},"alternative":{"anyOf":[{"$ref":"#/components/schemas/BacklogDesignComparisonPair"},{"type":"null"}]}},"required":["original","variant","device","alternative"]},"BacklogFieldDefinition":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":50,"description":"The shop's own identifier for the field. Unique per shop, and the key used in custom_fields."},"label":{"type":"string","maxLength":120},"type":{"type":"string","enum":["short_text","long_text","number","boolean","single_choice","date","url","person"]},"options":{"type":"array","items":{"type":"string"},"description":"Choices for a single_choice field; empty for every other type."},"required":{"type":"boolean"},"client_visible":{"type":"boolean","description":"Only client-visible fields leave Apex through the Research Hub read."},"position":{"type":"integer","minimum":0},"archived_at":{"type":["string","null"],"format":"date-time","description":"An archived field keeps the values already stored on ideas, disappears from reads, and rejects new writes."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","label","type","options","required","client_visible","position","archived_at"]},"BacklogFieldCreate":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":50,"description":"Derived from the label when omitted."},"label":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["short_text","long_text","number","boolean","single_choice","date","url","person"]},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"maxItems":100},"required":{"type":"boolean","default":false},"client_visible":{"type":"boolean","default":false}},"description":"A new field lands after the existing ones; the reorder call places it.","required":["label","type"],"allOf":[{"if":{"properties":{"type":{"const":"single_choice"}},"required":["type"]},"then":{"required":["options"],"properties":{"options":{"minItems":1}}}},{"if":{"properties":{"type":{"not":{"const":"single_choice"}}},"required":["type"]},"then":{"properties":{"options":{"maxItems":0}}}}]},"BacklogFieldOrder":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":0,"maximum":9999}},"required":["id","position"]}},"BacklogFieldUpdate":{"type":"object","additionalProperties":false,"description":"key and type are immutable: changing either would invalidate every value already stored under the old contract. position is not here either: PATCH /backlog/fields is the one writer of sheet order, because only it sees the whole sheet and can refuse two fields on one place. Restoring an archived field counts against the 50 live fields and answers 400 when the shop is already at the cap.","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"maxItems":100},"required":{"type":"boolean"},"client_visible":{"type":"boolean"},"archived":{"type":"boolean"}}},"BacklogDecision":{"type":"object","description":"What a decision surface may show about an idea. Approve and reject both answer with this shape.","properties":{"id":{"type":"string","format":"uuid"},"decision":{"type":["string","null"],"enum":["approved","rejected",null]},"roadmapMonth":{"type":["string","null"],"description":"The month the idea runs in, as YYYY-MM."},"note":{"type":["string","null"],"description":"The comment on an approval, or the reason on a rejection."},"reasonCategory":{"type":["string","null"],"enum":["not_right_for_brand","already_tested","too_much_effort","other",null]},"decidedByRole":{"type":["string","null"],"enum":["client","manager",null]},"decidedById":{"type":["string","null"],"format":"uuid"},"decidedAt":{"type":["string","null"],"format":"date-time"},"clientPriority":{"type":["string","null"],"enum":["low","normal","high",null]}},"required":["id","decision","roadmapMonth","note","reasonCategory","decidedByRole","decidedById","decidedAt","clientPriority"]},"BacklogItemDetail":{"allOf":[{"$ref":"#/components/schemas/BacklogItem"},{"type":"object","required":["score_sources"]}]},"BacklogCreate":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":["string","null"],"maxLength":10000},"status":{"type":"string","enum":["rough_idea","finished_concept","approved"]},"action_type":{"type":"string","enum":["ab_test","price_test","shipping_test","landing_page"]},"source":{"type":"string","minLength":1,"maxLength":80},"source_kind":{"type":"string","enum":["manual","customer","drip","research_hub"]},"source_id":{"type":["string","null"],"maxLength":255},"source_label":{"type":["string","null"],"maxLength":255},"provenance":{},"research_hub_brand_id":{"type":["string","null"],"maxLength":255},"research_hub_idea_id":{"type":["string","null"],"maxLength":255},"logic_map_artifact_id":{"type":["string","null"],"maxLength":255},"logic_map_status":{"type":"string","minLength":1,"maxLength":80},"test_plan_artifact_id":{"type":["string","null"],"maxLength":255},"hypothesis":{"type":["string","null"],"maxLength":10000},"page_label":{"type":["string","null"],"maxLength":255,"description":"Page the idea targets. Free text is mapped to a canonical page: a genome surface id (homepage, plp, pdp, cart, checkout, search, navigation, landing_page, quiz_lead_capture, ads, post_purchase, account, sitewide, other) or one of the shop's own page names. Text that names no known page is stored as null and returned in warnings."},"page_url":{"type":["string","null"],"maxLength":2000},"device":{"type":["string","null"],"maxLength":80,"description":"Device the idea targets. Free text is mapped to all, mobile, or desktop; naming both devices or responsive design maps to all. Text that names no device is stored as null and returned in warnings."},"audience":{"type":["string","null"],"maxLength":255},"psychological_direction":{"type":["string","null"],"maxLength":255},"psychological_tactic":{"type":["string","null"],"maxLength":255},"planned_launch_month":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Planned launch month as YYYY-MM. Drives the season feature in genome predictions."},"neednavigator_tags":{"type":"array","items":{}},"research_type":{"type":"array","items":{}},"research_notes":{"type":["string","null"],"maxLength":20000},"research_indication":{"type":["string","null"],"maxLength":10000},"variation_brief":{"type":["string","null"],"maxLength":20000},"landing_page_brief":{},"price_shipping_brief":{},"expected_revenue_impact":{"type":["number","null"],"minimum":0,"maximum":100},"ease_of_implementation":{"type":["integer","null"],"minimum":0,"maximum":10},"expert_review_score":{"type":["integer","null"],"minimum":0,"maximum":10},"feature_visibility_score":{"type":["integer","null"],"minimum":0,"maximum":10},"research_score":{"type":["number","null"],"minimum":0,"maximum":100},"learning_score":{"type":["number","null"],"minimum":0,"maximum":100},"computed_score":{"type":["number","null"],"minimum":0,"maximum":100},"score_breakdown":{},"score_source":{"type":"string","maxLength":80},"score_version":{"type":["string","null"],"maxLength":80},"due_date":{"type":["string","null"],"format":"date-time"},"campaign_start_at":{"type":["string","null"],"format":"date-time"},"campaign_end_at":{"type":["string","null"],"format":"date-time"},"owner_user_id":{"type":["string","null"],"format":"uuid"},"sketch_refs":{"type":"array","items":{}},"asset_refs":{"type":"array","items":{}},"tags":{"type":"array","items":{}},"metadata":{},"custom_fields":{"type":"object","additionalProperties":true,"description":"Values for the shop's own fields, keyed by field key. Each value is validated against its definition from /backlog/fields; a wrong type answers 422 naming the key. On PATCH, a null clears one value and unnamed fields are left alone."}},"required":["title"]},"BacklogUpdate":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":["string","null"],"maxLength":10000},"status":{"type":"string","enum":["rough_idea","finished_concept","approved"]},"action_type":{"type":"string","enum":["ab_test","price_test","shipping_test","landing_page"]},"source":{"type":"string","minLength":1,"maxLength":80},"source_kind":{"type":"string","enum":["manual","customer","drip","research_hub"]},"source_id":{"type":["string","null"],"maxLength":255},"source_label":{"type":["string","null"],"maxLength":255},"provenance":{},"research_hub_brand_id":{"type":["string","null"],"maxLength":255},"research_hub_idea_id":{"type":["string","null"],"maxLength":255},"logic_map_artifact_id":{"type":["string","null"],"maxLength":255},"logic_map_status":{"type":"string","minLength":1,"maxLength":80},"test_plan_artifact_id":{"type":["string","null"],"maxLength":255},"hypothesis":{"type":["string","null"],"maxLength":10000},"page_label":{"type":["string","null"],"maxLength":255,"description":"Page the idea targets. Free text is mapped to a canonical page: a genome surface id (homepage, plp, pdp, cart, checkout, search, navigation, landing_page, quiz_lead_capture, ads, post_purchase, account, sitewide, other) or one of the shop's own page names. Text that names no known page is stored as null and returned in warnings."},"page_url":{"type":["string","null"],"maxLength":2000},"device":{"type":["string","null"],"maxLength":80,"description":"Device the idea targets. Free text is mapped to all, mobile, or desktop; naming both devices or responsive design maps to all. Text that names no device is stored as null and returned in warnings."},"audience":{"type":["string","null"],"maxLength":255},"psychological_direction":{"type":["string","null"],"maxLength":255},"psychological_tactic":{"type":["string","null"],"maxLength":255},"planned_launch_month":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Planned launch month as YYYY-MM. Drives the season feature in genome predictions."},"neednavigator_tags":{"type":"array","items":{}},"research_type":{"type":"array","items":{}},"research_notes":{"type":["string","null"],"maxLength":20000},"research_indication":{"type":["string","null"],"maxLength":10000},"variation_brief":{"type":["string","null"],"maxLength":20000},"landing_page_brief":{},"price_shipping_brief":{},"expected_revenue_impact":{"type":["number","null"],"minimum":0,"maximum":100},"ease_of_implementation":{"type":["integer","null"],"minimum":0,"maximum":10},"expert_review_score":{"type":["integer","null"],"minimum":0,"maximum":10},"feature_visibility_score":{"type":["integer","null"],"minimum":0,"maximum":10},"research_score":{"type":["number","null"],"minimum":0,"maximum":100},"learning_score":{"type":["number","null"],"minimum":0,"maximum":100},"computed_score":{"type":["number","null"],"minimum":0,"maximum":100},"score_breakdown":{},"score_source":{"type":"string","maxLength":80},"score_version":{"type":["string","null"],"maxLength":80},"due_date":{"type":["string","null"],"format":"date-time"},"campaign_start_at":{"type":["string","null"],"format":"date-time"},"campaign_end_at":{"type":["string","null"],"format":"date-time"},"owner_user_id":{"type":["string","null"],"format":"uuid"},"sketch_refs":{"type":"array","items":{}},"asset_refs":{"type":"array","items":{}},"tags":{"type":"array","items":{}},"metadata":{},"custom_fields":{"type":"object","additionalProperties":true,"description":"Values for the shop's own fields, keyed by field key. Each value is validated against its definition from /backlog/fields; a wrong type answers 422 naming the key. On PATCH, a null clears one value and unnamed fields are left alone."},"expected_version":{"oneOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"string","pattern":"^[1-9][0-9]*$"}],"description":"Version returned by the latest backlog item read. A stale value returns a 409 with error.code backlog_item_cas_miss; values above 2147483647 are rejected as invalid."},"research_hub_round_trip":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["request_drip_workout","mark_push_pending","mark_pushed","mark_failed","cancel"]},"status":{"type":"string","enum":["requested","pending","pushed","failed","cancelled"]},"message":{"type":["string","null"],"maxLength":5000},"reason":{"type":["string","null"],"maxLength":1000},"research_hub_brand_id":{"type":["string","null"],"maxLength":255},"research_hub_idea_id":{"type":["string","null"],"maxLength":255},"request_id":{"type":["string","null"],"maxLength":255},"remote_url":{"type":["string","null"],"maxLength":2000},"remote_id":{"type":["string","null"],"maxLength":255},"payload":{}},"required":["action"]}}},"Signal":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"description":{"type":["string","null"]},"source":{"type":"string"},"value_type":{"type":"string"},"privacy_level":{"type":"string"},"runtimes":{"type":"array","items":{"type":"string"}},"ttl_days":{"type":["integer","null"]},"capture":{"type":"object"},"examples":{"type":"array","items":{}},"is_dimension":{"type":"boolean"},"value_labels":{"type":"object","additionalProperties":{"type":"string"}},"usage_notes":{"type":["string","null"]},"status":{"type":"string"},"is_built_in":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","key","label","source","value_type","privacy_level","runtimes","status","is_built_in","is_dimension","value_labels"]},"SignalCreate":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$"},"label":{"type":"string","minLength":1,"maxLength":255},"description":{"type":["string","null"],"maxLength":2000},"source":{"type":"string","enum":["url","traffic","device","shopify","surface","behavior","cart","search","consent","custom"]},"value_type":{"type":"string","enum":["string","number","boolean","string_array","json"]},"privacy_level":{"type":"string","enum":["anonymous","pseudonymous","customer"]},"runtimes":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","enum":["edge","client","pixel","server"]}},"ttl_days":{"type":["integer","null"],"minimum":1,"maximum":730},"capture":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["manual","url_parameter","dom_selector","global","data_layer","event_property","click_selector"]},"parameter":{"type":"string","minLength":1,"maxLength":120},"dataLayerName":{"type":"string","minLength":1,"maxLength":120},"eventName":{"oneOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1,"maxLength":160}}]},"from":{"oneOf":[{"type":"string","minLength":1,"maxLength":240},{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1,"maxLength":240}}]},"transform":{"type":"object","additionalProperties":false,"properties":{"trim":{"type":"boolean"},"lowercase":{"type":"boolean"},"map":{"type":"object","additionalProperties":{"type":"string"}},"scale":{"type":"number"},"default":{"oneOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"}]}}},"property":{"type":"string","minLength":1,"maxLength":160},"selector":{"type":"string","minLength":1,"maxLength":500},"source":{"type":"string","enum":["text","attribute","dataset","constant"]},"attribute":{"type":"string","minLength":1,"maxLength":160},"value":{"oneOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"}]},"path":{"type":"string","minLength":1,"maxLength":240},"persist":{"type":"boolean"}},"required":["mode"],"allOf":[{"if":{"properties":{"mode":{"const":"data_layer"}},"required":["mode"]},"then":{"required":["eventName","from"]}},{"if":{"properties":{"mode":{"const":"url_parameter"}},"required":["mode"]},"then":{"required":["parameter"]}},{"if":{"properties":{"mode":{"const":"dom_selector"}},"required":["mode"]},"then":{"required":["selector"]}},{"if":{"properties":{"mode":{"const":"global"}},"required":["mode"]},"then":{"required":["path"]}},{"if":{"properties":{"mode":{"const":"event_property"}},"required":["mode"]},"then":{"required":["eventName","property"],"properties":{"eventName":{"type":"string","minLength":1,"maxLength":160}}}},{"if":{"properties":{"mode":{"const":"click_selector"}},"required":["mode"]},"then":{"required":["selector"]}}]},"examples":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":500}},"usage_notes":{"type":["string","null"],"maxLength":2000},"is_dimension":{"type":"boolean","default":false},"value_labels":{"type":"object","additionalProperties":{"type":"string"},"default":{}}},"required":["key","label"]},"SignalUpdate":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$"},"label":{"type":"string","minLength":1,"maxLength":255},"description":{"type":["string","null"],"maxLength":2000},"source":{"type":"string","enum":["url","traffic","device","shopify","surface","behavior","cart","search","consent","custom"]},"value_type":{"type":"string","enum":["string","number","boolean","string_array","json"]},"privacy_level":{"type":"string","enum":["anonymous","pseudonymous","customer"]},"runtimes":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","enum":["edge","client","pixel","server"]}},"ttl_days":{"type":["integer","null"],"minimum":1,"maximum":730},"capture":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["manual","url_parameter","dom_selector","global","data_layer","event_property","click_selector"]},"parameter":{"type":"string","minLength":1,"maxLength":120},"dataLayerName":{"type":"string","minLength":1,"maxLength":120},"eventName":{"oneOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1,"maxLength":160}}]},"from":{"oneOf":[{"type":"string","minLength":1,"maxLength":240},{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1,"maxLength":240}}]},"transform":{"type":"object","additionalProperties":false,"properties":{"trim":{"type":"boolean"},"lowercase":{"type":"boolean"},"map":{"type":"object","additionalProperties":{"type":"string"}},"scale":{"type":"number"},"default":{"oneOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"}]}}},"property":{"type":"string","minLength":1,"maxLength":160},"selector":{"type":"string","minLength":1,"maxLength":500},"source":{"type":"string","enum":["text","attribute","dataset","constant"]},"attribute":{"type":"string","minLength":1,"maxLength":160},"value":{"oneOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"}]},"path":{"type":"string","minLength":1,"maxLength":240},"persist":{"type":"boolean"}},"required":["mode"],"allOf":[{"if":{"properties":{"mode":{"const":"data_layer"}},"required":["mode"]},"then":{"required":["eventName","from"]}},{"if":{"properties":{"mode":{"const":"url_parameter"}},"required":["mode"]},"then":{"required":["parameter"]}},{"if":{"properties":{"mode":{"const":"dom_selector"}},"required":["mode"]},"then":{"required":["selector"]}},{"if":{"properties":{"mode":{"const":"global"}},"required":["mode"]},"then":{"required":["path"]}},{"if":{"properties":{"mode":{"const":"event_property"}},"required":["mode"]},"then":{"required":["eventName","property"],"properties":{"eventName":{"type":"string","minLength":1,"maxLength":160}}}},{"if":{"properties":{"mode":{"const":"click_selector"}},"required":["mode"]},"then":{"required":["selector"]}}]},"examples":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":500}},"usage_notes":{"type":["string","null"],"maxLength":2000},"is_dimension":{"type":"boolean","default":false},"value_labels":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"status":{"type":"string","enum":["active","archived"]}}},"AdminStratifiedResult":{"type":"object","additionalProperties":false,"required":["experiment_id","experiment_name","experiment_status","shop_id","shop_name","shop_domain","strata","hybrid","formula","assumptions","rounding"],"properties":{"experiment_id":{"type":"string"},"experiment_name":{"type":"string"},"experiment_status":{"type":"string"},"shop_id":{"type":"string"},"shop_name":{"type":"string"},"shop_domain":{"type":"string"},"strata":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","label","status","denominator","aggregate_only","total_visitors","total_orders","arms","srm"],"properties":{"id":{"type":"string","enum":["consented_visitor","logged_in","rail_only"]},"label":{"type":"string"},"status":{"type":"string","enum":["available","no_data"]},"denominator":{"type":"string","enum":["distinct_visitors","served_count"]},"aggregate_only":{"type":"boolean"},"total_visitors":{"type":["number","null"]},"total_orders":{"type":["number","null"]},"arms":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["variation_id","name","is_control","visitors","orders","order_rate","lift","suppressed"],"properties":{"variation_id":{"type":"string"},"name":{"type":"string"},"is_control":{"type":"boolean"},"visitors":{"type":["number","null"]},"orders":{"type":["number","null"]},"order_rate":{"type":["number","null"]},"lift":{"type":["number","null"]},"suppressed":{"type":"boolean"}}}},"srm":{"type":"object","additionalProperties":false,"required":["status","p_value","design_effect","threshold"],"properties":{"status":{"type":"string","enum":["pass","mismatch","insufficient"]},"p_value":{"type":["number","null"]},"design_effect":{"type":"number"},"threshold":{"type":"number"}}}}}},"hybrid":{"type":["array","null"],"items":{"type":"object","additionalProperties":false,"required":["treatment_variation_id","treatment_name","lift","reason","weights"],"properties":{"treatment_variation_id":{"type":"string"},"treatment_name":{"type":"string"},"lift":{"type":["number","null"]},"reason":{"type":["string","null"],"enum":["missing_order_bearing_stratum_lift",null]},"weights":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["stratum","weight","lift"],"properties":{"stratum":{"type":"string","enum":["consented_visitor","logged_in","rail_only"]},"weight":{"type":"number"},"lift":{"type":["number","null"]}}}}}}},"formula":{"type":"string"},"assumptions":{"type":"array","items":{"type":"string"}},"rounding":{"type":"object","additionalProperties":false,"required":["aggregate_only_nearest","suppress_below_visitors"],"properties":{"aggregate_only_nearest":{"type":"integer","const":10},"suppress_below_visitors":{"type":"integer","const":10}}}}},"WorkspaceBuildResult":{"type":"object","properties":{"ok":{"type":"boolean"},"mutationCount":{"type":"integer"},"customCssBytes":{"type":"integer"},"customJsBytes":{"type":"integer"},"artifacts":{"type":"object"},"attachedGoalIds":{"type":"array","items":{"type":"string","format":"uuid"}},"driftBefore":{"type":"object"},"drift":{"type":"object"},"saved":{"type":"boolean"},"artifact_hash":{"type":"string","nullable":true},"publication":{"type":["object","null"],"additionalProperties":false,"required":["status","code","message"],"properties":{"status":{"type":"string","enum":["ok","pending","warning","failed"]},"code":{"type":"string"},"message":{"type":"string"}}},"warnings":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Legacy summary containing the first blocking issue message."},"code":{"type":"string","description":"Machine-readable failure code when the build is not successful."},"blockingIssues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["blocking","warning"]},"message":{"type":"string"},"field":{"type":"string"},"evidence":{"oneOf":[{"type":"string"},{"type":"array","items":{}},{"type":"object"}],"description":"Bounded validator evidence emitted as a message or placeholder string, a list of runtime-risk reasons or preview records, or structured matched-construct, snippet, URL, and source-location details."}},"required":["code","severity","message"]}},"warningIssues":{"type":"array","items":{"type":"object"}}},"required":["ok"]},"Page":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","minLength":1},"key":{"type":["string","null"]},"description":{"type":["string","null"]},"url_pattern":{"type":"string","minLength":1},"pattern_type":{"type":"string","enum":["exact","wildcard","regex"]},"match_type":{"type":"string","enum":["exact","contains","wildcard","regex"]},"include_rules":{},"exclude_rules":{},"advanced_condition":{},"trigger":{"type":"object","additionalProperties":true,"properties":{"mode":{"type":"string","enum":["immediate","history","polling","dom","manual-callback","manual-api"]},"pollOnRules":{"type":"boolean"},"disabled":{"type":"boolean"},"alwaysEmbedInSnippet":{"type":"boolean"},"deactivationMode":{"type":"string","enum":["reset","deactivate","force-reset","persistent"]},"triggerJs":{"type":["string","null"],"maxLength":8000}},"required":["mode","pollOnRules"]},"disabled":{"type":"boolean"},"status":{"type":"string"},"metadata":{},"rule_summary":{"type":"string"},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}},"propagation_warning":{"type":"object","description":"The Page write remains saved, but one or more stale targeting consumers could not refresh their stored Page snapshot.","additionalProperties":false,"required":["code","message","skipped_consumers"],"properties":{"code":{"type":"string","enum":["targeting_reexpansion_incomplete"]},"message":{"type":"string"},"skipped_consumers":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["consumer","id","reason"],"properties":{"consumer":{"type":"string","enum":["experiment","feature_flag","personalization","personalization_rule"]},"id":{"type":"string"},"reason":{"type":"string"}}}}}},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","url_pattern"]},"PageInput":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","minLength":1},"key":{"type":"string"},"description":{"type":["string","null"]},"url_pattern":{"type":"string","minLength":1},"pattern_type":{"type":"string","enum":["exact","wildcard","regex"]},"match_type":{"type":"string","enum":["exact","contains","wildcard","regex"]},"include_rules":{},"exclude_rules":{},"advanced_condition":{},"trigger":{"type":"object","additionalProperties":true,"properties":{"mode":{"type":"string","enum":["immediate","history","polling","dom","manual-callback","manual-api"]},"pollOnRules":{"type":"boolean"},"disabled":{"type":"boolean"},"alwaysEmbedInSnippet":{"type":"boolean"},"deactivationMode":{"type":"string","enum":["reset","deactivate","force-reset","persistent"]},"triggerJs":{"type":["string","null"],"maxLength":8000}}},"disabled":{"type":"boolean"}},"required":["name","url_pattern"]},"PageUpdateInput":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","minLength":1},"key":{"type":"string"},"description":{"type":["string","null"]},"url_pattern":{"type":"string","minLength":1},"pattern_type":{"type":"string","enum":["exact","wildcard","regex"]},"match_type":{"type":"string","enum":["exact","contains","wildcard","regex"]},"include_rules":{},"exclude_rules":{},"advanced_condition":{},"trigger":{"type":"object","additionalProperties":true,"properties":{"mode":{"type":"string","enum":["immediate","history","polling","dom","manual-callback","manual-api"]},"pollOnRules":{"type":"boolean"},"disabled":{"type":"boolean"},"alwaysEmbedInSnippet":{"type":"boolean"},"deactivationMode":{"type":"string","enum":["reset","deactivate","force-reset","persistent"]},"triggerJs":{"type":["string","null"],"maxLength":8000}}},"disabled":{"type":"boolean"},"status":{"type":"string","enum":["active","archived"]},"confirm_live_disable":{"type":"boolean","description":"Required as true to disable a page currently used by a running experiment; the PATCH is rejected otherwise. On the disable path a bare confirmation covers whatever is live at write time. It does NOT suffice for a trigger change on its own: a trigger change is only covered when confirmed_consumer_ids names every consumer listed in the 409 (with this flag or confirm_live_impact set), and omitting the ids yields a fresh 409."},"confirm_live_impact":{"type":"boolean","description":"Required as true to disable a page or change its trigger while running experiments, feature flags, or personalizations target it; the PATCH is rejected with 409 otherwise. A trigger change can stop delivery while goals keep attributing."},"confirmed_consumer_ids":{"type":"array","items":{"type":"string"},"description":"Ids of the live consumers listed in the 409 that is being confirmed. The server re-checks the live set inside the write transaction and answers with a fresh 409 when it now contains a consumer outside this list. A confirm_live_impact request that omits this field names nothing and is read as the empty confirmed set, so any live consumer yields a fresh 409; only the legacy confirm_live_disable flag on the disable path still covers whatever is live at write time."}}},"Segment":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"key":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["page","traffic","behavior","customer","custom"],"default":"page"},"rules":{"type":"object","description":"Empty Page rules represent Whole site. Other segment types require at least one flat condition or one non-empty condition group.","additionalProperties":false,"required":["version","operator","conditions"],"properties":{"version":{"type":"integer","const":1},"operator":{"type":"string","enum":["and","or"]},"conditions":{"type":"array","items":{"type":"object","required":["signal","operator"],"properties":{"signal":{"type":"string"},"operator":{"type":"string"},"value":{"description":"Condition value. Operators that require a value (equals, not_equals, contains, greater_than, …) reject empty or whitespace-only values with 400; valueless operators (is_set, is_empty) accept an omitted value.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"allOf":[{"if":{"properties":{"operator":{"not":{"enum":["is_set","is_empty"]}}},"required":["operator"]},"then":{"required":["value"],"properties":{"value":{"oneOf":[{"type":"string","minLength":1},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string","minLength":1},"minItems":1}]}}}}]}},"groups":{"type":"array","maxItems":8,"items":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"object","required":["signal","operator"],"properties":{"signal":{"type":"string"},"operator":{"type":"string"},"value":{"description":"Condition value. Operators that require a value (equals, not_equals, contains, greater_than, …) reject empty or whitespace-only values with 400; valueless operators (is_set, is_empty) accept an omitted value.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"allOf":[{"if":{"properties":{"operator":{"not":{"enum":["is_set","is_empty"]}}},"required":["operator"]},"then":{"required":["value"],"properties":{"value":{"oneOf":[{"type":"string","minLength":1},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string","minLength":1},"minItems":1}]}}}}]}}}}},"priority":{"type":"integer","minimum":0,"maximum":10000},"metadata":{"type":["object","null"]},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","rules"]},"SegmentInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"key":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["page","traffic","behavior","customer","custom"],"default":"page"},"rules":{"type":"object","description":"Empty Page rules represent Whole site. Other segment types require at least one flat condition or one non-empty condition group.","additionalProperties":false,"required":["version","operator","conditions"],"properties":{"version":{"type":"integer","const":1},"operator":{"type":"string","enum":["and","or"]},"conditions":{"type":"array","items":{"type":"object","required":["signal","operator"],"properties":{"signal":{"type":"string"},"operator":{"type":"string"},"value":{"description":"Condition value. Operators that require a value (equals, not_equals, contains, greater_than, …) reject empty or whitespace-only values with 400; valueless operators (is_set, is_empty) accept an omitted value.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"allOf":[{"if":{"properties":{"operator":{"not":{"enum":["is_set","is_empty"]}}},"required":["operator"]},"then":{"required":["value"],"properties":{"value":{"oneOf":[{"type":"string","minLength":1},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string","minLength":1},"minItems":1}]}}}}]}},"groups":{"type":"array","maxItems":8,"items":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"object","required":["signal","operator"],"properties":{"signal":{"type":"string"},"operator":{"type":"string"},"value":{"description":"Condition value. Operators that require a value (equals, not_equals, contains, greater_than, …) reject empty or whitespace-only values with 400; valueless operators (is_set, is_empty) accept an omitted value.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"allOf":[{"if":{"properties":{"operator":{"not":{"enum":["is_set","is_empty"]}}},"required":["operator"]},"then":{"required":["value"],"properties":{"value":{"oneOf":[{"type":"string","minLength":1},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string","minLength":1},"minItems":1}]}}}}]}}}}},"priority":{"type":"integer","minimum":0,"maximum":10000},"metadata":{"type":["object","null"]}},"required":["name","rules"],"allOf":[{"if":{"required":["type"],"properties":{"type":{"enum":["traffic","behavior","customer","custom"]}}},"then":{"properties":{"rules":{"anyOf":[{"properties":{"conditions":{"type":"array","minItems":1}}},{"required":["groups"],"properties":{"groups":{"type":"array","minItems":1}}}]}}}}]},"SegmentUpdateInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"key":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["page","traffic","behavior","customer","custom"]},"rules":{"type":"object","description":"Empty Page rules represent Whole site. Other segment types require at least one flat condition or one non-empty condition group.","additionalProperties":false,"required":["version","operator","conditions"],"properties":{"version":{"type":"integer","const":1},"operator":{"type":"string","enum":["and","or"]},"conditions":{"type":"array","items":{"type":"object","required":["signal","operator"],"properties":{"signal":{"type":"string"},"operator":{"type":"string"},"value":{"description":"Condition value. Operators that require a value (equals, not_equals, contains, greater_than, …) reject empty or whitespace-only values with 400; valueless operators (is_set, is_empty) accept an omitted value.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"allOf":[{"if":{"properties":{"operator":{"not":{"enum":["is_set","is_empty"]}}},"required":["operator"]},"then":{"required":["value"],"properties":{"value":{"oneOf":[{"type":"string","minLength":1},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string","minLength":1},"minItems":1}]}}}}]}},"groups":{"type":"array","maxItems":8,"items":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"object","required":["signal","operator"],"properties":{"signal":{"type":"string"},"operator":{"type":"string"},"value":{"description":"Condition value. Operators that require a value (equals, not_equals, contains, greater_than, …) reject empty or whitespace-only values with 400; valueless operators (is_set, is_empty) accept an omitted value.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"allOf":[{"if":{"properties":{"operator":{"not":{"enum":["is_set","is_empty"]}}},"required":["operator"]},"then":{"required":["value"],"properties":{"value":{"oneOf":[{"type":"string","minLength":1},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string","minLength":1},"minItems":1}]}}}}]}}}}},"priority":{"type":"integer","minimum":0,"maximum":10000},"metadata":{"type":["object","null"]},"status":{"type":"string","enum":["active","archived"]}},"allOf":[{"if":{"required":["type"],"properties":{"type":{"enum":["traffic","behavior","customer","custom"]}}},"then":{"properties":{"rules":{"anyOf":[{"properties":{"conditions":{"type":"array","minItems":1}}},{"required":["groups"],"properties":{"groups":{"type":"array","minItems":1}}}]}}}}],"description":"Omitted type retains the saved segment type. Rules or type changes are validated against the merged saved segment. Empty rules are valid only for Pages. Metadata-only and archive-only updates preserve legacy rules."},"ExclusionGroup":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"assignmentEpoch":{"type":"integer"},"assignmentEpochStartedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"},"archived_by":{"type":["string","null"]},"members":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"experimentId":{"type":"string","format":"uuid"},"experiment_id":{"type":"string","format":"uuid"},"share":{"type":"number","minimum":0,"maximum":100},"traffic_share":{"type":"number","minimum":0,"maximum":1},"experiment":{"type":["object","null"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"testKey":{"type":["string","null"]},"status":{"type":"string"},"targeting":{},"trafficAllocation":{"type":["number","null"]},"archived":{"type":"boolean"},"participating":{"type":"boolean"}},"required":["id","name","testKey","status","targeting","trafficAllocation","archived","participating"]}},"required":["id","experimentId","experiment_id","share","traffic_share","experiment"]}},"memberCount":{"type":"integer"},"runningCount":{"type":"integer"},"nonParticipatingCount":{"type":"integer"},"trafficTotal":{"type":"number"},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}}},"required":["id","name","assignmentEpoch","createdAt","updatedAt","members","memberCount","runningCount","nonParticipatingCount","trafficTotal"]},"ExclusionGroupInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"]},"members":{"type":"array","minItems":2,"items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"experiment_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"traffic_share":{"type":"number","minimum":0,"maximum":1}},"required":["experiment_id","traffic_share"]},{"type":"object","additionalProperties":false,"properties":{"experimentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"share":{"type":"number","minimum":0,"maximum":100}},"required":["experimentId","share"]}]}}},"required":["name","members"]},"ExclusionGroupUpdateInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"]},"members":{"type":"array","minItems":2,"items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"experiment_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"traffic_share":{"type":"number","minimum":0,"maximum":1}},"required":["experiment_id","traffic_share"]},{"type":"object","additionalProperties":false,"properties":{"experimentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"share":{"type":"number","minimum":0,"maximum":100}},"required":["experimentId","share"]}]}}}},"ExclusionGroupMembersInput":{"type":"object","additionalProperties":false,"properties":{"members":{"type":"array","minItems":2,"items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"experiment_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"traffic_share":{"type":"number","minimum":0,"maximum":1}},"required":["experiment_id","traffic_share"]},{"type":"object","additionalProperties":false,"properties":{"experimentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"share":{"type":"number","minimum":0,"maximum":100}},"required":["experimentId","share"]}]}}},"required":["members"]},"FunnelStep":{"type":"object","additionalProperties":false,"properties":{"order":{"type":"number"},"page_id":{"type":"string"},"url_pattern":{"type":"string"},"label":{"type":"string"}},"required":["order","url_pattern","label"]},"Funnel":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/FunnelStep"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"},"archived_by":{"type":["string","null"]}},"required":["id","name","steps"]},"FunnelInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"steps":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/FunnelStep"}}},"required":["name","steps"]},"FunnelUpdateInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"steps":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/FunnelStep"}}}},"FunnelRun":{"type":"object","additionalProperties":false,"properties":{"total_sessions_analyzed":{"type":"integer","description":"Number of analyzed sessions. The first step's drop-off rate uses distinct visitors across these sessions as its predecessor population."},"steps":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"step":{"type":"integer"},"label":{"type":"string"},"url_pattern":{"type":"string"},"visitors":{"type":"integer"},"drop_off_rate":{"type":"number","description":"Percentage of the predecessor population that did not reach this step. For the first step, the predecessor population is distinct analyzed visitors; later steps use visitors from the previous step."},"matched_pageviews":{"type":"integer"}},"required":["step","label","url_pattern","visitors","drop_off_rate","matched_pageviews"]}}},"required":["steps","total_sessions_analyzed"]},"Goal":{"properties":{"archived_at":{"format":"date-time","type":["string","null"]},"archived_by":{"type":["string","null"]},"capture":{"description":"Data capture rules — extract element data when goal fires","items":{"$ref":"#/components/schemas/GoalCapture"},"type":["array","null"]},"count_once":{"type":"boolean"},"created_at":{"format":"date-time","type":"string"},"event_name":{"type":["string","null"]},"filter":{"anyOf":[{"$ref":"#/components/schemas/GoalFilter"},{"type":"null"}]},"id":{"format":"uuid","type":"string"},"measurement":{"description":"Read-time analysis model. Any goal type may use conversion or value measurement; count_once independently selects first-per-visitor or every-event contribution.","enum":["conversion","value"],"type":"string"},"name":{"type":"string"},"page_id":{"description":"Optional Page scope. Required for new click goals and not allowed for custom or revenue goals.","format":"uuid","type":["string","null"]},"publication_warning":{"additionalProperties":false,"description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","properties":{"code":{"enum":["storefront_publication_incomplete"],"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"selector":{"type":["string","null"]},"text_match":{"description":"Case-insensitive text match for click goals","type":["string","null"]},"type":{"enum":["click","pageview","custom","revenue"],"type":"string"},"url_pattern":{"type":["string","null"]},"value_property":{"description":"Numeric event property read for value goals. Null preserves the revenue-column source. Not supported on revenue goals.","maxLength":120,"type":["string","null"]},"value_unit":{"description":"Display unit for a value goal; malformed stored values degrade to number.","enum":["currency","number","duration_seconds","percent",null],"type":["string","null"]}},"required":["id","name","type","measurement","count_once","created_at"],"type":"object"},"PaginationMeta":{"properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["has_more","next_cursor"],"type":"object"}}},"paths":{"/assign":{"get":{"summary":"Get deterministic server-side assignments","tags":["Assignments"],"servers":[{"url":"https://events.drip-apex.com/v1"}],"parameters":[{"name":"shop_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri"}},{"name":"environment","in":"query","required":false,"schema":{"type":"string"}},{"name":"experiments","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Assignments and program cohort returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerAssignmentResponse"}}}},"400":{"description":"Invalid request, including a customer identifier supplied in the query string instead of a POST body.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AssignGetCustomerIdError"},{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Get deterministic assignments with commerce proof inputs","tags":["Assignments"],"servers":[{"url":"https://events.drip-apex.com/v1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["shop_id"],"anyOf":[{"required":["user_id"]},{"required":["logged_in_customer_id"]},{"required":["customer_id"]}],"properties":{"shop_id":{"type":"string"},"user_id":{"type":"string"},"logged_in_customer_id":{"type":"string","description":"Shopify customer id in decimal or gid://shopify/Customer/<id> form. Send the raw string to avoid integer precision loss."},"customer_id":{"type":"string","deprecated":true,"description":"Alias for logged_in_customer_id. Send the raw string to avoid integer precision loss."},"decision_use":{"type":"string","enum":["aggregate","individual"],"description":"Individual use is rejected with 403 when the gated Shopify customer identity is selected."},"url":{"type":"string","format":"uri"},"environment":{"type":"string"},"experiments":{"type":"array","items":{"type":"string"}},"cart_token":{"type":"string"},"persist_function_handoff":{"type":"boolean","description":"When true with a verified cart capability, persist the signed commerce authorization in the app-owned cart metafield read by Shopify Functions."},"exclusion_group_selections":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["group_id","experiment_id","epoch"],"properties":{"group_id":{"type":"string"},"experiment_id":{"type":"string"},"epoch":{"type":"integer","minimum":1}}}}}}}}},"responses":{"200":{"description":"Assignments, program cohort, and commerce authorization returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerAssignmentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"A logged-in customer assignment was requested for an individual-level decision.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/handover/verify":{"post":{"summary":"Verify a signed cross-domain bucketing handover token","description":"Worker runtime endpoint. Verifies the token signature, expiry, and shop binding without requiring ingest credentials.","tags":["Runtime"],"security":[],"servers":[{"url":"https://events.drip-apex.com/v1"}],"parameters":[{"name":"X-Drip-Shop","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["verifyToken"],"properties":{"verifyToken":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Verified handover payload","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Missing or invalid shop identifier"},"401":{"description":"Unsigned, forged, expired, or cross-shop handover token"},"500":{"description":"Handover verification is unavailable"}}}},"/experiments/conflicts":{"post":{"summary":"Inspect experiment conflicts","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["selectors"],"properties":{"selectors":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}},"exclude_experiment_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Conflict analysis","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/qa":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update experiment QA","responses":{"200":{"description":"QA updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"delete":{"summary":"Reset experiment QA","responses":{"200":{"description":"QA reset","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/qa/run":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read QA run","responses":{"200":{"description":"QA run, including QA destination URLs for goals on pages outside experiment targeting (goal-page entries in urls, and goalPageDestinations evidence on the qa_url_coverage checklist item)","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update QA run","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["runId"],"anyOf":[{"required":["itemId"]},{"required":["runNotes"]},{"required":["acceptanceCriteriaSummary"]}],"properties":{"runId":{"type":"string","minLength":1},"itemId":{"type":"string","minLength":1},"status":{"type":"string","enum":["pending","pass","warning","fail","accepted","skipped"]},"notes":{"type":"string","maxLength":5000},"evidence":{"type":"object","additionalProperties":true},"runNotes":{"type":"string","maxLength":10000},"acceptanceCriteriaSummary":{"type":["string","null"],"maxLength":5000}}}}}},"responses":{"200":{"description":"QA run updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Add a custom QA checklist item","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["runId","title"],"properties":{"runId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":140},"description":{"type":"string","maxLength":1000},"category":{"type":"string","maxLength":80},"required":{"type":"boolean"}}}}}},"responses":{"201":{"description":"QA checklist item created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"delete":{"summary":"Delete custom QA checklist item","parameters":[{"name":"runId","in":"query","schema":{"type":"string"}},{"name":"itemId","in":"query","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"runId":{"type":"string","minLength":1},"itemId":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"QA run deleted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/qa/evidence":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Attach or upload QA evidence","description":"Attaches a terminal screenshot job, writes typed evidence records, or uploads QA evidence images. Exactly one request form is accepted per call.","tags":["Experiments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["screenshot_job_id"],"properties":{"runId":{"type":"string","minLength":1},"screenshot_job_id":{"type":"string","minLength":1}}},{"type":"object","additionalProperties":false,"required":["records"],"properties":{"runId":{"type":"string","minLength":1},"records":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["kind","label"],"properties":{"kind":{"type":"string","enum":["screenshot","goal","summary","selector_audit","console_network","qa_audit","readiness"]},"label":{"type":"string","minLength":1,"maxLength":140},"status":{"type":"string","enum":["captured","passed","warning","failed","pending","not_run"],"default":"captured"},"device":{"type":"string","maxLength":40},"variationId":{"type":"string"},"source":{"type":"string","minLength":1,"maxLength":140,"pattern":"\\S","default":"api"},"capturedAt":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":true}}}}}}]}},"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"runId":{"type":"string"},"files":{"type":"array","minItems":1,"maxItems":6,"items":{"type":"string","format":"binary"}},"label":{"type":"string","maxLength":140},"device":{"type":"string","maxLength":40},"variation_id":{"type":"string"},"status":{"type":"string","enum":["captured","passed","warning","failed","pending","not_run"]},"kind":{"type":"string","enum":["screenshot","goal","summary","selector_audit","console_network","qa_audit","readiness"],"default":"screenshot"}}}}}},"responses":{"200":{"description":"Signed QA run with the updated evidence","content":{"application/json":{"schema":{"type":"object","required":["run"],"properties":{"run":{"type":"object","description":"Serialized QA run; recognized storage references in evidence are returned as signed URLs","properties":{"id":{"type":"string"},"status":{"type":"string"},"checklist":{"type":"array","items":{"type":"object"}},"automatedEvidence":{"type":["object","null"]},"evidenceRecords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"label":{"type":"string"},"status":{"type":"string"},"capturedAt":{"type":"string"},"device":{"type":["string","null"]},"variationId":{"type":["string","null"]},"source":{"type":["string","null"]},"payload":{"type":"object"}}}}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"description":"Evidence upload failed","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/start":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Retired experiment launch endpoint","description":"This endpoint is gone. Launch traffic through the dashboard approval workflow.","responses":{"410":{"description":"Launch is dashboard-only","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/harness/sessions":{"post":{"summary":"Create harness session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["experimentSlug","experimentName","variationSlug","variationName","targetUrl"],"properties":{"experimentId":{"type":"string"},"variationId":{"type":"string"},"experimentSlug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"},"experimentName":{"type":"string","minLength":1,"maxLength":255},"variationSlug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"},"variationName":{"type":"string","minLength":1,"maxLength":255},"targetUrl":{"type":"string","format":"uri"},"resetJs":{"type":["string","null"],"maxLength":200000},"antiFlickerSelectors":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":500}},"ttlSeconds":{"type":"integer","minimum":60,"maximum":86400}}}}}},"responses":{"201":{"description":"Harness session created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/harness/sessions/{id}/versions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Create harness session version","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["js"],"properties":{"js":{"type":"string","format":"binary"},"css":{"type":"string","format":"binary"},"manifest":{"type":"string","description":"JSON-encoded artifact metadata"}}}}}},"responses":{"201":{"description":"Version created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/preview-sessions":{"post":{"summary":"Create an artifact-injecting proxy preview session","description":"Requires a secret API key with experiments:write. The returned short-lived URL is a bearer capability that renders the selected draft variation without a dashboard session or installed Apex snippet.","tags":["Experiments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["experiment_id"],"properties":{"experiment_id":{"type":"string","description":"Experiment UUID or slug"},"variation_id":{"type":"string","description":"Variation UUID or slug; optional — defaults to the experiment's first non-control variation"},"target_url":{"type":"string","format":"uri","description":"Optional target; defaults to the experiment store URL"},"ttl_hours":{"type":"integer","minimum":1,"maximum":168,"default":168,"description":"Preview lifetime in hours"}}}}}},"responses":{"200":{"description":"Preview session","content":{"application/json":{"schema":{"type":"object","required":["session_id","preview_url","expires_at"],"properties":{"session_id":{"type":"string","format":"uuid"},"preview_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/admin/settings":{"get":{"tags":["Platform admin"],"summary":"Read allowlisted platform settings","description":"Requires an admin:read user API key and a live PlatformAccess row; environment email grants do not apply.","responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"guardian_enabled":{"type":"boolean"},"srm_check_enabled":{"type":"boolean"}},"required":["guardian_enabled","srm_check_enabled"]}},"required":["data"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"tags":["Platform admin"],"summary":"Update allowlisted platform settings","description":"Only guardian_enabled and srm_check_enabled are accepted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"guardian_enabled":{"type":"boolean"},"srm_check_enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Settings updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"guardian_enabled":{"type":"boolean"},"srm_check_enabled":{"type":"boolean"}},"required":["guardian_enabled","srm_check_enabled"]}},"required":["data"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/admin/shops/{id}/archive":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Platform admin"],"summary":"Archive a shop","description":"Requires an admin:write user API key and refuses shops with running, non-archived experiments.","responses":{"200":{"description":"Shop archived and delivery disabled","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Shop not found (pass-through orchestration body)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Shop has running, non-archived experiments","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"running_experiments":{"type":"integer"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"description":"Archival persisted but snippet republication pending, or publication lock contention — retriable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"},"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"archival_persisted":{"type":"boolean"},"publication_pending":{"type":"boolean"},"retriable":{"type":"boolean"}}}}}}}}},"/admin/shops/{id}/restore":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Platform admin"],"summary":"Restore an archived shop","description":"Requires an admin:write user API key. Delivery remains controlled by the shop runtime kill switch.","responses":{"200":{"description":"Shop restored","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Shop not found (pass-through orchestration body)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/admin/tracking/quarantine":{"get":{"tags":["Platform admin"],"summary":"List tracking quarantine events","description":"Read-only platform view requiring a live PlatformAccess row.","parameters":[{"name":"shopId","in":"query","schema":{"type":"string"}},{"name":"reasonCode","in":"query","schema":{"type":"string"}},{"name":"verdict","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Quarantine rows","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"shop_id":{"type":"string"},"shop_name":{"type":"string"},"shop_domain":{"type":"string"},"source_id":{"type":["string","null"]},"source_provider":{"type":["string","null"]},"source_label":{"type":["string","null"]},"source_status":{"type":["string","null"]},"event_id":{"type":"string"},"event_type":{"type":"string"},"visitor_id":{"type":"string"},"reason":{"type":"string"},"reason_code":{"type":"string"},"verdict":{"type":"string"},"raw_event":{"type":"object"},"normalized_event":{"type":"object"},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}}}}},"required":["rows"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/account/profile":{"get":{"summary":"Get the current user's profile","tags":["Account"],"responses":{"200":{"description":"Account profile","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update the current user's profile","tags":["Account"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"displayName":{"type":"string","minLength":1,"maxLength":80},"avatarDataUrl":{"type":["string","null"],"maxLength":380000}}}}}},"responses":{"200":{"description":"Updated account profile","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/keys":{"get":{"summary":"List a shop's API keys","tags":["API keys"],"parameters":[{"name":"shop_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"API key metadata; hashes and secrets are never included","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Create a shop API key","tags":["API keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["shop_id","name","type"],"properties":{"shop_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"type":{"type":"string","enum":["live_secret","test_secret","publishable"]},"permissions":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":120}},"rate_limit":{"type":"integer","minimum":1,"maximum":10000},"expires_at":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"201":{"description":"Created key, including its secret exactly once","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/keys/{id}":{"delete":{"summary":"Revoke a shop API key","tags":["API keys"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shop_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Revoked","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog":{"get":{"summary":"List backlog","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"include_archived","in":"query","description":"Include archived backlog items when true.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Paginated backlog","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BacklogItem"}},"pagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["has_more","next_cursor"]}},"required":["data","pagination"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Create a backlog item","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItem"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/fields":{"get":{"summary":"List the shop's idea fields","description":"The field definitions whose values ride on each idea's custom_fields.","parameters":[{"name":"include_archived","in":"query","description":"Include archived fields when true.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Field definitions, in sheet order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BacklogFieldDefinition"}}},"required":["data"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Add an idea field","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogFieldCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogFieldDefinition"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Reorder the idea fields","description":"Places the live fields. Every named field must be live, and the resulting positions must be unique across the whole live sheet, so send the sheet rather than one row when two fields swap places. The body is the bare array or the same array under an order key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BacklogFieldOrder"},{"type":"object","additionalProperties":false,"properties":{"order":{"$ref":"#/components/schemas/BacklogFieldOrder"}},"required":["order"]}]}}}},"responses":{"200":{"description":"Field definitions, in the new order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BacklogFieldDefinition"}}},"required":["data"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/fields/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"summary":"Update an idea field","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogFieldUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogFieldDefinition"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"delete":{"summary":"Archive an idea field","description":"Archiving keeps the values already stored on ideas. The field disappears from reads and rejects new writes.","responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogFieldDefinition"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a backlogitem","responses":{"200":{"description":"Resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItemDetail"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update a backlogitem","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItem"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Backlog item changed after it was loaded. Reload the item, take its fresh version, and retry.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[409]},"code":{"type":"string","enum":["backlog_item_cas_miss"]}},"required":["message","status","code"]}},"required":["error"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"delete":{"summary":"Archive a backlog item","description":"Archives the backlog item instead of destroying it.","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/{id}/design":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get an idea's design board","description":"Mockups, links, inspiration, and internal build notes, plus every Research Hub mirror the item carries. The internal half (build notes, inspiration, and links whose switch is off) is redacted for a client viewer: a client shop role in the dashboard, and a user API key whose holder holds one. A secret API key is minted with apikeys:manage, which no client role holds, so it reads the whole board.","responses":{"200":{"description":"Design board","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItemDesignEnvelope"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update an idea's design board","description":"Replaces the keys it carries and leaves the rest alone. Arrays replace wholesale.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItemDesignPatch"}}}},"responses":{"200":{"description":"Updated design board","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItemDesignEnvelope"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The idea changed while saving","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[409]},"code":{"type":"string","enum":["backlog_item_cas_miss","backlog_design_unreadable"]}},"required":["message","status","code"]}},"required":["error"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/{id}/archive":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Archive a backlog item and reject its roadmap decision","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"feedback":{"type":["string","null"],"maxLength":10000,"description":"Decline reason stored as the roadmap rejection note and forwarded as Research Hub feedback."},"reason":{"type":["string","null"],"maxLength":10000,"description":"Alias for feedback."}}}}}},"responses":{"200":{"description":"Archived backlog item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItem"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Approve a backlog idea into a month","description":"Schedules the idea and records who decided. On a shop where DRIP decides the backlog, a client principal is refused with 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["roadmap_month"],"properties":{"roadmap_month":{"type":"string","minLength":1,"maxLength":40,"pattern":"\\S","description":"The month to run the idea in, as YYYY-MM or \"Month YYYY\"."},"comment":{"type":["string","null"],"maxLength":10000,"description":"Optional note stored with the approval."}}}}}},"responses":{"200":{"description":"The idea's decision after approving","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogDecision"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Reject a backlog idea with a reason","description":"Records the rejection and its reason. The idea stays in the backlog, shown as rejected, rather than being archived.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reason_category","reason"],"properties":{"reason_category":{"type":"string","enum":["not_right_for_brand","already_tested","too_much_effort","other"]},"reason":{"type":"string","minLength":1,"maxLength":10000,"pattern":"\\S","description":"Why the idea was rejected. Required for every category."}}}}}},"responses":{"200":{"description":"The idea's decision after rejecting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogDecision"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/backlog/{id}/restore":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Restore an archived backlog item and reset its roadmap decision to proposed","responses":{"200":{"description":"Restored backlog item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklogItem"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/external-tracking":{"get":{"summary":"Read cross-domain identity handover settings","tags":["External tracking"],"responses":{"200":{"description":"External tracking settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalTrackingResponse"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update cross-domain identity handover settings","tags":["External tracking"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"externalTracking":{"type":"object","additionalProperties":false,"properties":{"domains":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Domains must already be bound to this shop through its primary, additional, or environment domains."},"handoverQueryParam":{"type":"string","pattern":"^[a-z_][a-z0-9_]{0,31}$","maxLength":32},"handoverTtlSeconds":{"type":"integer","minimum":30,"maximum":600},"handoverMintTimeoutMs":{"type":"integer","minimum":50,"maximum":2000},"signed":{"type":"boolean","description":"Sending false is rejected with 403: turning handover signing off is a platform-support action. Sending true re-enables signing."}}},"ifRevision":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"200":{"description":"Updated handover settings and edge precompile outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalTrackingPatchResponse"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/personalizations":{"get":{"summary":"List personalizations","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Personalizations with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Personalization"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Create personalization","responses":{"201":{"description":"Created personalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Personalization"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalizationInput"}}}}}},"/personalizations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get personalization","responses":{"200":{"description":"Personalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Personalization"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update personalization","responses":{"200":{"description":"Updated personalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Personalization"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalizationUpdateInput"}}}}}},"/personalizations/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Activate personalization","responses":{"200":{"description":"Updated personalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Personalization"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/personalizations/{id}/pause":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Pause personalization","responses":{"200":{"description":"Updated personalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Personalization"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/personalizations/{id}/archive":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Archive personalization","responses":{"200":{"description":"Updated personalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Personalization"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments":{"get":{"summary":"List experiments","description":"Returns a paginated list of experiments. Supports cursor-based pagination and optional status filter.","tags":["Experiments"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","awaiting_client_approval","changes_requested","client_approved","qa","ready_to_launch","running","paused","completed"]}},{"name":"archived","in":"query","schema":{"type":"string","enum":["1"]},"description":"Set to 1 to include archived experiments"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"},"description":"ID of the last item from the previous page"}],"responses":{"200":{"description":"Paginated list of experiments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Experiment"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Create experiment","description":"Creates a new experiment. Default control and variant are created if variations are not provided. Omitted statistical settings use the shop testing defaults. Experiments authenticated with a user API key default owner_user_id to that key's user; organization- and shop-scoped keys have no user and leave the owner null.","tags":["Experiments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"slug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","nullable":true},"description":{"type":"string","maxLength":2000,"nullable":true},"backlog_item_id":{"type":"string","format":"uuid","description":"Backlog item to link as the primary source. A repeat request returns the already linked experiment with 200; dashboard-gated backlog items are rejected."},"idea_key":{"type":"string","description":"Shop backlog key (for example LOC-121). Alternative to backlog_item_id; sending both is rejected with 422."},"as_follow_up":{"type":"boolean","default":false,"description":"Link the new experiment to the idea as a follow-up test when the idea already has a primary test."},"owner_user_id":{"type":["string","null"],"format":"uuid","readOnly":true,"description":"Resolved from the authenticating user API key. Organization- and shop-scoped keys leave this null."},"counting_type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"],"default":"standard"},"delivery_type":{"type":"string","enum":["mutation","redirect"],"default":"mutation"},"type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"],"deprecated":true,"description":"Deprecated alias for counting_type."},"experiment_type":{"type":"string","enum":["mutation","redirect"],"deprecated":true,"description":"Deprecated alias for delivery_type."},"traffic_allocation":{"type":"number","minimum":0,"maximum":1,"default":1},"experiment_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_reset_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_css":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"sequential_testing_enabled":{"type":"boolean","description":"Enable always-valid sequential significance (mSPRT). Defaults to the shop testing setting when omitted."},"significance_level":{"type":"number","minimum":0.8,"maximum":0.99,"description":"Defaults to the shop testing setting when omitted."},"statistical_power":{"type":"number","minimum":0.5,"maximum":0.99,"description":"Defaults to the shop testing setting when omitted."},"store_url":{"type":"string","format":"uri","nullable":true},"auto_stop_override":{"$ref":"#/components/schemas/AutoStopOverride"},"guardian_override":{"$ref":"#/components/schemas/GuardianOverride"},"targeting":{"anyOf":[{"$ref":"#/components/schemas/ExperimentTargeting"},{"type":"null"}]},"variations":{"type":"array","minItems":2,"items":{"type":"object","required":["name","weight"],"properties":{"name":{"type":"string"},"weight":{"type":"number","minimum":0,"maximum":1},"is_control":{"type":"boolean","default":false},"redirect_url":{"type":"string","format":"uri","nullable":true,"description":"Redirect destination. Treatment mutations and custom CSS/JavaScript apply only on the source page; the destination preserves assignment attribution without applying those artifacts. A destination on the same origin and path as the experiment's positive source URL rules that differs only by query parameters (a template variant, for example a Shopify ?view= alternate template) is accepted; any other destination matching the source rules is rejected."},"mutations":{"type":"array","items":{"$ref":"#/components/schemas/Mutation"},"default":[]},"url_blocks":{"$ref":"#/components/schemas/UrlBlocks"},"custom_css":{"type":"string","nullable":true,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"custom_js":{"type":"string","nullable":true,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."}}}},"primary_goal_id":{"type":"string","format":"uuid","nullable":true,"description":"Explicit primary decision metric. Can reference any goal type, including click or pageview goals. Defaults to the first goal_ids item."},"goal_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}},"responses":{"200":{"description":"Existing experiment already linked to the backlog item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"201":{"description":"Experiment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Backlog item not found for this shop","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"422":{"description":"Backlog item requires customer approval or the dashboard landing-page handoff, or both backlog_item_id and idea_key were sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}":{"get":{"summary":"Get experiment","description":"Returns a single experiment by ID with variations and goals.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Experiment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"patch":{"summary":"Update experiment","description":"Partially updates an experiment. Cannot update completed experiments.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"slug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","nullable":true},"description":{"type":"string","maxLength":2000,"nullable":true},"owner_user_id":{"type":["string","null"],"format":"uuid","description":"Assigns the experiment owner to a member of the shop's organization. Send null to clear the owner."},"counting_type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"]},"type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"],"deprecated":true,"description":"Deprecated alias for counting_type."},"traffic_allocation":{"type":"number","minimum":0,"maximum":1},"experiment_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_reset_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_css":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"sequential_testing_enabled":{"type":"boolean","description":"Enable always-valid sequential significance (mSPRT)"},"store_url":{"type":"string","format":"uri","nullable":true},"auto_stop_override":{"$ref":"#/components/schemas/AutoStopOverride"},"guardian_override":{"$ref":"#/components/schemas/GuardianOverride"},"targeting":{"anyOf":[{"$ref":"#/components/schemas/ExperimentTargeting"},{"type":"null"}]},"confirmTargetingReplace":{"type":"boolean","description":"Required (true) when the targeting update would replace the experiment's author-explicit URL targeting with a page-entity rule. Without it such updates are rejected with 409 and error.code confirm_targeting_replace_required."}}}}}},"responses":{"200":{"description":"Experiment updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Cannot update completed experiment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Targeting replacement requires confirmation (error.code confirm_targeting_replace_required): the update would replace the experiment's author-explicit URL targeting with a page-entity rule. Retry with confirmTargetingReplace: true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"delete":{"summary":"Archive experiment","description":"Archives an experiment while preserving its variations and results history.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Experiment deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/{id}/filesystem":{"get":{"summary":"Read experiment filesystem","description":"Returns the complete canonical filesystem snapshot for an experiment. File hashes can be used to detect changes before planning a write.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Canonical experiment filesystem","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"rootName":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/ExperimentFilesystemFile"}}},"required":["rootName","files"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/filesystem/plan":{"post":{"summary":"Plan an experiment filesystem apply","description":"Validates a complete filesystem snapshot and reports the changes without writing them. Draft experiments accept all supported filesystem changes. Paused experiments accept treatment-content changes and redirect destinations. Running experiments accept treatment-content changes only; redirect destinations remain draft/paused-only. Structural changes remain draft-only and are reported with the offending file paths.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"files":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"path":{"type":"string","minLength":1},"content":{"type":"string"}},"required":["path","content"]}}},"required":["files"]}}}},"responses":{"200":{"description":"Filesystem apply plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExperimentFilesystemPlan"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Invalid request body","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/filesystem/apply":{"post":{"summary":"Apply an experiment filesystem","description":"Atomically applies experiment, goal, variation, and variation-artifact changes to draft experiments. Paused experiments accept treatment-content changes and redirect destinations. Running experiments accept treatment-content changes only; redirect destinations remain draft/paused-only. Structural changes remain draft-only and fail closed with the offending file paths. Running artifact writes republish the storefront configuration. A successful response with applied=true means every database change committed. applied=false means no changes from this request committed, except when saved=true reports a committed artifact whose storefront publication failed. Identically re-applying an already committed snapshot is safe and converges on the same final state.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"files":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"path":{"type":"string","minLength":1},"content":{"type":"string"}},"required":["path","content"]}}},"required":["files"]}}}},"responses":{"200":{"description":"Atomic apply outcome","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"applied":{"type":"boolean"},"saved":{"type":"boolean"},"artifact_hash":{"type":["string","null"]},"publication":{"type":["object","null"],"additionalProperties":false,"required":["status","code","message"],"properties":{"status":{"type":"string","enum":["ok","pending","warning","failed"]},"code":{"type":"string"},"message":{"type":"string"}}},"plan":{"$ref":"#/components/schemas/ExperimentFilesystemPlan"}},"required":["applied","plan"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Invalid request body","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"500":{"description":"Unexpected failure; the atomic database transaction was rolled back and no filesystem changes committed.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/results":{"get":{"summary":"Get experiment results","description":"Returns the canonical experiment results read model, including totals, arms, decision, metrics, timeseries, warnings, and delivery health.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"currency","in":"query","schema":{"type":"string","minLength":3,"maxLength":3},"description":"Optional ISO currency code for revenue diagnostics."}],"responses":{"200":{"description":"Experiment results","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","pattern":"^([A-Z]{3})?$","description":"ISO-4217 reporting currency used by every money value in this response; empty when the shop currency is unknown or malformed."},"experiment":{"type":"object"},"totals":{"type":"object"},"arms":{"type":"array","items":{"type":"object"}},"control":{"type":"object","nullable":true},"treatment":{"type":"object","nullable":true},"decision":{"type":"object","properties":{"method":{"type":"string","enum":["sequential-msprt","fixed-horizon-welch","revenue-fixed-horizon-welch","count-fixed-horizon-welch"]},"basis":{"type":"string","enum":["sequential","fixed_horizon"]}},"required":["method","basis"]},"effective_outcome":{"type":"object","description":"Rendered outcome classification. Manager decisions override only this classification; statisticsOutcome remains the untouched statistics plane.","properties":{"outcome":{"type":"string","enum":["winner","loser","inconclusive","collecting","underpowered","untrustworthy","no-primary-goal","analytics_unavailable"]},"statisticsOutcome":{"type":"string","enum":["winner","loser","inconclusive","collecting","underpowered","untrustworthy","no-primary-goal","analytics_unavailable"]},"provenance":{"type":"string","enum":["statistics","manager_decided"]}},"required":["outcome","statisticsOutcome","provenance"]},"manager_decision":{"type":"object","nullable":true,"description":"The active manager decision. Null when no decision exists or the latest decision was revoked.","properties":{"outcome":{"type":"string","enum":["winner","loser","inconclusive"]},"reason":{"type":"string"},"decided_by":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"decided_at":{"type":"string","format":"date-time"},"version":{"type":"integer","minimum":1}},"required":["outcome","reason","decided_by","decided_at","version"]},"metrics":{"type":"array","items":{"type":"object","properties":{"lineItemsTruncated":{"type":"boolean","description":"Informational integrity signal: capped line-item payloads may undercount this filtered goal. Present only on line-item-filtered goal metrics, and only when the diagnostic returned a definite verdict. Absence does not imply completeness — read lineItemsIntegrity."},"lineItemsIntegrity":{"type":"string","enum":["complete","truncated","unknown"],"description":"Integrity of the line-item payloads behind this filtered goal. 'unknown' means the diagnostic could not run, so completeness is unconfirmed rather than proven. Present only on line-item-filtered goal metrics."},"ordersLackingItemData":{"type":"integer","minimum":0,"description":"Count of eligible, deduplicated, exposure-gated orders whose line items could not answer this goal's item filter. Present only on line-item-filtered revenue goal metrics, and absent when the coverage probe failed — read ordersLackingItemDataUnknown."},"ordersLackingItemDataUnknown":{"type":"boolean","description":"True when the coverage probe failed, so the count is unconfirmed and ordersLackingItemData is absent. Reporting 0 would present a failed probe as a verified zero."},"missingItemsIncluded":{"type":"boolean","description":"Whether orders without usable product data are counted into this goal, per the missingItems setting of its line-item filter. Present only on line-item-filtered goal metrics."},"controlPopulation":{"type":"integer","nullable":true,"description":"Metric-specific denominator for the control arm. Order-based goals include server-matched orders without a tracked session; other goals use exposed visitors."},"variantPopulation":{"type":"integer","nullable":true,"description":"Metric-specific denominator for the displayed treatment arm. Order-based goals include server-matched orders without a tracked session; other goals use exposed visitors."},"controlAttributedOrders":{"type":"integer","nullable":true,"description":"All matching attributed control orders, consented and consent-declined. Display-only; excluded from rates and inference."},"variantAttributedOrders":{"type":"integer","nullable":true,"description":"All matching attributed decision-treatment orders, consented and consent-declined. Display-only; excluded from rates and inference."},"controlConsentedOrders":{"type":"integer","nullable":true},"variantConsentedOrders":{"type":"integer","nullable":true},"controlDeclinedOrders":{"type":"integer","nullable":true},"variantDeclinedOrders":{"type":"integer","nullable":true},"controlUnevaluableOrders":{"type":"integer","nullable":true},"variantUnevaluableOrders":{"type":"integer","nullable":true},"attributedOrdersTruncated":{"type":"boolean","description":"True when the bounded commerce attribution read exceeded 50,000 rows."},"totalEvents":{"type":"integer","nullable":true,"description":"Total repeatable goal events across the displayed experiment arms. Null for count-once goals."},"controlUniqueConverters":{"type":"integer","nullable":true,"description":"Control arm visitors who converted this goal at least once. Display-only counting basis; `counting` still decides which basis every statistic on this row was computed on. Absent on money, value, and revenue-alias rows."},"variantUniqueConverters":{"type":"integer","nullable":true,"description":"Displayed treatment arm visitors who converted this goal at least once. Display-only counting basis; `counting` still decides which basis every statistic on this row was computed on. Absent on money, value, and revenue-alias rows."},"controlAllEvents":{"type":"integer","nullable":true,"description":"Every control arm goal fire, repeats included. Display-only counting basis; `counting` still decides which basis every statistic on this row was computed on. Absent on money, value, and revenue-alias rows."},"variantAllEvents":{"type":"integer","nullable":true,"description":"Every displayed treatment arm goal fire, repeats included. Display-only counting basis; `counting` still decides which basis every statistic on this row was computed on. Absent on money, value, and revenue-alias rows."},"variants":{"type":"array","items":{"type":"object","properties":{"attributedOrders":{"type":"integer","nullable":true},"consentedOrders":{"type":"integer","nullable":true},"declinedOrders":{"type":"integer","nullable":true},"unevaluableOrders":{"type":"integer","nullable":true},"eventsDisplay":{"type":"string","nullable":true,"description":"Formatted repeatable event count for this variant. Null for count-once goals."},"uniqueConverters":{"type":"integer","nullable":true,"description":"This variant's visitors who converted the goal at least once. Display-only counting basis; `counting` still decides which basis every statistic was computed on. Absent on money, value, and revenue-alias rows."},"allEvents":{"type":"integer","nullable":true,"description":"Every goal fire for this variant, repeats included. Display-only counting basis; `counting` still decides which basis every statistic was computed on. Absent on money, value, and revenue-alias rows."}}}}}}},"series":{"type":"array","items":{"type":"object"}},"segments":{"type":"array","items":{"type":"object"}},"revenue":{"type":"object"},"commerce":{"type":"object"},"funnel":{"type":"array","items":{"type":"object"}},"deliveryHealth":{"type":"array","items":{"type":"object"}},"runtimeEvidence":{"type":"object","nullable":true},"warnings":{"type":"array","items":{"type":"object"}}},"required":["currency","experiment","totals","arms","decision","effective_outcome","manager_decision","metrics","series","segments","revenue","commerce","funnel","deliveryHealth","warnings"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing experiment read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/by-slug/{slug}":{"get":{"summary":"Get experiment by slug","description":"Fetch a single experiment by slug (scoped to the API key's shop).","tags":["Experiments"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"}}],"responses":{"200":{"description":"Experiment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"put":{"summary":"Upsert experiment by slug","description":"Idempotently create or update a draft experiment by slug. New experiments use the shop testing defaults for omitted statistical settings and default owner_user_id to the authenticated user for user API keys; organization- and shop-scoped keys leave the owner null. If an experiment exists with this slug and is not in draft status, returns 409.","tags":["Experiments"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","variations"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000,"nullable":true},"counting_type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"],"description":"Defaults to standard on create; omission preserves the stored counting_type on update."},"delivery_type":{"type":"string","enum":["mutation","redirect"],"description":"Defaults to mutation when creating a new slug. When updating an existing draft, omission preserves its stored experiment type."},"type":{"type":"string","enum":["standard","setup_test","aa_test","non_program"],"deprecated":true,"description":"Deprecated alias for counting_type."},"experiment_type":{"type":"string","enum":["mutation","redirect"],"deprecated":true,"description":"Deprecated alias for delivery_type."},"traffic_allocation":{"type":"number","minimum":0,"maximum":1,"default":1},"experiment_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_reset_js":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"experiment_css":{"type":"string","nullable":true,"maxLength":200000,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"sequential_testing_enabled":{"type":"boolean","description":"Enable always-valid sequential significance (mSPRT). On create, omission uses the shop testing default."},"significance_level":{"type":"number","minimum":0.8,"maximum":0.99,"description":"On create, omission uses the shop testing default."},"statistical_power":{"type":"number","minimum":0.5,"maximum":0.99,"description":"On create, omission uses the shop testing default."},"store_url":{"type":"string","format":"uri","nullable":true},"auto_stop_override":{"$ref":"#/components/schemas/AutoStopOverride"},"targeting":{"anyOf":[{"$ref":"#/components/schemas/ExperimentTargeting"},{"type":"null"}]},"variations":{"type":"array","minItems":2,"items":{"type":"object","required":["name","weight"],"properties":{"name":{"type":"string"},"weight":{"type":"number","minimum":0,"maximum":1},"is_control":{"type":"boolean","default":false},"redirect_url":{"type":"string","format":"uri","nullable":true,"description":"When updating an existing variation, omission preserves its stored redirect destination; null clears it. Treatment mutations and custom CSS/JavaScript remain source-page-only and are not applied on the destination. A destination on the same origin and path as the experiment's positive source URL rules that differs only by query parameters (a template variant, for example a Shopify ?view= alternate template) is accepted; any other destination matching the source rules is rejected."},"mutations":{"type":"array","items":{"$ref":"#/components/schemas/Mutation"},"default":[]},"url_blocks":{"$ref":"#/components/schemas/UrlBlocks"},"custom_css":{"type":"string","nullable":true,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."},"custom_js":{"type":"string","nullable":true,"description":"Inline data URIs longer than 4,096 characters are rejected with HTTP 400; upload images as assets."}}}},"primary_goal_id":{"type":"string","format":"uuid","nullable":true,"description":"Explicit primary decision metric. Can reference any goal type, including click or pageview goals. Defaults to the first goal_ids item."},"goal_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}},"responses":{"200":{"description":"Experiment updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"201":{"description":"Experiment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Conflict (experiment not in draft status or slug already exists)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/idea":{"post":{"summary":"Attach an idea to an experiment","description":"Links the experiment to one idea. Send exactly one of backlog_item_id or idea_key. Repeating the request returns the existing link with 200 and writes no audit entry.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"backlog_item_id":{"type":"string","format":"uuid","description":"Idea UUID."},"idea_key":{"type":"string","description":"Shop backlog key, for example LOC-121."},"as_follow_up":{"type":"boolean","default":false,"description":"Link as a follow-up test when the idea already has a primary test."}},"oneOf":[{"required":["backlog_item_id"]},{"required":["idea_key"]}]}}}},"responses":{"200":{"description":"The experiment was already linked to this idea","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaLinkResponse"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"201":{"description":"Idea attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaLinkResponse"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"No identifier, or a field of the wrong type","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment or idea not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Experiment or idea already has a primary link","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"422":{"description":"Both backlog_item_id and idea_key were sent","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"delete":{"summary":"Detach the linked idea from an experiment","description":"Removes one idea link. Without an identifier the primary link goes first, then the oldest link.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"backlog_item_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Remove the link to this idea instead of the primary link."},{"name":"idea_key","in":"query","required":false,"schema":{"type":"string"},"description":"Shop backlog key alternative to backlog_item_id."}],"responses":{"200":{"description":"Idea detached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaDetachResponse"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment or idea link not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"422":{"description":"Both backlog_item_id and idea_key were sent","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/{id}/pause":{"post":{"summary":"Pause experiment","description":"Pauses a running experiment.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Experiment paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Only running experiments can be paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"502":{"description":"Commerce configuration failed before commit, or the lifecycle change committed but storefront publication failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CommercePlanePostCommitPublishError"}]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"description":"Publication lock contended; retry after the Retry-After interval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/{id}/complete":{"post":{"summary":"Complete experiment","description":"Marks a running or paused experiment as completed. Sets ended_at timestamp.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Experiment completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Only running or paused experiments can be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"502":{"description":"Commerce configuration failed before commit, or the lifecycle change committed but storefront publication failed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CommercePlanePostCommitPublishError"}]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"description":"Publication lock contended; retry after the Retry-After interval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/{id}/duplicate":{"post":{"summary":"Duplicate experiment","description":"Creates a faithful copy of the experiment in draft status with its configuration, variation artifacts, landing-page bindings, and goal associations. Review, scheduling, runtime, and result state do not carry over.","tags":["Experiments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"201":{"description":"Duplicate experiment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"A variation artifact could not be copied; no duplicate is created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"A concurrent write caused a temporary transaction conflict (error code tx_write_conflict); retry the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/generate":{"post":{"summary":"Generate experiment with AI","description":"Uses AI to generate an experiment configuration based on a store URL and prompt.","tags":["Experiments","AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["store_url","prompt"],"properties":{"store_url":{"type":"string","format":"uri"},"prompt":{"type":"string","minLength":1,"maxLength":5000},"primary_goal_id":{"type":"string","format":"uuid","nullable":true,"description":"Explicit primary decision metric. Can reference any goal type, including click or pageview goals. Defaults to the first goal_ids item."},"goal_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"traffic_allocation":{"type":"number","minimum":0,"maximum":1,"default":1},"targeting":{"anyOf":[{"$ref":"#/components/schemas/ExperimentTargeting"},{"type":"null"}]},"screenshot_devices":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"AI-generated experiment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Experiment"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/{id}/variations/generate":{"post":{"summary":"Generate variation with AI","description":"Uses AI to generate a new variation for an existing experiment.","tags":["Variations","AI"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"description":"Experiment ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":5000}}}}}},"responses":{"201":{"description":"AI-generated variation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Variation"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/variations":{"post":{"summary":"Create variation","description":"Creates a new variation for a draft experiment. Requires experiment_id in the body.","tags":["Variations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["experiment_id","name","weight"],"properties":{"experiment_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"name":{"type":"string","minLength":1,"maxLength":255},"weight":{"type":"number","minimum":0,"maximum":1},"is_control":{"type":"boolean","default":false},"redirect_url":{"type":"string","format":"uri","nullable":true,"description":"Redirect destination. Null clears the destination on redirect experiments and is treated as omitted on mutation experiments. Treatment mutations and custom CSS/JavaScript apply only on the source page."},"mutations":{"type":"array","items":{"$ref":"#/components/schemas/Mutation"},"default":[]},"url_blocks":{"$ref":"#/components/schemas/UrlBlocks"},"custom_css":{"type":"string","nullable":true},"custom_js":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"Variation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Variation"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error or experiment not in draft status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/variations/{id}":{"get":{"summary":"Get variation","description":"Returns a single variation by ID.","tags":["Variations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Variation details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Variation"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized to access this variation","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Variation not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"patch":{"summary":"Update variation","description":"Partially updates a variation. Treatment artifacts (mutations, URL blocks, and custom CSS/JavaScript) can change while the experiment is draft, paused, or running. Running artifact writes republish the storefront configuration. Other variation fields remain draft-only. Cannot update is_control.","tags":["Variations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"weight":{"type":"number","minimum":0,"maximum":1},"redirect_url":{"type":"string","format":"uri","nullable":true,"description":"Redirect destination. Null clears the destination on redirect experiments and is treated as omitted on mutation experiments. Treatment mutations and custom CSS/JavaScript apply only on the source page."},"expected_prior_redirect_url":{"type":"string","format":"uri","nullable":true,"description":"Optional compare-and-set predicate for redirect destination updates. Set this to the destination previously read, or null when no destination was stored. Returns 409 if the stored value changed before this write."},"mutations":{"type":"array","items":{"$ref":"#/components/schemas/Mutation"}},"url_blocks":{"$ref":"#/components/schemas/UrlBlocks"},"custom_css":{"type":"string","nullable":true},"custom_js":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Variation updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Variation"},{"type":"object","description":"Artifact writes include save and publication outcomes. Metadata-only updates may omit these fields.","properties":{"saved":{"type":"boolean"},"artifact_hash":{"type":["string","null"]},"publication":{"type":["object","null"],"additionalProperties":false,"required":["status","code","message"],"properties":{"status":{"type":"string","enum":["ok","pending","warning","failed"]},"code":{"type":"string"},"message":{"type":"string"}}}}}]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"The write was rejected, or treatment artifacts committed before a later publication step reported a failure","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","required":["error","saved","artifact_hash","publication"],"properties":{"error":{"type":"object","required":["message","status"],"properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[400]}}},"saved":{"type":"boolean"},"artifact_hash":{"type":["string","null"]},"publication":{"type":["object","null"],"additionalProperties":false,"required":["status","code","message"],"properties":{"status":{"type":"string","enum":["ok","pending","warning","failed"]},"code":{"type":"string"},"message":{"type":"string"}}}}}]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Variation not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Treatment artifacts cannot change after the experiment finishes, the redirect destination changed since it was read, the experiment is no longer editable, or a price-test mutation targets a subscription-priced or bundle-component variant","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"502":{"description":"The running treatment artifact was saved, but storefront publication failed","content":{"application/json":{"schema":{"type":"object","required":["error","saved","artifact_hash","publication"],"properties":{"error":{"type":"object","required":["message","status"],"properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[502]}}},"saved":{"type":"boolean"},"artifact_hash":{"type":["string","null"]},"publication":{"type":["object","null"],"additionalProperties":false,"required":["status","code","message"],"properties":{"status":{"type":"string","enum":["ok","pending","warning","failed"]},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"delete":{"summary":"Archive variation","description":"Archives a non-control variation from a draft experiment. Minimum 2 active variations must remain, and remaining active weights are redistributed.","tags":["Variations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Variation archived","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"all_variations":{"type":"array","description":"Remaining active variations with their redistributed weights.","items":{"$ref":"#/components/schemas/Variation"}},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Cannot delete control, non-draft experiment, or last two variations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Variation not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/variations/{id}/restore":{"post":{"summary":"Restore variation","description":"Restores an archived variation and redistributes all active variation weights.","tags":["Variations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Variation restored","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Variation"},{"type":"object","properties":{"all_variations":{"type":"array","description":"Sibling variations with their redistributed weights.","items":{"$ref":"#/components/schemas/Variation"}}}}]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Variation not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Variation is already active or changed concurrently","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/{id}/variations/{variationId}/workspace":{"get":{"summary":"Read variation workspace","description":"Returns the canonical Apex workspace for an exact experiment variation. Used by `apex workspace checkout`.","tags":["Apex Workspace"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"description":"Experiment ID"},{"name":"variationId","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"description":"Variation ID"}],"responses":{"200":{"description":"Canonical workspace payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspacePayload"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized to access this variation","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment variation workspace not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/variations/{variationId}/files":{"get":{"summary":"List variation workspace files","description":"Lists canonical workspace files for an exact experiment variation.","tags":["Apex Workspace"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"variationId","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Workspace files","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceFile"}}},"required":["files"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized to access this variation","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment variation workspace not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/variations/{variationId}/files/{path}":{"get":{"summary":"Read variation workspace file","description":"Reads one canonical workspace file. URL-encode the file path, for example src%2Findex.js.","tags":["Apex Workspace"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"variationId","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"Canonical workspace path, URL-encoded. Supported roots: src, goals, segments, network, metrics.json, targeting.json, experiment.config.json, dev-doc.md."}],"responses":{"200":{"description":"Workspace file","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/WorkspaceFile"}},"required":["file"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized to access this variation","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Workspace file not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"put":{"summary":"Write variation workspace file","description":"Writes one canonical workspace file and records a workspace revision. Supply expected_version from the current file sha256 to reject a concurrent edit.","tags":["Apex Workspace"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"variationId","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"Canonical workspace path, URL-encoded. Supported roots: src, goals, segments, network, metrics.json, targeting.json, experiment.config.json, dev-doc.md."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"source":{"type":"string","enum":["manual","operator","build","system"],"default":"operator"},"title":{"type":"string","minLength":1,"maxLength":255},"expected_version":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Current file sha256. A stale or missing file returns workspace_file_cas_miss."}}}}}},"responses":{"200":{"description":"Workspace file write result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"changed":{"type":"boolean"},"file":{"$ref":"#/components/schemas/WorkspaceFile"},"revision":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"title":{"type":"string"}}}},"required":["ok","changed","file"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error or unsupported workspace path","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized to edit this variation","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment variation workspace not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"The workspace file changed or no longer exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[409]},"code":{"type":"string","enum":["workspace_file_cas_miss"]}},"required":["message","status","code"]}},"required":["error"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/variations/{variationId}/build":{"post":{"summary":"Build variation workspace","description":"Projects canonical workspace files into Apex runtime state: mutations, CSS, JS, targeting, goals, and segments.","tags":["Apex Workspace"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"variationId","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["full","validate_only"],"default":"full"},"allowGoalWrites":{"type":"boolean","default":false,"description":"Set allowGoalWrites=true to allow metrics.json to create or update shared shop-level goals. Defaults to false for fail-closed API publishes."}}}}}},"responses":{"200":{"description":"Workspace build succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceBuildResult"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Workspace build failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceBuildResult"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized to edit this variation","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment variation workspace not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Workspace build conflicted with a concurrent artifact save","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceBuildResult"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/experiments/{id}/variations/{variationId}/revisions":{"get":{"summary":"List variation workspace revisions","description":"Lists recent workspace revisions for an exact experiment variation.","tags":["Apex Workspace"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}},{"name":"variationId","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}],"responses":{"200":{"description":"Workspace revisions","content":{"application/json":{"schema":{"type":"object","properties":{"revisions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceRevision"}}},"required":["revisions"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"Not authorized to access this variation","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment variation workspace not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/targeting/test":{"get":{"summary":"Test URL targeting","description":"Evaluates the API key shop's experiment targeting rules against one URL and returns all matching experiments for parallel-experiment awareness.","tags":["Targeting"],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"status","in":"query","schema":{"type":"string","default":"all"},"description":"Comma-separated statuses or all. Defaults to draft,qa,running,paused."}],"responses":{"200":{"description":"Targeting evaluation","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"statuses":{"type":"array","items":{"type":"string"}},"matching_count":{"type":"integer"},"truncated":{"type":"boolean"},"experiments":{"type":"array","items":{"type":"object","properties":{"experiment":{"type":"object"},"matches":{"type":"boolean"},"has_url_rules":{"type":"boolean"},"rules":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"pattern":{"type":"string"},"type":{"type":"string","enum":["simple","regex"]},"include":{"type":"boolean"},"matched":{"type":"boolean"},"indeterminate":{"type":"boolean","description":"True only when a valid regex has a catastrophic backtracking shape and is not executed server-side. Lookaround and backreference patterns are evaluated normally."},"matchType":{"type":"string","nullable":true}},"required":["source","pattern","type","include","matched","matchType"]}},"caveats":{"type":"array","items":{"type":"string"},"description":"Targeting limitations. Valid regexes with catastrophic backtracking shapes are reported as unverifiable server-side; lookaround and backreference patterns are evaluated normally."}},"required":["experiment","matches","has_url_rules","rules","caveats"]}}},"required":["url","statuses","matching_count","truncated","experiments"]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Invalid URL","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing experiment read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/harness/sessions/{id}/publish":{"post":{"summary":"Publish harness session","description":"Publishes reviewed harness artifacts to the session variation.","tags":["Harness"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Harness session published","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["variation","jsArtifactId","cssArtifactId","reviewStatus","warningIssues"],"properties":{"variation":{"$ref":"#/components/schemas/Variation"},"jsArtifactId":{"type":"string","format":"uuid"},"cssArtifactId":{"type":["string","null"],"format":"uuid"},"reviewStatus":{"type":"string"},"warningIssues":{"type":"array","items":{}},"publication_warning":{"type":"object","description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["storefront_publication_incomplete"]},"message":{"type":"string"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Artifact review blocked publish","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Harness session not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Experiment is not in draft status","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/experiments/{id}/screenshots":{"post":{"summary":"Create screenshot job","description":"Queues a screenshot capture job for the specified variations and devices.","tags":["Screenshots"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."},"description":"Experiment ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["devices","variation_ids"],"properties":{"devices":{"type":"array","minItems":1,"items":{"type":"string"}},"variation_ids":{"type":"array","minItems":1,"items":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[1-9][0-9]{9}$"}],"description":"Internal UUID or 10-digit public id."}}}}}}},"responses":{"202":{"description":"Screenshot job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotJob"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Experiment not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/screenshots/{jobId}":{"get":{"summary":"Get screenshot job status","description":"Returns the current status and results of a screenshot job.","tags":["Screenshots"],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Screenshot job details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenshotJob"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Job not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/webhooks":{"get":{"summary":"List webhooks","description":"Returns all webhooks for the shop.","tags":["Webhooks"],"parameters":[{"name":"include_archived","in":"query","schema":{"type":"boolean","default":false},"description":"Include archived webhooks."}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"availableEvents":{"type":"array","items":{"type":"string"}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"post":{"summary":"Create webhook","description":"Registers a new webhook endpoint. URL must use HTTPS. Events: experiment.started, experiment.completed, experiment.significant, experiment.guardian_triggered, experiment.guardian_paused, variation.winning, screenshots.completed, project.published.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"Must use HTTPS"},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["experiment.started","experiment.completed","experiment.significant","experiment.guardian_triggered","experiment.guardian_paused","variation.winning","screenshots.completed","project.published"]}}}}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/webhooks/{id}":{"get":{"summary":"Get webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Webhook not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"patch":{"summary":"Update webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"minItems":1},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Webhook not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"delete":{"summary":"Archive webhook","description":"Archives a webhook registration while retaining delivery history.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string","format":"uuid"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Webhook not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/webhooks/{id}/restore":{"post":{"summary":"Restore webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Restored webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Webhook not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"List webhook deliveries","description":"Returns recent delivery attempts for one webhook. Delivery IDs are also sent as the X-Apex-Delivery-Id header on outbound webhook requests.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","processing","delivered","failed","dead"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"List of webhook delivery attempts","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"consecutiveFailures":{"type":"integer"},"disabledAt":{"type":"string","format":"date-time","nullable":true}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Webhook not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/webhooks/{id}/test":{"post":{"summary":"Send test webhook","description":"Sends a signed test event and records the delivery.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Test delivery","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"consecutiveFailures":{"type":"integer"},"disabledAt":{"type":"string","format":"date-time","nullable":true}}},"delivery":{"$ref":"#/components/schemas/WebhookDelivery"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Webhook not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"409":{"description":"Webhook is inactive","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/org":{"get":{"summary":"Get the credential organization","tags":["Organization"],"responses":{"200":{"description":"Dashboard organization detail shape, including a `members` array (id, userId, email, role, defaultShopRole, createdAt) and `_count.members`.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update organization settings","tags":["Organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"slug":{"type":"string"},"billing_email":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"sso_enabled":{"type":"boolean"},"sso_enforced":{"type":"boolean"},"sso_domain":{"type":["string","null"]},"sso_provider_id":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated organization","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/org/members":{"get":{"summary":"List organization members","tags":["Organization"],"responses":{"200":{"description":"Members from the dashboard member source","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/org/invitations":{"get":{"summary":"List organization invitations","tags":["Organization"],"responses":{"200":{"description":"Pending invitations","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Invite an organization member","tags":["Organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email"},"org_role":{"type":"string","enum":["admin","member"],"default":"member"},"default_shop_role":{"type":"string","enum":["editor"],"default":"editor"}}}}}},"responses":{"201":{"description":"Invitation created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"description":"The invitation email could not be delivered. The response message says whether the pending invitation was rolled back (safe to retry now) or is still present and blocking retries until it expires","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/org/invitations/{id}":{"delete":{"summary":"Revoke an organization invitation","tags":["Organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invitation revoked","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/org/members/{id}":{"patch":{"summary":"Update an organization member","tags":["Organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"role":{"type":"string"},"default_shop_role":{"type":"string","enum":["editor"]}}}}}},"responses":{"200":{"description":"Member updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"delete":{"summary":"Remove an organization member","tags":["Organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Member removed","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/team/members":{"get":{"summary":"List shop team members","tags":["Team"],"parameters":[{"name":"shop_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Team members","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/team/invitations":{"get":{"summary":"List shop invitations","tags":["Team"],"parameters":[{"name":"shop_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invitations","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"post":{"summary":"Invite a shop member","tags":["Team"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","role","shop_id"],"properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["editor","client_viewer"]},"shop_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Invitation created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"description":"The invitation email could not be delivered. The response message says whether the pending invitation was rolled back (safe to retry now) or is still present and blocking retries until it expires","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/team/invitations/{id}":{"delete":{"summary":"Revoke a shop invitation","tags":["Team"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["shop_id"],"properties":{"shop_id":{"type":"string","format":"uuid"}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invitation revoked","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/team/members/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a shop member","tags":["Team"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["shop_id"],"anyOf":[{"required":["role"]},{"required":["permission_overrides"]}],"properties":{"shop_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["editor","client_viewer"],"description":"Assignable client role. Viewer accepts only the approvals:design override."},"permission_overrides":{"type":"object","additionalProperties":false,"description":"Per-member permission overrides. Editors accept approvals:design and approvals:launch; Viewers accept only approvals:design and any other key returns 422; legacy client roles reject every override.","properties":{"approvals:design":{"type":"boolean"},"approvals:launch":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Member updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"delete":{"summary":"Remove a shop member","tags":["Team"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["shop_id"],"properties":{"shop_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Member removed","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops":{"get":{"summary":"List organization shops","tags":["Shops"],"responses":{"200":{"description":"Shop list","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShopSummary"}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"post":{"summary":"Create a shop","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","domain","platform"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"domain":{"type":"string","minLength":1,"maxLength":253},"platform":{"type":"string","enum":["shopify","hydrogen","shopware","woocommerce","centra","webflow","custom"]},"plan":{"type":"string","enum":["managed","self_serve"],"default":"self_serve","description":"Provisioning plan. Omitting it defaults to self_serve. The self_serve value provisions the self_managed tier; managed provisions the apex_managed tier."},"origin":{"type":["string","null"],"maxLength":2048},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLE","SOS","SRD","SSP","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UYW","UZS","VES","VND","VUV","WST","XAF","XCD","XCG","XDR","XOF","XPF","XSU","YER","ZAR","ZMW","ZWG"],"description":"Assigned ISO-4217 currency code"}}}}}},"responses":{"201":{"description":"Shop created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Shop"},{"type":"object","required":["setup"],"properties":{"setup":{"type":"object","description":"Per-step provisioning outcomes (snippet, edge, hostname). A step can report status \"error\" while the shop row itself was created."},"sandbox":{"type":"boolean","description":"Present and true when the shop was created without claiming the live domain binding — the creating organization is flagged internal, so the domain stays available for a live shop. Omitted otherwise."}}}]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The domain already has a live binding. Owner details are included only when the caller may see the owning shop.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["message","status"],"properties":{"message":{"type":"string"},"status":{"type":"integer","const":409}}},"conflict":{"type":"object","additionalProperties":false,"required":["domain","owner_shop_id","owner_shop_name"],"properties":{"domain":{"type":"string"},"owner_shop_id":{"type":"string","format":"uuid"},"owner_shop_name":{"type":"string"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a shop","tags":["Shops"],"responses":{"200":{"description":"Shop detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"summary":"Update a shop","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"domain":{"type":"string","minLength":1,"maxLength":253},"origin":{"type":["string","null"],"maxLength":2048},"tier":{"type":"string","enum":["self_managed","apex_managed","drip_managed","core","managed","enterprise"],"description":"Platform-operator field; requires operator:write. The deprecated write aliases core, managed, and enterprise are mapped server-side. Responses return only self_managed, apex_managed, and drip_managed."},"operator_enabled":{"type":"boolean","description":"Platform-operator field; requires operator:write."},"holdout_pct":{"type":"number","minimum":0,"maximum":10,"description":"Platform-operator field; requires operator:write."},"holdout_v1_enabled":{"type":"boolean","description":"Platform-operator field; requires operator:write."},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLE","SOS","SRD","SSP","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UYW","UZS","VES","VND","VUV","WST","XAF","XCD","XCG","XDR","XOF","XPF","XSU","YER","ZAR","ZMW","ZWG"],"description":"Assigned ISO-4217 currency code"}}}}}},"responses":{"200":{"description":"Shop updated","content":{"application/json":{"schema":{"type":"object","required":["ok","shop"],"properties":{"ok":{"type":"boolean","const":true},"shop":{"$ref":"#/components/schemas/Shop"}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/shops/{id}/audit-logs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List audit logs for an authorized shop with a user API key","tags":["Audit logs","Shops"],"parameters":[{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"entity_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Audit log page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"pagination":{"type":"object","additionalProperties":false,"required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/shops/{id}/shopware/prebind":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Pre-bind a Shopware store to an Apex shop","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["shopUrl"],"properties":{"shopUrl":{"type":"string","format":"uri","maxLength":2048},"environmentKey":{"type":"string","minLength":1,"maxLength":48,"default":"production","description":"Configured Apex environment key for this Shopware installation."}}}}}},"responses":{"200":{"description":"Existing binding returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"201":{"description":"Pending binding created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/auto-stop":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get auto-stop settings","tags":["Shops"],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","required":["auto_stop_defaults"],"properties":{"auto_stop_defaults":{"type":"object","additionalProperties":false,"description":"Complete merged auto-stop settings.","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["off","fixed_horizon_planned_end","sequential_significance"]},"min_runtime_minutes":{"type":"integer","minimum":0},"sequential":{"type":"object","additionalProperties":false,"properties":{"min_visitors":{"type":"integer","minimum":1},"min_conversions":{"type":"integer","minimum":1},"action_on_significant":{"type":"string","enum":["pause"]}}},"fixed_horizon":{"type":"object","additionalProperties":false,"properties":{"window_days":{"type":"integer","minimum":1,"maximum":120},"mde":{"type":"number","minimum":0.001,"maximum":1},"alpha":{"type":"number","minimum":0.001,"maximum":0.2},"power":{"type":"number","minimum":0.5,"maximum":0.99},"tail":{"type":"string","enum":["two-sided","one-sided"]},"auto_pause_on_inconclusive":{"type":"boolean"}}}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"patch":{"summary":"Update auto-stop settings","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Partial auto-stop patch merged over the current values.","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["off","fixed_horizon_planned_end","sequential_significance"]},"min_runtime_minutes":{"type":"integer","minimum":0},"sequential":{"type":"object","additionalProperties":false,"properties":{"min_visitors":{"type":"integer","minimum":1},"min_conversions":{"type":"integer","minimum":1},"action_on_significant":{"type":"string","enum":["pause"]}}},"fixed_horizon":{"type":"object","additionalProperties":false,"properties":{"window_days":{"type":"integer","minimum":1,"maximum":120},"mde":{"type":"number","minimum":0.001,"maximum":1},"alpha":{"type":"number","minimum":0.001,"maximum":0.2},"power":{"type":"number","minimum":0.5,"maximum":0.99},"tail":{"type":"string","enum":["two-sided","one-sided"]},"auto_pause_on_inconclusive":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Settings updated","content":{"application/json":{"schema":{"type":"object","required":["auto_stop_defaults"],"properties":{"auto_stop_defaults":{"type":"object","additionalProperties":false,"description":"Complete merged auto-stop settings.","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["off","fixed_horizon_planned_end","sequential_significance"]},"min_runtime_minutes":{"type":"integer","minimum":0},"sequential":{"type":"object","additionalProperties":false,"properties":{"min_visitors":{"type":"integer","minimum":1},"min_conversions":{"type":"integer","minimum":1},"action_on_significant":{"type":"string","enum":["pause"]}}},"fixed_horizon":{"type":"object","additionalProperties":false,"properties":{"window_days":{"type":"integer","minimum":1,"maximum":120},"mde":{"type":"number","minimum":0.001,"maximum":1},"alpha":{"type":"number","minimum":0.001,"maximum":0.2},"power":{"type":"number","minimum":0.5,"maximum":0.99},"tail":{"type":"string","enum":["two-sided","one-sided"]},"auto_pause_on_inconclusive":{"type":"boolean"}}}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}/testing-defaults":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get testing-defaults settings","tags":["Shops"],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","required":["testing_defaults"],"properties":{"testing_defaults":{"type":"object","additionalProperties":false,"description":"Complete merged testing-defaults settings.","properties":{"significanceLevel":{"type":"number","minimum":0.8,"maximum":0.99},"statisticalPower":{"type":"number","minimum":0.5,"maximum":0.99},"sequentialTestingEnabled":{"type":"boolean"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"patch":{"summary":"Update testing-defaults settings","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Partial testing-defaults patch merged over the current values.","properties":{"significanceLevel":{"type":"number","minimum":0.8,"maximum":0.99},"statisticalPower":{"type":"number","minimum":0.5,"maximum":0.99},"sequentialTestingEnabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Settings updated","content":{"application/json":{"schema":{"type":"object","required":["testing_defaults"],"properties":{"testing_defaults":{"type":"object","additionalProperties":false,"description":"Complete merged testing-defaults settings.","properties":{"significanceLevel":{"type":"number","minimum":0.8,"maximum":0.99},"statisticalPower":{"type":"number","minimum":0.5,"maximum":0.99},"sequentialTestingEnabled":{"type":"boolean"}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}/guardian":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get guardian settings","tags":["Shops"],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","required":["guardian_defaults"],"properties":{"guardian_defaults":{"type":"object","additionalProperties":false,"description":"Complete merged guardian settings.","properties":{"enabled":{"type":"boolean"},"pause_on_broken":{"type":"boolean"},"pause_on_harm":{"type":"boolean"},"alert_on_data_quality":{"type":"boolean"},"delivery_drift":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"missRateThreshold":{"type":"number","minimum":0,"maximum":1},"minSamples":{"type":"integer","minimum":1},"consecutiveChecks":{"type":"integer","minimum":1},"shouldPause":{"type":"boolean"}}},"revenue_loss":{"type":["object","null"],"additionalProperties":false,"description":"Shop revenue-loss pause threshold; null disables it.","required":["enabled","threshold_amount","currency"],"properties":{"enabled":{"type":"boolean"},"threshold_amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}}}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}},"patch":{"summary":"Update guardian settings","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Partial guardian patch merged over the current values.","properties":{"enabled":{"type":"boolean"},"pause_on_broken":{"type":"boolean"},"pause_on_harm":{"type":"boolean"},"alert_on_data_quality":{"type":"boolean"},"delivery_drift":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"missRateThreshold":{"type":"number","minimum":0,"maximum":1},"minSamples":{"type":"integer","minimum":1},"consecutiveChecks":{"type":"integer","minimum":1},"shouldPause":{"type":"boolean"}}},"revenue_loss":{"type":["object","null"],"additionalProperties":false,"description":"Shop revenue-loss pause threshold; null disables it.","required":["enabled","threshold_amount","currency"],"properties":{"enabled":{"type":"boolean"},"threshold_amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}}}}}}}},"responses":{"200":{"description":"Settings updated","content":{"application/json":{"schema":{"type":"object","required":["guardian_defaults"],"properties":{"guardian_defaults":{"type":"object","additionalProperties":false,"description":"Complete merged guardian settings.","properties":{"enabled":{"type":"boolean"},"pause_on_broken":{"type":"boolean"},"pause_on_harm":{"type":"boolean"},"alert_on_data_quality":{"type":"boolean"},"delivery_drift":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"missRateThreshold":{"type":"number","minimum":0,"maximum":1},"minSamples":{"type":"integer","minimum":1},"consecutiveChecks":{"type":"integer","minimum":1},"shouldPause":{"type":"boolean"}}},"revenue_loss":{"type":["object","null"],"additionalProperties":false,"description":"Shop revenue-loss pause threshold; null disables it.","required":["enabled","threshold_amount","currency"],"properties":{"enabled":{"type":"boolean"},"threshold_amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}}}}}}}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}/store-profile":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get the store profile","tags":["Shops"],"responses":{"200":{"description":"The complete dashboard Store Profile contract. When the store-profile schema is not yet migrated, the route degrades to `{ schemaReady: false }` with HTTP 200 instead of failing.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/StoreProfileResponse"},{"type":"object","additionalProperties":false,"required":["schemaReady"],"properties":{"schemaReady":{"type":"boolean","enum":[false]}}}]}}},"headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"description":"Store profile temporarily unavailable (database under pressure); retry shortly.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}/store-profile/facts/{factId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"factId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"summary":"Review a store-profile fact","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["suggested","confirmed","rejected","stale"]},"claim":{"type":"string","maxLength":900},"value":{"description":"Arbitrary JSON value"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Fact reviewed","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}/store-profile/findings/review":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Review a semantic finding","tags":["Shops"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","claim"],"properties":{"key":{"type":"string","maxLength":160},"claim":{"type":"string","maxLength":900},"status":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"source":{"type":"string"},"confidence":{"type":"number"},"value":{"description":"Arbitrary JSON value"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Finding reviewed","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}/store-profile/learning-runs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Start a store-profile learning run","tags":["Shops"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"trigger":{"type":"string","default":"manual"},"sources":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}}}},"responses":{"201":{"description":"Learning run queued","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}}}},"/shops/{id}/engine":{"get":{"summary":"Get engine state and guardrails","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engine state","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"state":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["off","on","paused"]},"status_changed_at":{"type":"string","format":"date-time"},"status_changed_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["status"]},"guardrails":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"allow_trust":{"type":"boolean"},"allow_urgency":{"type":"boolean"},"allow_crosssell":{"type":"boolean"},"allow_reassurance":{"type":"boolean"},"allow_capture":{"type":"boolean"},"auto_launch_trust":{"type":"boolean"},"auto_launch_urgency":{"type":"boolean"},"auto_launch_crosssell":{"type":"boolean"},"auto_launch_reassurance":{"type":"boolean"},"auto_launch_capture":{"type":"boolean"},"surfaces":{"type":"object","additionalProperties":false,"properties":{"home":{"type":"boolean"},"collections":{"type":"boolean"},"pdp":{"type":"boolean"},"cart":{"type":"boolean"}},"required":["home","collections","pdp","cart"]},"segments":{},"max_concurrent":{"type":"integer","minimum":1,"maximum":8},"max_per_page":{"type":"integer","minimum":1,"maximum":3},"updated_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","shop_id","version","allow_trust","allow_urgency","allow_crosssell","allow_reassurance","allow_capture","auto_launch_trust","auto_launch_urgency","auto_launch_crosssell","auto_launch_reassurance","auto_launch_capture","surfaces","segments","max_concurrent","max_per_page","updated_by","created_at","updated_at"]},{"type":"null"}]},"version":{"type":["integer","null"],"minimum":1}},"required":["state","guardrails","version"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/guardrails":{"get":{"summary":"Get engine guardrails","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engine guardrails","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"allow_trust":{"type":"boolean"},"allow_urgency":{"type":"boolean"},"allow_crosssell":{"type":"boolean"},"allow_reassurance":{"type":"boolean"},"allow_capture":{"type":"boolean"},"auto_launch_trust":{"type":"boolean"},"auto_launch_urgency":{"type":"boolean"},"auto_launch_crosssell":{"type":"boolean"},"auto_launch_reassurance":{"type":"boolean"},"auto_launch_capture":{"type":"boolean"},"surfaces":{"type":"object","additionalProperties":false,"properties":{"home":{"type":"boolean"},"collections":{"type":"boolean"},"pdp":{"type":"boolean"},"cart":{"type":"boolean"}},"required":["home","collections","pdp","cart"]},"segments":{},"max_concurrent":{"type":"integer","minimum":1,"maximum":8},"max_per_page":{"type":"integer","minimum":1,"maximum":3},"updated_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","shop_id","version","allow_trust","allow_urgency","allow_crosssell","allow_reassurance","allow_capture","auto_launch_trust","auto_launch_urgency","auto_launch_crosssell","auto_launch_reassurance","auto_launch_capture","surfaces","segments","max_concurrent","max_per_page","updated_by","created_at","updated_at"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}},"patch":{"summary":"Update engine guardrails with optimistic concurrency","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["expected_version"],"properties":{"expected_version":{"type":"integer","minimum":0},"allow":{"type":"object","additionalProperties":false,"properties":{"trust":{"type":"boolean"},"urgency":{"type":"boolean"},"crosssell":{"type":"boolean"},"reassurance":{"type":"boolean"},"capture":{"type":"boolean"}}},"auto_launch":{"type":"object","additionalProperties":false,"properties":{"trust":{"type":"boolean"},"urgency":{"type":"boolean"},"crosssell":{"type":"boolean"},"reassurance":{"type":"boolean"},"capture":{"type":"boolean"}}},"surfaces":{"type":"object","additionalProperties":false,"properties":{"home":{"type":"boolean"},"collections":{"type":"boolean"},"pdp":{"type":"boolean"},"cart":{"type":"boolean"}},"required":["home","collections","pdp","cart"]},"segments":{},"max_concurrent":{"type":"integer","minimum":1,"maximum":8},"max_per_page":{"type":"integer","minimum":1,"maximum":3}}}}}},"responses":{"200":{"description":"Updated engine guardrails","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"allow_trust":{"type":"boolean"},"allow_urgency":{"type":"boolean"},"allow_crosssell":{"type":"boolean"},"allow_reassurance":{"type":"boolean"},"allow_capture":{"type":"boolean"},"auto_launch_trust":{"type":"boolean"},"auto_launch_urgency":{"type":"boolean"},"auto_launch_crosssell":{"type":"boolean"},"auto_launch_reassurance":{"type":"boolean"},"auto_launch_capture":{"type":"boolean"},"surfaces":{"type":"object","additionalProperties":false,"properties":{"home":{"type":"boolean"},"collections":{"type":"boolean"},"pdp":{"type":"boolean"},"cart":{"type":"boolean"}},"required":["home","collections","pdp","cart"]},"segments":{},"max_concurrent":{"type":"integer","minimum":1,"maximum":8},"max_per_page":{"type":"integer","minimum":1,"maximum":3},"updated_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","shop_id","version","allow_trust","allow_urgency","allow_crosssell","allow_reassurance","allow_capture","auto_launch_trust","auto_launch_urgency","auto_launch_crosssell","auto_launch_reassurance","auto_launch_capture","surfaces","segments","max_concurrent","max_per_page","updated_by","created_at","updated_at"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/start":{"post":{"summary":"Start engine","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engine state updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["off","on","paused"]},"status_changed_at":{"type":"string","format":"date-time"},"status_changed_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/pause":{"post":{"summary":"Pause engine","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engine state updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["off","on","paused"]},"status_changed_at":{"type":"string","format":"date-time"},"status_changed_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/stop":{"post":{"summary":"Stop engine","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engine state updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["off","on","paused"]},"status_changed_at":{"type":"string","format":"date-time"},"status_changed_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/proposals/{pid}/approve":{"post":{"summary":"Approve engine proposal","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"pid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engine proposal approve decision recorded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["trust","urgency","crosssell","reassurance","capture"]},"surface":{"type":"string","enum":["home","collections","pdp","cart"]},"status":{"type":"string","enum":["proposed","approved","rejected","expired","vetoed"]},"decided_by":{"type":["string","null"],"format":"uuid"},"decided_at":{"type":["string","null"],"format":"date-time"},"rejection_reason":{"type":["string","null"]},"auto_launch_at":{"type":["string","null"],"format":"date-time"}},"required":["id","shop_id","category","surface","status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/proposals/{pid}/reject":{"post":{"summary":"Reject engine proposal","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"pid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}},"responses":{"200":{"description":"Engine proposal reject decision recorded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["trust","urgency","crosssell","reassurance","capture"]},"surface":{"type":"string","enum":["home","collections","pdp","cart"]},"status":{"type":"string","enum":["proposed","approved","rejected","expired","vetoed"]},"decided_by":{"type":["string","null"],"format":"uuid"},"decided_at":{"type":["string","null"],"format":"date-time"},"rejection_reason":{"type":["string","null"]},"auto_launch_at":{"type":["string","null"],"format":"date-time"}},"required":["id","shop_id","category","surface","status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/proposals/{pid}/veto":{"post":{"summary":"Veto engine proposal","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"pid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engine proposal veto decision recorded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"shop_id":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["trust","urgency","crosssell","reassurance","capture"]},"surface":{"type":"string","enum":["home","collections","pdp","cart"]},"status":{"type":"string","enum":["proposed","approved","rejected","expired","vetoed"]},"decided_by":{"type":["string","null"],"format":"uuid"},"decided_at":{"type":["string","null"],"format":"date-time"},"rejection_reason":{"type":["string","null"]},"auto_launch_at":{"type":["string","null"],"format":"date-time"}},"required":["id","shop_id","category","surface","status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}}}},"/shops/{id}/engine/interventions/{iid}/rollout":{"post":{"summary":"Roll a certified Engine winner out to 100% of traffic","description":"Sends all eligible traffic to the winning variation, freezes the certified interval, and starts the decay watch. The program holdout is untouched.","tags":["Shops"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"iid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"expected_updated_at":{"type":"string","format":"date-time"}},"required":["expected_updated_at"]}}}},"responses":{"200":{"description":"Engine intervention rolled out","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"intervention_id":{"type":"string","format":"uuid"},"experiment_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["rolledout"]},"rolled_out_at":{"type":"string","format":"date-time"},"certified_lift":{"type":"number"},"certified_ci_low":{"type":"number"},"certified_ci_high":{"type":["number","null"]},"publication_status":{"type":"string"}},"required":["intervention_id","experiment_id","status","rolled_out_at","certified_lift","certified_ci_low","publication_status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Rollout refused","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"A refused rollout. `code` separates a stale row (refresh and retry) from a precondition refusal (this intervention cannot be rolled out).","properties":{"error":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[409]},"code":{"type":"string","enum":["engine_rollout_stale","engine_rollout_precondition"]}},"required":["message","status","code"]}},"required":["error"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"description":"Either the certified measurement could not be read (rollout refused, retriable) or the rate-limiting backend is unavailable. Both are plain error envelopes; only the first carries a rollout `code`.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"description":"The certified measurement could not be read, so the rollout was refused without shipping anything. Retry after the Retry-After delay.","properties":{"error":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"},"status":{"type":"integer","enum":[503]},"code":{"type":"string","enum":["engine_rollout_measurement_unavailable"]},"retriable":{"type":"boolean","enum":[true]}},"required":["message","status","code","retriable"]}},"required":["error"]},{"$ref":"#/components/schemas/Error"}]}}}}}}},"/analytics/entry-exit":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":30,"maximum":90,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDataResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show entry and exit page analytics","tags":["Analytics"]}},"/analytics/geo":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":30,"maximum":90,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDataResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show geography and device analytics","tags":["Analytics"]}},"/analytics/pages":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":30,"maximum":90,"minimum":1,"type":"integer"}},{"description":"Planning window in days (planning_days is also accepted)","in":"query","name":"planningDays","required":false,"schema":{"default":180,"maximum":365,"minimum":30,"type":"integer"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDataResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show page analytics","tags":["Analytics"]}},"/analytics/realtime":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDataResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show realtime analytics","tags":["Analytics"]}},"/analytics/sessions":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":30,"maximum":90,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDataResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show session analytics","tags":["Analytics"]}},"/analytics/stats":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":7,"maximum":90,"minimum":1,"type":"integer"}},{"in":"query","name":"shop_currency","required":false,"schema":{"description":"Assigned ISO-4217 currency code","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLE","SOS","SRD","SSP","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UYW","UZS","VES","VND","VUV","WST","XAF","XCD","XCG","XDR","XOF","XPF","XSU","YER","ZAR","ZMW","ZWG"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsStatsResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show dashboard analytics stats","tags":["Analytics"]}},"/analytics/suggest-goals":{"post":{"description":"Requires a secret API key with the analytics:read scope. The endpoint only reads analytics and returns suggestions — it creates no goals — but it spends model budget, so publishable keys receive 403 Forbidden and a per-shop 24-hour spend guard applies on top of the normal API rate limit.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"funnels":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"goals":{"items":{"additionalProperties":true,"properties":{"eventName":{"type":"string"},"explanation":{"type":"string"},"name":{"type":"string"},"selector":{"type":"string"},"type":{"enum":["click","pageview","custom","revenue"],"type":"string"},"urlPattern":{"type":"string"}},"required":["name","type"],"type":"object"},"type":"array"},"triggers":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"required":["goals","funnels","triggers"],"type":"object"}}},"description":"Suggested goals and funnels","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Request body is too large","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The suggestion model returned unusable output","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Suggest goals and funnels","tags":["Analytics","Goals"]}},"/analytics/timeseries":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":30,"maximum":90,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDataResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show analytics timeseries","tags":["Analytics"]}},"/analytics/traffic":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":30,"maximum":90,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsDataResponse"}}},"description":"Analytics data","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show traffic sources","tags":["Analytics"]}},"/analytics/url-inventory":{"get":{"description":"Returns a shaped Tinybird pageview URL inventory for the API key's shop. Requires a secret API key with analytics:read.","parameters":[{"in":"query","name":"days","required":false,"schema":{"default":14,"maximum":90,"minimum":1,"type":"integer"}},{"in":"query","name":"host","required":false,"schema":{"type":"string"}},{"in":"query","name":"pathContains","required":false,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"maximum":10000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"host":{"type":"string"},"pageviews":{"type":"integer"},"path":{"type":"string"},"visitors":{"type":"integer"}},"required":["host","path","pageviews","visitors"],"type":"object"},"type":"array"},"total":{"type":"integer"},"truncated":{"type":"boolean"}},"required":["items","total","truncated"],"type":"object"}}},"description":"URL inventory","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show URL inventory","tags":["Analytics"]}},"/analytics/visitor-series":{"get":{"parameters":[{"in":"query","name":"days","required":false,"schema":{"default":60,"maximum":180,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"date":{"format":"date","type":"string"},"pageviews":{"type":"integer"},"visitors":{"type":"integer"}},"required":["date","visitors","pageviews"],"type":"object"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Daily visitors and pageviews","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Analytics is temporarily unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Show daily visitor series","tags":["Analytics"]}},"/assets":{"get":{"parameters":[{"description":"Include archived assets.","in":"query","name":"include_archived","schema":{"default":false,"type":"boolean"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Asset"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"Assets with cursor pagination","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List assets"},"post":{"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"files":{"items":{"format":"binary","type":"string"},"maxItems":12,"minItems":1,"type":"array"}},"required":["files"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"assets":{"items":{"$ref":"#/components/schemas/Asset"},"type":"array"}},"required":["assets"],"type":"object"}}},"description":"Uploaded assets","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"Too many files or a file exceeds the upload size limit.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Upload assets"}},"/assets/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"description":"Asset","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get asset"},"delete":{"description":"Archives the asset without deleting its stored file; it can be restored.","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Deleted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Archive asset"}},"/assets/{id}/restore":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"description":"Restored asset","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Restore asset"}},"/audit-logs":{"get":{"parameters":[{"in":"query","name":"entity_type","schema":{"type":"string"}},{"in":"query","name":"entity_id","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AuditLog"},"type":"array"},"pagination":{"additionalProperties":false,"properties":{"has_more":{"type":"boolean"},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["total","limit","offset","has_more"],"type":"object"}},"type":"object"}}},"description":"Audit log page","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"List audit logs","tags":["Audit logs"]}},"/brand-context":{"get":{"description":"Returns the compiled shop brand context for external agents and developer workflows. Internal Apex notes are never included.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/BrandContext"}},"required":["data"],"type":"object"}}},"description":"Compiled brand context","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing experiment read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get brand context","tags":["Brand"]}},"/consent":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentSettingsResponse"}}},"description":"Consent settings","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Read consent gating settings","tags":["Consent"]},"patch":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"applyCanonicalSplit":{"description":"Applies the canonical consent-safe split. Only `true` is accepted: clearing the shop-wide showVariationsRule/startTrackingRule prerequisites is a dashboard (shop:settings) action and returns 403 here.","enum":[true],"type":"boolean"},"consentMode":{"type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentSettingsResponse"}}},"description":"Updated consent settings","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update consent gating settings","tags":["Consent"]}},"/data-deletion":{"get":{"parameters":[{"in":"query","name":"request_id","schema":{"format":"uuid","type":"string"}},{"in":"query","name":"visitor_id","schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion status","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Read data-deletion status"},"post":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"visitor_id":{"minLength":1,"type":"string"}},"required":["visitor_id"],"type":"object"}}},"required":true},"responses":{"202":{"description":"Deletion accepted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Request data deletion"}},"/data-export":{"get":{"parameters":[{"in":"query","name":"request_id","schema":{"format":"uuid","type":"string"}},{"in":"query","name":"visitor_id","schema":{"type":"string"}}],"responses":{"200":{"description":"Data export","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Export personal data"},"post":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"limit":{"maximum":50000,"minimum":1,"type":"integer"},"visitor_id":{"minLength":1,"type":"string"}},"required":["visitor_id"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Completed data export","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Request a personal data export"}},"/environments":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentsResponse"}}},"description":"Environment settings","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List runtime environments and domain mappings","tags":["Environments"]},"patch":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"environments":{"$ref":"#/components/schemas/Environments"},"expected_version":{"description":"Optional version returned by GET. The write conflicts if settings changed after that read.","format":"date-time","type":["string","null"]}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentsPatchResponse"}}},"description":"Updated environment settings and edge precompile outcome","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The environment patch is invalid, including when the active key is absent from the effective environment items.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Runtime settings changed since the supplied version was read; re-read and retry.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update runtime environments and domain mappings","tags":["Environments"]}},"/exclusion-groups":{"get":{"parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}},{"description":"Include archived exclusion groups.","in":"query","name":"include_archived","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ExclusionGroup"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"exclusion groups list","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List exclusion groups"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroupInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroup"}}},"description":"exclusion groups created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Create exclusion groups"}},"/exclusion-groups/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroup"}}},"description":"exclusion group returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get exclusion group"},"patch":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroupUpdateInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroup"}}},"description":"exclusion group returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update exclusion group"},"delete":{"description":"Archives the group while preserving membership.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"publication_warning":{"additionalProperties":false,"description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","properties":{"code":{"enum":["storefront_publication_incomplete"],"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["ok"],"type":"object"}}},"description":"exclusion group deleted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Archive exclusion group"}},"/exclusion-groups/{id}/members":{"put":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroupMembersInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroup"}}},"description":"Exclusion group members replaced","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Replace exclusion group members"}},"/exclusion-groups/{id}/restore":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExclusionGroup"}}},"description":"Exclusion group restored","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Restore exclusion group"}},"/external-pixels/snippet":{"post":{"description":"Requires a secret API key with the external_pixels:write scope; the response embeds a signed ingest credential, so read-scoped and publishable keys receive 403 Forbidden.","requestBody":{"content":{"application/json":{"schema":{"properties":{"globalName":{"maxLength":80,"type":"string"},"handoverParam":{"maxLength":80,"type":"string"},"provider":{"maxLength":80,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalPixelSnippet"}}},"description":"Generated snippet","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Generate external purchase pixel snippet"}},"/flags":{"get":{"parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FeatureFlag"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"Flags with cursor pagination","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List flags"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlag"}}},"description":"Created flag","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Create flag"}},"/flags/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlag"}}},"description":"Flag","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get flag"},"patch":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagUpdateInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlag"}}},"description":"Updated flag","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update flag"}},"/flags/{id}/activate":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlag"}}},"description":"Updated flag","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Activate flag"}},"/flags/{id}/archive":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlag"}}},"description":"Updated flag","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Archive flag"}},"/flags/{id}/pause":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlag"}}},"description":"Updated flag","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Pause flag"}},"/flags/{id}/status":{"get":{"description":"Returns database publication metadata, the propagation worst-case window derived from the shop's effective runtime cache TTLs, and, for visual flags, the public edge config URL used to confirm propagation. Edge propagation does not apply to API-delivered flags.","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"config_urls":{"items":{"format":"uri","type":"string"},"type":"array"},"edge_delivery":{"enum":["applicable","not_applicable"],"type":"string"},"edge_delivery_message":{"description":"For API delivery, warns that a cached visual payload may remain during the worst-case propagation window and that status uses a single vantage.","type":["string","null"]},"expected_worst_case_seconds":{"description":"Snippet TTL plus config TTL, using the shop's effective runtime values.","minimum":0,"type":"integer"},"flag":{"properties":{"delivery_type":{"enum":["visual","api"],"type":"string"},"environment_key":{"type":"string"},"id":{"format":"uuid","type":"string"},"key":{"type":"string"},"status":{"enum":["draft","active","paused","archived"],"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","key","status","delivery_type","environment_key","updated_at"],"type":"object"},"generated_at":{"format":"date-time","type":["string","null"]},"publication_revision":{"type":"integer"}},"required":["flag","publication_revision","generated_at","expected_worst_case_seconds","edge_delivery","edge_delivery_message","config_urls"],"type":"object"}}},"description":"Flag publication status","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get flag edge publication status"}},"/funnels":{"get":{"parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}},{"description":"Include archived funnels.","in":"query","name":"include_archived","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Funnel"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"funnels list","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List funnels"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunnelInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Funnel"}}},"description":"funnels created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Create funnels"}},"/funnels/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Funnel"}}},"description":"funnel returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get funnel"},"patch":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunnelUpdateInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Funnel"}}},"description":"funnel returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update funnel"},"delete":{"description":"Archives the funnel instead of destroying it.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"funnel deleted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Archive funnel"}},"/funnels/{id}/restore":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Funnel"}}},"description":"Restored funnel","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Restore funnel"}},"/funnels/{id}/run":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"days","schema":{"default":30,"maximum":365,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunnelRun"}}},"description":"Funnel run","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"502":{"description":"Analysis unavailable","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Run funnel analysis","tags":["Funnels"]}},"/goals":{"get":{"description":"Returns a paginated list of goals for the shop.","parameters":[{"in":"query","name":"cursor","schema":{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"}},{"description":"Include archived goals.","in":"query","name":"include_archived","schema":{"default":false,"type":"boolean"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Goal"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"type":"object"}}},"description":"Paginated list of goals","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List goals","tags":["Goals"]},"post":{"description":"Creates a new goal. Click goals require page_id plus selector or text_match. Pageview goals require page_id or url_pattern. Custom goals require event_name. Line-item filters are accepted for revenue goals and custom checkout_started/add_to_cart funnel-event goals.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"capture":{"anyOf":[{"items":{"$ref":"#/components/schemas/GoalCapture"},"type":"array"},{"type":"null"}]},"count_once":{"default":false,"type":"boolean"},"event_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"filter":{"anyOf":[{"$ref":"#/components/schemas/GoalFilter"},{"type":"null"}]},"measurement":{"default":"conversion","description":"Read-time analysis model. Any goal type may use conversion or value measurement.","enum":["conversion","value"],"type":"string"},"name":{"maxLength":255,"minLength":1,"type":"string"},"page_id":{"anyOf":[{"description":"Page scope. Required for click goals, optional for pageview goals, and not allowed for custom or revenue goals.","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"},{"type":"null"}]},"selector":{"anyOf":[{"type":"string"},{"type":"null"}]},"text_match":{"anyOf":[{"description":"Case-insensitive text match for click goals","type":"string"},{"type":"null"}]},"type":{"enum":["click","pageview","custom","revenue"],"type":"string"},"url_pattern":{"anyOf":[{"type":"string"},{"type":"null"}]},"value_property":{"anyOf":[{"description":"Only valid when measurement is value and type is not revenue; other combinations are rejected with 400.","maxLength":120,"minLength":1,"pattern":"^[A-Za-z0-9_.-]+$","type":"string"},{"type":"null"}]},"value_unit":{"anyOf":[{"description":"Only valid when measurement is value; rejected with 400 otherwise.","enum":["currency","number","duration_seconds","percent"],"type":"string"},{"type":"null"}]}},"required":["name","type"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Goal"}}},"description":"Goal created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Validation error","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Create goal","tags":["Goals"]}},"/goals/{id}":{"get":{"description":"Returns a single goal by ID.","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Goal"}}},"description":"Goal details","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Goal not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Get goal","tags":["Goals"]},"patch":{"description":"Partially updates a goal. Line-item filters are accepted for revenue goals and custom checkout_started/add_to_cart funnel-event goals. Custom goals may not listen on reserved wire event names (purchase, pageview, ...): the resulting type/event_name combination is validated against the stored row and rejected with 400 (funnel-event goal names are the sanctioned exception).","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"capture":{"anyOf":[{"items":{"$ref":"#/components/schemas/GoalCapture"},"type":"array"},{"type":"null"}]},"count_once":{"type":"boolean"},"event_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}]},"filter":{"anyOf":[{"$ref":"#/components/schemas/GoalFilter"},{"type":"null"}]},"measurement":{"description":"Read-time analysis model. Any goal type may use conversion or value measurement.","enum":["conversion","value"],"type":"string"},"name":{"maxLength":255,"minLength":1,"type":"string"},"page_id":{"anyOf":[{"description":"Page scope. Set null to clear it when the resulting goal type allows project-level scope.","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"},{"type":"null"}]},"selector":{"anyOf":[{"type":"string"},{"type":"null"}]},"text_match":{"anyOf":[{"description":"Case-insensitive text match for click goals","type":"string"},{"type":"null"}]},"type":{"enum":["click","pageview","custom","revenue"],"type":"string"},"url_pattern":{"anyOf":[{"type":"string"},{"type":"null"}]},"value_property":{"anyOf":[{"description":"Only valid when measurement is value and type is not revenue; other combinations are rejected with 400.","maxLength":120,"minLength":1,"pattern":"^[A-Za-z0-9_.-]+$","type":"string"},{"type":"null"}]},"value_unit":{"anyOf":[{"description":"Only valid when measurement is value; rejected with 400 otherwise.","enum":["currency","number","duration_seconds","percent"],"type":"string"},{"type":"null"}]}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Goal"}}},"description":"Goal updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Goal not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Update goal","tags":["Goals"]},"delete":{"description":"Archives a goal while preserving its experiment and personalization links.","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"},"id":{"format":"uuid","type":"string"},"publication_warning":{"additionalProperties":false,"description":"The write remains saved, but callers should treat storefront configuration as potentially stale.","properties":{"code":{"enum":["storefront_publication_incomplete"],"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"type":"object"}}},"description":"Goal deleted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Goal not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Archive goal","tags":["Goals"]}},"/goals/{id}/restore":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Goal"}}},"description":"Goal restored","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Goal not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Restore goal","tags":["Goals"]}},"/inbox/messages":{"get":{"parameters":[{"in":"query","name":"experiment_id","schema":{"format":"uuid","type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/InboxMessage"},"type":"array"}},"type":"object"}}},"description":"Inbox messages","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"List inbox messages","tags":["Inbox"]},"post":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"body":{"maxLength":10000,"minLength":1,"type":"string"},"experiment_id":{"anyOf":[{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"},{"type":"null"}]},"thread_type":{"default":"account","enum":["account","experiment"],"type":"string"}},"required":["body"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"message":{"$ref":"#/components/schemas/InboxMessage"}},"type":"object"}}},"description":"Message created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Send an inbox message","tags":["Inbox"]}},"/inbox/read-state":{"post":{"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"additionalProperties":false,"properties":{"channelKey":{"type":"string"}},"required":["channelKey"],"type":"object"},{"additionalProperties":false,"properties":{"all":{"const":true,"type":"boolean"}},"required":["all"],"type":"object"}]}}},"required":true},"responses":{"200":{"description":"Read state updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Mark inbox channels read","tags":["Inbox"]}},"/install-domains":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallDomainsResponse"}}},"description":"Install domains","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Read install domains and storefront origins","tags":["Install Domains"]},"patch":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"domains":{"items":{"type":"string"},"maxItems":10,"type":"array"},"ifRevision":{"type":"string"}},"required":["domains"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallDomainsResponse"}}},"description":"Updated install domains and edge precompile outcome","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Install domains changed since the supplied revision was read; re-read and retry.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Replace install domains","tags":["Install Domains"]}},"/landing-pages":{"get":{"description":"Requires the Apex Labs feature for the shop; shops without it receive 404 Not Found.","parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"format":"uuid","type":"string"}},{"in":"query","name":"status","schema":{"enum":["draft","qa_ready","published","archived","all"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/LandingPageSummary"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"Landing pages with cursor pagination","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Apex Labs is not enabled for this shop, so landing pages are unavailable.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List landing pages"}},"/landing-pages/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LandingPage"}}},"description":"Landing page","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get landing page"}},"/me":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"account_scoped":{"type":"boolean"},"expires_at":{"format":"date-time","type":"string"},"org_id":{"format":"uuid","type":["string","null"]},"org_role":{"enum":["owner","admin","member"],"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"user_id":{"format":"uuid","type":"string"}},"required":["user_id","org_id","scopes","expires_at"],"type":"object"}},"required":["data"],"type":"object"}}},"description":"User key identity and live organization role","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"security":[{"bearerAuth":[]}],"summary":"Inspect the current user API key identity","tags":["User keys"]}},"/me/context":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"key":{"additionalProperties":false,"properties":{"account_scoped":{"type":"boolean"},"id":{"format":"uuid","type":"string"},"org_id":{"format":"uuid","type":["string","null"]}},"required":["id","account_scoped","org_id"],"type":"object"},"orgs":{"items":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"role":{"description":"guest = reachable only through a direct shop membership; the org row groups those shops","enum":["owner","admin","member","guest"],"type":"string"},"shops":{"items":{"additionalProperties":false,"properties":{"domain":{"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"role":{"enum":["owner","admin","editor","viewer","analyst","client_viewer","client_approver"],"type":"string"}},"required":["id","name","domain","role"],"type":"object"},"type":"array"}},"required":["id","name","role","shops"],"type":"object"},"type":"array"},"user_id":{"format":"uuid","type":"string"}},"required":["user_id","key","orgs"],"type":"object"}},"required":["data"],"type":"object"}}},"description":"User key context with effective organization and shop roles","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"security":[{"bearerAuth":[]}],"summary":"List every organization and shop available to a user API key","tags":["User keys"]}},"/pages":{"get":{"parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Page"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"pages list","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List pages"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}},"description":"pages created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Create pages"}},"/pages/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}},"description":"page returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get page"},"patch":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageUpdateInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}},"description":"page returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PageLiveImpactError"},{"$ref":"#/components/schemas/Error"}]}}},"description":"Conflict. A live-consumer acknowledgement conflict returns the PageLiveImpactError shape — repeat the request with confirm_live_impact and confirmed_consumer_ids carrying every id listed. A trigger-propagation race or duplicate API name returns the generic Error shape.","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update page"},"delete":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"page deleted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Delete page"}},"/roadmap/approved":{"get":{"description":"Returns approved backlog/roadmap ideas ready to build in Apex. This is the API used by `apex roadmap approved`.","parameters":[{"in":"query","name":"limit","schema":{"default":25,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"format":"uuid","type":"string"}},{"description":"Search title, description, hypothesis, brief, and research notes.","in":"query","name":"q","schema":{"type":"string"}},{"description":"When false, only returns approved ideas without a linked experiment. When true, only returns ideas with a linked experiment.","in":"query","name":"has_experiment","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"type":"object"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"Approved roadmap ideas","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing backlog read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List approved roadmap ideas","tags":["Roadmap"]}},"/roadmap/items/{id}/handoff":{"get":{"description":"Returns the full build brief for an approved roadmap item, including hypothesis, target page, visual references, scoring, and Apex CLI workspace commands.","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Roadmap build handoff","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing backlog read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"404":{"description":"Roadmap item not found","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get roadmap build handoff","tags":["Roadmap"]}},"/runtime-settings":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"runtime_settings":{"additionalProperties":true,"properties":{"projectCode":{"additionalProperties":false,"properties":{"css":{"maxLength":20000,"type":"string"},"enabled":{"type":"boolean"},"helperJs":{"maxLength":20000,"type":"string"},"js":{"maxLength":20000,"type":"string"}},"required":["enabled","css","helperJs","js"],"type":"object"}},"required":["projectCode"],"type":"object"},"shop_id":{"format":"uuid","type":"string"},"version":{"description":"Opaque concurrency token. Preserve all fractional-second digits unchanged.","type":["string","null"]}},"required":["shop_id","runtime_settings","version"],"type":"object"}}},"description":"Parsed runtime settings with shop identity and opaque version","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Read public runtime settings","tags":["Runtime settings"]},"patch":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"anyOf":[{"required":["dataLayerTriggers"]},{"required":["setupCapture"]},{"required":["projectCode"]}],"properties":{"dataLayerTriggers":{"items":{"$ref":"#/components/schemas/DataLayerTrigger"},"maxItems":20,"type":"array"},"expectedVersion":{"format":"date-time","type":["string","null"]},"projectCode":{"additionalProperties":false,"description":"Partial project code. Omitted fields are preserved. Null or blank code clears that field. Limits count characters, not bytes.","minProperties":1,"properties":{"css":{"maxLength":20000,"type":["string","null"]},"enabled":{"type":"boolean"},"helperJs":{"maxLength":20000,"type":["string","null"]},"js":{"maxLength":20000,"type":["string","null"]}},"type":"object"},"setupCapture":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"expiresAt":{"format":"date-time","type":["string","null"]},"layerNames":{"items":{"pattern":"^[A-Za-z_$][\\w$]*$","type":"string"},"maxItems":5,"type":"array"},"maxEventsPerSession":{"maximum":100,"minimum":1,"type":"integer"},"urlPatterns":{"items":{"maxLength":500,"type":"string"},"maxItems":10,"type":"array"}},"required":["enabled"],"type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"precompile":{"additionalProperties":true,"type":"object"},"runtime_settings":{"additionalProperties":true,"properties":{"projectCode":{"additionalProperties":false,"properties":{"css":{"maxLength":20000,"type":"string"},"enabled":{"type":"boolean"},"helperJs":{"maxLength":20000,"type":"string"},"js":{"maxLength":20000,"type":"string"}},"required":["enabled","css","helperJs","js"],"type":"object"}},"required":["projectCode"],"type":"object"},"shop_id":{"format":"uuid","type":"string"},"version":{"description":"Opaque concurrency token. Preserve all fractional-second digits unchanged.","type":["string","null"]},"warnings":{"description":"Non-blocking configuration warnings. An undeclared mapping target is persisted for targeting but not attached to exposure events.","items":{"type":"string"},"type":"array"},"writtenVersion":{"description":"Opaque version captured by this transaction; the current response version may include a later writer.","type":"string"}},"required":["shop_id","runtime_settings","precompile","version","writtenVersion"],"type":"object"}}},"description":"Updated runtime settings and precompile result","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update data layer triggers, setup capture, or project code","tags":["Runtime settings"]}},"/runtime-settings/recipes":{"post":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"expectedVersion":{"format":"date-time","type":["string","null"]},"params":{"additionalProperties":false,"description":"customDataLayerPurchase requires params with eventName, revenuePath, orderIdPath, and currencyPath. ga4Ecommerce takes no params: omit them or send an empty object; non-empty ga4Ecommerce params are rejected.","properties":{"costPath":{"type":"string"},"currencyPath":{"type":"string"},"dataLayerName":{"type":"string"},"eventName":{"type":"string"},"mappings":{"items":{"additionalProperties":false,"properties":{"from":{"type":"string"},"persist":{"type":"boolean"},"to":{"type":"string"},"ttlDays":{"type":"number"},"valueType":{"enum":["string","number","boolean","string_array","json"],"type":"string"}},"required":["from","to"],"type":"object"},"type":"array"},"orderIdPath":{"type":"string"},"profitPath":{"type":"string"},"properties":{"items":{"additionalProperties":false,"properties":{"from":{"type":"string"},"to":{"type":"string"},"valueType":{"enum":["string","number","boolean","string_array","json"],"type":"string"}},"required":["from","to"],"type":"object"},"type":"array"},"revenuePath":{"type":"string"}},"type":"object"},"recipeId":{"enum":["customDataLayerPurchase","ga4Ecommerce"],"type":"string"}},"required":["recipeId"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"precompile":{"additionalProperties":true,"type":"object"},"runtime_settings":{"additionalProperties":true,"type":"object"},"shop_id":{"format":"uuid","type":"string"},"warnings":{"description":"Non-blocking configuration warnings. An undeclared mapping target is persisted for targeting but not attached to exposure events.","items":{"type":"string"},"type":"array"}},"required":["shop_id","runtime_settings","precompile"],"type":"object"}}},"description":"Updated runtime settings and precompile result","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Apply a server-owned runtime integration recipe","tags":["Runtime settings"]}},"/segments":{"get":{"parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Segment"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"],"type":"object"}}},"description":"segments list","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List segments"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}},"description":"segments created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Create segments"}},"/segments/{id}":{"patch":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentUpdateInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}},"description":"segment returned","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update segment"},"delete":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"segment deleted","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Delete segment"}},"/signals":{"get":{"description":"The first page includes the built-in signal catalog before paginated custom signals. Built-ins do not participate in cursor pagination.","parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"format":"uuid","type":"string"}},{"description":"Include archived custom signals when true. Built-in signals are always active.","in":"query","name":"include_archived","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Signal"},"type":"array"},"pagination":{"properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["has_more","next_cursor"],"type":"object"}},"required":["data","pagination"],"type":"object"}}},"description":"Paginated signals","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List signals"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signal"}}},"description":"Created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Create a signal"}},"/signals/{id}":{"get":{"parameters":[{"description":"Custom signal UUID or built-in catalog signal key (e.g. url.full).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signal"}}},"description":"Resource","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Get a signal"},"patch":{"parameters":[{"description":"Custom signal UUID or built-in catalog signal key (e.g. url.full).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signal"}}},"description":"Updated","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Update a signal"},"delete":{"parameters":[{"description":"Custom signal UUID or built-in catalog signal key (e.g. url.full).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Deleted or archived","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Delete or archive a signal"}},"/sos":{"post":{"description":"Creates a customer bug report or help request for shop API keys. User API keys belonging to a DRIP platform administrator may also create internal SOS types.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"affected_url":{"anyOf":[{"format":"uri","maxLength":2000,"type":"string"},{"type":"null"}]},"description":{"maxLength":20000,"minLength":1,"type":"string"},"expected_behavior":{"maxLength":20000,"minLength":1,"type":"string"},"experiment_id":{"anyOf":[{"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","type":"string"},{"type":"null"}]},"idempotency_key":{"maxLength":200,"minLength":1,"type":"string"},"loom_url":{"anyOf":[{"format":"uri","maxLength":2000,"type":"string"},{"type":"null"}]},"reproduction_steps":{"anyOf":[{"maxLength":20000,"type":"string"},{"type":"null"}]},"sub_class":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}]},"type":{"enum":["full_handover","design","development","qa","config","bug","help"],"type":"string"}},"required":["type","description"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Reused internal SOS ticket or deduplicated customer ticket receipt","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"201":{"description":"Internal SOS ticket or customer ticket created","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing permission or requested an internal SOS type","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"502":{"description":"Jira create failed","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"description":"SOS is disabled","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}}},"summary":"Create SOS ticket","tags":["SOS"]}},"/sos/mine":{"get":{"description":"Lists SOS tickets created by the current API key.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"tickets":{"items":{"type":"object"},"type":"array"}},"required":["tickets"],"type":"object"}}},"description":"SOS tickets","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing experiment read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"List my SOS tickets","tags":["SOS"]}},"/tracking/discovery":{"get":{"description":"Aggregates consented-session QA diagnostic events (qa_mode=1) and normal-traffic pageview denominators (qa_mode=0) for the authenticated API key's shop.","parameters":[{"in":"query","name":"minutes","schema":{"default":10080,"maximum":20160,"minimum":1,"type":"integer"}},{"in":"query","name":"limit","schema":{"default":2000,"maximum":5000,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"consent_scope":{"type":"string"},"data_layer":{"items":{"type":"object"},"type":"array"},"ok":{"type":"boolean"},"scopes":{"type":"object"},"shop_id":{"type":"string"},"sources":{"type":"object"},"storage":{"items":{"type":"object"},"type":"array"},"trigger_diagnoses":{"items":{"properties":{"count":{"type":"integer"},"numericPaths":{"items":{"type":"string"},"type":"array"},"path":{"description":"Configured trigger payload path that failed extraction or comparison","type":"string"},"reason":{"type":"string"},"trigger":{"type":"string"},"url":{"description":"URL pathname where the failure was observed","type":"string"}},"required":["trigger","reason","path","url","numericPaths","count"],"type":"object"},"type":"array"},"unsupported":{"items":{"type":"object"},"type":"array"},"window":{"type":"object"}},"required":["ok","shop_id","window","consent_scope","scopes","sources","data_layer","unsupported","trigger_diagnoses","storage"],"type":"object"}}},"description":"Observed tracking schema report with URL push/pageview counts, timing percentiles, type-collision flags, and ranked storage keys","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing experiment read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Discover the observed tracking schema","tags":["Tracking"]}},"/tracking/simulate-trigger":{"post":{"description":"Pure dry run of dataLayerTriggers against payloads. Does not persist or emit events.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"payloads":{"items":{},"maxItems":50,"type":"array"},"triggers":{"items":{"additionalProperties":false,"properties":{"dataLayerName":{"type":"string"},"enabled":{"type":"boolean"},"eventName":{"minLength":1,"type":"string"},"mappings":{"items":{"type":"object"},"type":"array"},"reEvaluate":{"type":"boolean"},"trackEventName":{"type":"string"},"trackPageview":{"type":"boolean"},"trackRevenue":{"type":"object"},"when":{"items":{"$ref":"#/components/schemas/DataLayerTriggerWhenCondition"},"maxItems":5,"minItems":1,"type":"array"}},"required":["eventName"],"type":"object"},"maxItems":20,"type":"array"}},"required":["triggers","payloads"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"generated_at":{"description":"UTC timestamp ending in Z","format":"date-time","type":"string"},"results":{"items":{"type":"object"},"type":"array"},"shop_id":{"type":"string"},"summary":{"properties":{"currency_warnings":{"type":"integer"},"extracted_revenue":{"type":"integer"},"matched":{"type":"integer"},"total":{"type":"integer"}},"required":["matched","total","extracted_revenue","currency_warnings"],"type":"object"}},"required":["shop_id","generated_at","results","summary"],"type":"object"}}},"description":"Side-effect-free simulation verdict","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"Request body exceeds 64KB","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Simulate data-layer triggers","tags":["Tracking"]}},"/tracking/verify":{"get":{"description":"Returns recent Tinybird events for the API key's shop so agents can verify revenue, pageview, and custom tracking setup from the CLI.","parameters":[{"in":"query","name":"minutes","schema":{"default":120,"maximum":10080,"minimum":5,"type":"integer"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":200,"minimum":1,"type":"integer"}},{"in":"query","name":"experiment_id","schema":{"format":"uuid","type":"string"}},{"description":"Comma-separated event type filter.","in":"query","name":"event_type","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"filters":{"type":"object"},"ok":{"type":"boolean"},"recent_events":{"items":{"type":"object"},"type":"array"},"totals":{"type":"object"},"window":{"type":"object"}},"required":["ok","window","filters","totals","recent_events"],"type":"object"}}},"description":"Tracking verification summary","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"401":{"description":"Unauthorized","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"403":{"description":"API key is missing experiment read permission","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"429":{"description":"Rate limit exceeded","headers":{"X-Apex-API-Version":{"$ref":"#/components/headers/ApexApiVersion"}}},"503":{"$ref":"#/components/responses/DatabaseBusy"}},"summary":"Verify live tracking events","tags":["Tracking"]}}}}