{ "openapi": "3.0.0", "info": { "title": "Public API Reference", "version": "2025-07-30", "description": "\n\nThe Zephr Public API provides common client-side actions tied to a session cookie. Unlike the Admin API, neither users nor other resources can be dereferenced; the only data that can be accessed is owned by the user who is currently signed-in. This design is used to protect other users from malicious attacks.\n\nYou can find the base URL for the Public API by navigating to your site domains. To do this, select **Sites** from the **Delivery** menu, select your site, and then click the **Site Domains** button. The base URL is the Live domain.\n\nZephr forms use the Public API by default, with relative URLs based on the base URL.\n" }, "tags": [ { "name": "Authentication", "x-displayName": "Authentication" }, { "name": "Braintree Payments", "x-displayName": "Braintree Payments" }, { "name": "Browser Feature Transformations", "x-displayName": "Browser Feature Transformations" }, { "name": "Decision Engine", "x-displayName": "Decision Engine" }, { "name": "Dynamic Offer Decision Engine", "x-displayName": "Dynamic Offer Decision Engine" }, { "name": "Dynamic Offer Promo Code Decision", "x-displayName": "Dynamic Offer Promo Code Decision" }, { "name": "OAuth Flow", "x-displayName": "OAuth Flow" }, { "name": "Payments", "x-displayName": "Payments" }, { "name": "Product Sharing", "x-displayName": "Product Sharing" }, { "name": "SDK Feature Decision Engine", "x-displayName": "SDK Feature Decision Engine" }, { "name": "Sessions", "x-displayName": "Sessions" }, { "name": "Stripe Payments", "x-displayName": "Stripe Payments" }, { "name": "Third-Party Authentication", "description": "This section contains the API operations for the OAuth 2.0 Authorization Code Flow.", "x-displayName": "Third-Party Authentication" }, { "name": "User", "x-displayName": "User" }, { "name": "V4 Gifts", "description": "Create a Gift resource for V4. Gifts can be used to provide access to a particular URL for one session only by appending a gift token ID to the URL as the `gift` path parameter.", "x-displayName": "V4 Gifts" }, { "name": "Web Analytics", "x-displayName": "Web Analytics" }, { "name": "Zephr Features", "x-displayName": "Zephr Features" }, { "name": "Component Library", "x-displayName": "Component Library" } ], "servers": [ { "url": "https://{your-domain}", "variables": { "your-domain": { "default": "demo-site", "description": "The domain of your site." } } } ], "security": [ { "CookieBlaizeSession": [] }, { "JwtQuery": [] }, { "JwtHeaderXBlaizeJwt": [] }, { "JwtHeaderXZephrJwt": [] }, { "JwtBearer": [] }, { "JwtCookie": [] } ], "paths": { "/blaize/login": { "post": { "responses": { "200": { "description": "OK. The user has logged in successfully.", "headers": { "Set-Cookie": { "description": "The authenticated user session.", "schema": { "type": "string", "example": "blaize_session=443ed68f-0b44-4f32-8443-553d584cb0dd; Expires=Fri, 16 Nov 2024 12:35:56 GMT; Path=/;" } }, "\u0000Set-Cookie": { "description": "The user tracking ID.", "schema": { "type": "string", "example": "blaize_tracking_id=b117093c-e1f7-4ee0-8dda-6b5205f7fbee; Expires=Fri, 16 Nov 2024 12:35:56 GMT; Path=/;" } }, "\u0000\u0000Set-Cookie": { "description": "The anonymous user session before authentication.", "schema": { "type": "string", "example": "blaize_prev_anon_session=b117093c-e1f7-4ee0-8dda-6b5205f7fbee; Expires=Fri, 16 Nov 2024 12:35:56 GMT; Path=/;" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-login-response" } } } }, "400": { "description": "Bad Request. The server could not understand the request due to invalid syntax or missing required parameters.", "headers": {} }, "401": { "description": "Unauthorized. The user is unable to authenticate due to invalid login credentials, resulting in a lack of authentication.", "headers": {} } }, "summary": "Log in to the user account", "operationId": "loginUserAccount", "description": "This endpoint is utilized for user authentication, granting access to secured endpoints that mandate authentication. Following successful authentication, a `blaize_session` is generated for the user, enabling them to access the secure endpoints.", "tags": [ "Authentication" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie is employed to ascertain whether a user is already authenticated or has an active session.", "required": false, "example": "blaize_session=... (optional)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-registration-request" } } } } } }, "/blaize/logout": { "post": { "responses": { "200": { "description": "OK", "headers": { "Set-Cookie": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin-user-logout-response" }, "examples": { "response": { "value": { "message": "Session deleted" } } } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Log out of the user account", "operationId": "logoutUserAccount", "description": "Logs out of the user account.", "tags": [ "Authentication" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin-user-logout-request" } } } } } }, "/zephr/public/sso/v1/status": { "get": { "responses": { "200": { "description": "SSO status was retrieved successfully.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveStatusResponse" }, "examples": { "response": { "value": { "status": "authenticated", "meta": {} } } } } } } }, "summary": "Retrieve the SSO status", "operationId": "retrieveSSOStatus", "description": "Retrieves the SSO status and metadata of the current user.", "tags": [ "Authentication" ] } }, "/zephr/public/sso/v1/status/meta": { "put": { "responses": { "200": { "description": "OK", "headers": {} }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Update the metadata", "operationId": "updateMetaData", "description": "Updates the SSO metadata associated with the user.", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer-meta" }, "example": {} } } } } }, "/blaize/token-exchange": { "post": { "responses": { "201": { "description": "Created", "headers": {} }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Start the passwordless authentication flow", "operationId": "startPasswordlessAuthentication", "description": "Starts the passwordless authentication flow by sending an email to the user with a sign-in link. When the user clicks the link, they are directed to GET /blaize/token-exchange?token=..., which authenticates them automatically.\n**IMPORTANT**: Passwordless authentication requires the user's email to be verified. This means the user must first receive a separate verification email and click the link to confirm their email address. Verification can be triggered by sending a POST request to the appropriate endpoint.\n", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordless-authentication-request" } } } } }, "get": { "responses": { "302": { "description": "Found", "headers": { "Location": { "schema": { "type": "string" } }, "Set-Cookie": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Login link expired" }, "404": { "description": "Passwordless login token not found" }, "409": { "description": "Passwordless login token expired" }, "410": { "description": "Unused passwordless login token expired" } }, "summary": "Completes the passwordless authentication flow", "operationId": "completePasswordlessAuthentication", "description": "Completes the passwordless authentication flow. This endpoint is triggered when the the user clicks the link in the email sent after a POST /blaize/token-exchange request.\n**IMPORTANT**: For passwordless authentication, first is required to send a POST to request an email to be sent to the User’s email with a link for the user to click on to verify his email.\n", "tags": [ "Authentication" ] } }, "/zephr/users/reset/{state}": { "post": { "responses": { "200": { "description": "OK", "headers": {} }, "400": { "description": "Bad Request", "headers": {} }, "404": { "description": "Token Not Found", "headers": {} }, "409": { "description": "The state was already used", "headers": {} } }, "summary": "Complete a 2FA based password reset", "operationId": "complete2FAPasswordReset", "description": "Completes the password reset.\n**IMPORTANT**: To reset a user's password, first send a POST request to trigger an email with a reset token. This token must be included in the state parameter when calling this API. The validator parameter is optional, if omitted, the OTP can be verified first, and the new password can be submitted separately with the correct OTP.\n", "tags": [ "Authentication" ], "parameters": [ { "name": "state", "in": "path", "description": "A 6-digit code, which is used to verify the password request.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/user-2fa-password-reset-complete" } } }, "/blaize/blaize/password-reset.html": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "" } } } } } }, "summary": "Return the password reset form", "operationId": "resetPasswordForm", "description": "Returns the password reset form", "tags": [ "Authentication" ] } }, "/blaize/anonymous-session": { "post": { "responses": { "201": { "description": "Created", "headers": { "Set-Cookie": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cdn-anonymous-session-response" }, "examples": { "response": { "value": { "message": "Anonymous session created successfully", "tracking_id": "33d576c7-d036-40e7-8141-8a91998a5c79" } } } } } } }, "summary": "Create an anonymous session", "operationId": "createAnonymousSession", "description": "Creates an anonymous session.", "tags": [ "Authentication" ], "parameters": [ { "name": "token", "in": "query", "description": "Required if browser fingerprinting is enabled on the CDN. This token is retrieved from the `GET` `/blaize/browser-fingerprint` flow.", "required": false, "schema": { "type": "string" } }, { "name": "fingerprint", "in": "query", "description": "Required if browser fingerprinting is enabled on the CDN, the fingerprint retrieved from the `GET` `/blaize/browser-fingerprint` flow.", "required": false, "schema": { "type": "string" } } ] } }, "/blaize/users/update-email": { "post": { "responses": { "200": { "description": "OK", "headers": {} }, "400": { "description": "Bad Request", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Start updating the current email address", "operationId": "startUpdatingYourCurrentEmailAddress", "description": "Starts updating user's current email address.\n", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start-update-your-current-email-address-request" } } } } } }, "/zephr/users/update-email": { "post": { "responses": { "200": { "description": "OK. The confirmation email was sent successfully.", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Email with OTP sent to verify new email address" } } } } } }, "400": { "description": "Bad Request. Returned if the provided email is invalid.", "headers": {} }, "401": { "description": "Unauthorized. Returned if the provided validator is invalid.", "headers": {} }, "404": { "description": "Not Found. Returned if the user is not found.", "headers": {} } }, "summary": "Start updating the current email address", "operationId": "startUpdatingYourCurrentZephrEmailAddress", "description": "Updates the user's email address. The user will receive an email with a one-time password (OTP) to verify the new email address. In order to finish the process, the user must provide the OTP to the _/zephr/users/update-email/{otp}_ endpoint. The difference between this endpoint and the _/blaize/users/update-email_ endpoint is that this endpoint requires the extra layer of authentication through the required validator.", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start-update-your-current-zephr-email-address-request" } } } } } }, "/zephr/users/update-email/{otp}": { "post": { "responses": { "200": { "description": "OK. The email address was updated successfully.", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User Email updated" } } } } } }, "400": { "description": "Bad Request. Returned if the provided OTP is invalid.", "headers": {} }, "401": { "description": "Unauthorized. Returned if the provided validator is invalid.", "headers": {} } }, "summary": "Complete updating the current email address", "operationId": "completeUpdatingYourCurrentZephrEmailAddress", "description": "Completes updating the user's email address. The user must provide the OTP received in the email to verify the new email address. The difference between this endpoint and the _/blaize/users/update-email/_ endpoint is that this endpoint requires the extra layer of authentication through the required validator.", "tags": [ "Authentication" ], "parameters": [ { "name": "otp", "in": "path", "description": "The one-time password (OTP) received in the email.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/complete-update-your-current-zephr-email-address-request" } } } } } }, "/blaize/update-email.html": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "" } } } } } }, "summary": "Return the update email request form", "operationId": "updateEmailRequestForm", "description": "Returns the update email request Form.", "tags": [ "Authentication" ] } }, "/blaize/users/change-password": { "post": { "responses": { "200": { "description": "OK", "headers": {} }, "400": { "description": "Bad Request", "headers": {} }, "403": { "description": "Forbidden", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Change the user password", "operationId": "changePassword", "description": "Changes the user password.", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "current_validators": { "type": "object", "properties": { "password": { "type": "string" } } }, "new_validators": { "type": "object", "properties": { "password": { "type": "string" } } } }, "required": [ "current_validators", "new_validators" ], "example": { "current_validators": { "password": "mysecurepassword123" }, "new_validators": { "password": "mysecurepassword123" } } } } } } } }, "/blaize/payment/braintree/token": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJ2ZXmsaW5nQW...(lots more random-looking characters)...dyZWmVubW8iOiJvZmYifQ==" } } }, "examples": { "response": { "value": { "token": "eyJ2ZXmsaW5nQW...(lots more random-looking characters)...dyZWmVubW8iOiJvZmYifQ==" } } } } } }, "401": { "description": "Unauthorized", "headers": {} } }, "summary": "Retrieve the Braintree token", "operationId": "getBraintreeToken", "description": "Issues a Braintree client token for the current blaize session.\nThis holds the user's userId if the user has an authenticated session.\nThis token can be used to request a payment once.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "allowUnauthenticated", "in": "query", "description": "If tokens can be generated for unauthenticated user sessions - defaults to false.", "required": false, "schema": { "type": "boolean" } }, { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] } }, "/blaize/payment/braintree/subscriptionChargedCallback": { "post": { "responses": { "200": { "description": "OK. A product purchase is created successfully.", "headers": {} }, "400": { "description": "Bad Request. The product purchase creation failed because the subscription was overdue or the callback endpoint received an invalid or empty payload.", "headers": {} } }, "summary": "Create a subscription charged callback", "operationId": "createSubscriptionChargedCallback", "description": "This endpoint generates a callback for subscription charges when a product purchase is created, regardless of success or failure. It requires a mandatory string payload containing the `bt_signature` and `bt_payload` parameters. To use subscriptions, configure the Braintree callback to direct to this endpoint.", "tags": [ "Braintree Payments" ], "requestBody": { "content": { "application/json": { "schema": { "type": "string", "example": "bt_signature=&bt_payload=" } } } } } }, "/blaize/payment/braintree/subscriptions": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "required": [ "managed-by", "external-id", "next-billing-time", "blaize-product", "transaction-history", "subscription-state", "plan_id", "plan_name", "currency_code", "pre_discount_price", "billing_frequency_unit", "billing_frequency", "discounts_applied", "multiphase_plan" ], "properties": { "managed-by": { "type": "string", "example": "Braintree", "description": "The name of payment provider capitalised." }, "ends": { "type": "string", "format": "date-time", "example": "2021-05-17T04:31:33Z", "description": "ISO-8601 formatted time at which the subscription was canceled. This field will be omitted if the subscription is not canceled." }, "external-id": { "type": "string", "example": "abc123", "description": "The ID for this subscription in Braintree." }, "next-billing-time": { "type": "string", "format": "date-time", "example": "2021-05-17T04:31:33Z", "description": "ISO-8601 formatted time at which the subscription will next be billed." }, "blaize-product": { "$ref": "#/components/schemas/braintree-subscription-product" }, "transaction-history": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "example": "2024-02-15T11:30:58Z", "description": "ISO-8601 formatted time at which the transaction was made." }, "currency": { "type": "string", "example": "EUR" }, "cents": { "type": "number", "example": 900 }, "cycle": { "type": "string", "example": "month" }, "cycleCount": { "type": "number", "example": 1 }, "currencyCode": { "type": "string", "example": "EUR", "description": "ISO 4217 currency code for this currency." }, "human-readable-amount": { "type": "string", "example": "€9.0" } } } }, "subscription-state": { "type": "string", "description": "The subscription state, as acquired from Braintree.", "enum": [ "Active", "Canceled", "Expired", "Past Due", "Pending", "Unrecognized" ] }, "paid_through_date": { "type": "string", "format": "date-time", "example": "2021-05-17T04:31:33Z", "description": "ISO-8601 formatted time up to which the subscription has been paid for. This will be `null` if the subscription has not yet been paid for." }, "plan_id": { "type": "string", "example": "plan-123", "description": "The Braintree plan ID" }, "plan_name": { "type": "string", "example": "monthly-plan", "description": "The Braintree plan name" }, "billing_frequency_unit": { "type": "string", "description": "The time unit of the billing frequency. Braintree only supports MONTH.", "enum": [ "MONTH" ] }, "billing_frequency": { "type": "number", "example": 1, "description": "The frequency at which the subscription is billed, in the units specified by billing_frequency_unit." }, "currency_code": { "type": "string", "example": "GBP", "description": "The currency of the subscription price." }, "pre_discount_price": { "type": "number", "example": 50, "description": "The subscription price before any discounts are applied." }, "multiphase_plan": { "type": "boolean", "example": false, "description": "Always `false`, as Braintree does not support multi-phased plans." }, "discounts_applied": { "type": "boolean", "example": true, "description": "If the subscription has any applied discounts." } } }, "examples": { "response": { "value": { "managed-by": "Braintree", "external-id": "abc123", "next-billing-time": "2021-05-17T04:31:33Z", "blaize-product": { "id": "one-month-one-off", "label": "One month access", "description": "One month access", "entitlement": { "id": "191f6d00-b8d4-46f1-a22d-2bf53f4f8fa3", "type": "bundle" }, "mapping": { "recurring": { "plans": { "id": "cxtr", "label": null, "archived": false, "billingCycles": 1, "paymentProvider": "braintree" }, "multiPhasedPlans": [] }, "oneOff": { "plans": { "id": "3mkb", "label": null, "archived": false, "billingCycles": null, "paymentProvider": "braintree", "accessDuration": { "duration": 5, "unit": "MONTHS" } } }, "braintree_one_off": { "price_points": [] }, "rate_plans": [], "jwt": { "claim_value": "" } }, "sharingLimit": 0 }, "transaction-history": { "time": "2021-05-17T04:31:33Z", "currency": "GBP", "cents": 234, "cycle": "month", "cycleCount": 1, "currencyCode": "GBP", "human-readable-amount": "£2.34" }, "subscription-state": "Active", "paid_through_date": "2021-05-17T04:31:33Z", "plan_id": "plan-123", "plan_name": "monthly-plan", "billing_frequency_unit": "MONTH", "billing_frequency": 1, "currency_code": "GBP", "pre_discount_price": 2, "multiphase_plan": false, "discounts_applied": true } } } } } }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "List the Braintree subscriptions of a user", "operationId": "listUserBraintreeSubscriptions", "description": "Lists all Braintree subscriptions for the logged-in user.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] } }, "/blaize/payment/braintree/subscriptions/{subscriptionId}": { "patch": { "responses": { "204": { "description": "No Content", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Update the Braintree subscription", "operationId": "updateBraintreeSubscription", "description": "Updates a Braintree subscription by ID.\nThis operation currently only supports updating the payment method for a subscription, sending the payment method token or nonce.\n", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Subscription ID", "required": true, "schema": { "type": "string" } }, { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method_token": { "type": "string", "description": "Payment method token referencing a payment method in Braintree." }, "payment_method_nonce": { "type": "string", "description": "Payment method nonce referencing a payment method in Braintree." } }, "example": { "payment_method_token": "alpha123token", "payment_method_nonce": "alpha123token" } } } } } }, "delete": { "responses": { "200": { "description": "OK", "headers": {} }, "404": { "description": "Not Found", "headers": {} }, "409": { "description": "Conflict", "headers": {} } }, "summary": "Cancel the Braintree subscription", "operationId": "cancelBraintreeSubscription", "description": "Cancels a Braintree subscription by ID.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Subscription ID", "required": true, "schema": { "type": "string" } } ] } }, "/blaize/payment/braintree/buy": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "example": "aa583cb8-51d1-4bd9-9ec7-3a43796ef8e5", "description": "New grant of product bundle to user." } } }, "examples": { "response": { "value": { "grant_id": "aa583cb8-51d1-4bd9-9ec7-3a43796ef8e5" } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Create a Braintree buy (one-off)", "operationId": "createBraintreeBuyOneOff", "description": "Uses the payment info captured by the braintree drop-in UI and encoded in the payment nonce to create a braintree customer and issue a one-off payment.\nWhen braintree responds successfully, the logged-in user will be granted all entitlements in the product's associated bundle.\n", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product Id/slug" }, "price_point_id": { "type": "string", "description": "Price Point Id/slug" }, "payment_nonce": { "type": "string", "description": "Payment method nonce from Braintree drop-in UI." } }, "required": [ "product_id", "price_point_id", "payment_nonce" ], "example": { "product_id": "lifetime-membership", "price_point_id": "gold-package", "payment_nonce": "eyJ2ZXmsaW5nQW...(lots more random-looking characters)...dyZWmVubW8iOiJvZmYifQ==" } } } } } } }, "/zephr/payment/braintree/payment-methods": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_methods" }, "examples": { "response": { "value": [ { "token": "8m2kc5g", "default": false, "card_type": "Visa", "card_holder_name": "John Rambo", "card_number_masked": "654321******0987", "expiration_date": "07/22", "expired": false, "expiring_soon": false, "in_use": false, "last_4": "1111", "nonce": "086128f3-04c2-069e-78d2-3f4de98508e5", "type": "CreditCard", "zipcode": "123456" } ] } } } } }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "List Braintree payment methods", "operationId": "listBraintreeUserPaymentMethods", "description": "Lists the Braintree payment method details associated with the logged-in user.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] }, "post": { "responses": { "200": { "description": "OK. A new Braintree payment method has been created for the authenticated user.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_method" }, "examples": { "response": { "value": { "token": "8m2kc5g", "default": false, "card_type": "Visa", "card_holder_name": "John Rambo", "card_number_masked": "654321******0987", "expiration_date": "07/22", "expired": false, "expiring_soon": false, "in_use": false, "last_4": "1111", "nonce": "086128f3-04c2-069e-78d2-3f4de98508e5", "type": "CreditCard", "zipcode": "123456" } } } } } }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Create a new Braintree payment method.", "operationId": "createBraintreeUserPaymentMethod", "description": "Creates the Braintree payment method with the associated vaulted nonce, for the authenticated user.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": true, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method_nonce": { "type": "string", "example": "aa583cb8...and other characters...3a43796ef8e5", "description": "The vaulted nonce associated with the new payment method." } } } } } } } }, "/zephr/payment/braintree/payment-methods/{paymentMethodToken}": { "patch": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_method" }, "examples": { "response": { "value": { "token": "8m2kc5g", "default": false, "card_type": "Visa", "card_holder_name": "John Rambo", "card_number_masked": "654321******0987", "expiration_date": "07/22", "expired": false, "expiring_soon": false, "in_use": false, "last_4": "1111", "nonce": "086128f3-04c2-069e-78d2-3f4de98508e5", "type": "CreditCard", "zipcode": "123456" } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Update a Braintree payment method", "operationId": "updateUserBraintreePaymentMethod", "description": "Updates the Braintree payment method details associated with the logged-in user.\nThe details to update must first be captured from Braintree in a nonce and vaulted.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "paymentMethodToken", "in": "path", "description": "The unique ID of the payment method.", "required": true, "schema": { "type": "string" } }, { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method_nonce": { "type": "string", "example": "aa583cb8...and other characters...3a43796ef8e5", "description": "The vaulted nonce associated with the update payment method." } } } } } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Delete the Braintree payment method", "operationId": "deleteUserBraintreePaymentMethod", "description": "Deletes the Braintree payment method associated with the provided token.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "paymentMethodToken", "in": "path", "description": "The unique ID of the payment method.", "required": true, "schema": { "type": "string" } }, { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] } }, "/zephr/payment/braintree/default-payment-method": { "put": { "responses": { "204": { "description": "No Content", "headers": {} }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Set the default Braintree payment method", "operationId": "setUserDefaultBraintreePaymentMethod", "description": "Sets the Braintree default payment method for the logged-in user.\nThis must be a valid payment method already associated with the user.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method_token": { "type": "string", "example": "payment-method-123", "description": "The unique ID of the payment method to be set as default for the user." } } } } } } } }, "/zephr/payment/braintree/plans": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan-id": { "$ref": "#/components/schemas/payment_plan" } } }, "examples": { "response": { "value": { "plan-id": { "id": "annual-plan", "name": "Sports+ Membership Annual", "currency_code": "USD", "base_price": 10.2, "billing_interval_unit": "MONTH", "billing_interval": 3, "billing_cycles": 12, "trial_duration_unit": "DAY", "trial_duration": 30, "discounts": [ { "id": "annual-discount", "name": "Sports+ Membership Discount", "description": "This is a discount description", "amount": "9.99", "billing_cycles": "6", "current_billing_cycle": "4" } ], "zephr_product_id": "product-123" } } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "List all Braintree plans", "operationId": "listBraintreePlans", "description": "Lists the plans associated with the identified product.\nThe product ID is required.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID", "required": true, "schema": { "type": "string" } }, { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] } }, "/blaize/payment/braintree/promo-code": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "discount", "paymentOptions" ], "properties": { "code": { "type": "string", "example": "promo-123", "description": "The promo code identifier." }, "discount": { "type": "number", "example": 20, "description": "The discount amount." }, "paymentOptions": { "type": "array", "items": { "$ref": "#/components/schemas/promo-code-payment-options" }, "description": "The list of payment options." } } }, "examples": { "response": { "value": { "code": "promo-123", "discount": 20, "paymentOptions": [ { "slug": "plan-123", "currency": "$", "pricePointId": "cost-123", "originalPrice": 3.45, "discountPrice": 2 } ] } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "403": { "description": "Forbidden", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Get a Braintree Promo Code", "operationId": "getBraintreePromoCode", "description": "Gets a Braintree promo code.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "code", "in": "query", "description": "Promo code to lookup by ID.", "required": true, "schema": { "type": "string" } }, { "name": "paymentForm", "in": "query", "description": "Payment form to lookup by slug.", "required": true, "schema": { "type": "string" } } ] } }, "/blaize/payment/braintree/addons&promoCode={promoCode}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add-ons" }, "examples": { "response": { "value": [ { "id": "add-123", "label": "Easy Add-on", "value": 12, "type": "PERCENT", "paymentOptions": [ { "slug": "plan-123", "currency": "$", "addonPrice": 12.34 } ] } ] } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "403": { "description": "Forbidden", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "List Braintree add-ons", "operationId": "listBraintreeAddons", "description": "Lists the Braintree add-ons.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "paymentForm", "in": "query", "description": "Payment form to lookup by slug.", "required": true, "schema": { "type": "string" } }, { "name": "promoCode", "in": "path", "description": "Promo code to lookup by ID.", "required": true, "schema": { "type": "string" } } ] } }, "/blaize/payment/braintree/subscribe": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "example": "33d576c7-d036-40e7-8141-8a91998a5c79", "description": "New grant of product bundle to user." } } }, "examples": { "response": { "value": { "grant_id": "33d576c7-d036-40e7-8141-8a91998a5c79" } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} } }, "summary": "Start the Braintree subscription (Deprecated)", "operationId": "startBraintreeSubscriptionDeprecated", "description": "** (Deprecated - use the \"/zephr/subscribe\" operation intead)**\nUses the payment info captured by the braintree drop-in UI and encoded in the payment nonce to create a braintree customer in with a recurring payment.\nWhen braintree responds successfully, the logged-in user will be temporarily granted all entitlements in the product's associated bundle.", "tags": [ "Braintree Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID/slug" }, "plan_id": { "type": "string" }, "discount_code": { "type": "string" }, "payment_nonce": { "type": "string", "description": "Payment method nonce from Braintree drop-in UI." }, "skip_trial_period": { "type": "boolean", "description": "Whether or not to skip any trial period that may be associated with this subscription. This should be `null` or not set to use the configured trial period." }, "start_date": { "type": "string", "description": "ISO 8601 date format which determines when the subscription will start. When the attribute is passed, the value must be in the future. Otherwise, the subscription is expected to start immediately." } }, "required": [ "product_id", "payment_nonce" ], "example": { "product_id": "premium-access-monthly-recurring", "payment_nonce": "eyJ2ZXmsaW5nQW...(lots more random-looking characters)...dyZWmVubW8iOiJvZmYifQ==", "skip_trial_period": true, "start_date": "2021-01-01T00:00:00Z" } } } } } } }, "/zephr/feature-decisions": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/browser-features-response" }, "examples": { "response": { "value": { "featureResults": { "featureX": "blaize.transform.resource('...')" }, "resources": { "uiComponents": { "M-eRFAot": "

Example

" } }, "accessDetails": { "authenticated": false, "accessDecisions": { "W28U8Z": false }, "entitlements": { "W28U8Z": { "usedInDecision": false, "decrementedInDecision": false } }, "credits": { "W28U8Z": { "usedInDecision": false, "decrementedInDecision": false, "totalCredits": 0, "remainingCredits": 0 } }, "meters": { "W28U8Z": { "usedInDecision": false, "decrementedInDecision": false, "totalCredits": 0, "remainingCredits": 0 } }, "trialTrackingDetails": [ { "entitlementId": "W28U8Z", "entitlementType": "entitlement", "trackCreditsUsed": false, "trackCreditsRemaining": false, "creditsUsedKey": "creditsUsed", "creditsRemainingKey": "creditsRemaining" } ], "trials": { "pLvjuu": { "totalCredits": 1, "remainingCredits": 0, "tracker": "", "reportInDataLayer": true, "dataLayerCreditsUsedKey": "trial-pLvjuu-creditsUsed", "dataLayerCreditsRemainingKey": "trial-pLvjuu-creditsRemaining", "decrementedInDecision": true, "usedInDecision": true } }, "timeTrials": { "xCoYJr": { "reportInDataLayer": true, "trialDurationUnits": "HOURS", "trialDuration": 1, "entryTime": "2024-02-08T08:48:33.056008906Z[UTC]", "trackerHits": 1, "timeRemainingInTrial": 0, "dataLayerTrialDurationKey": "trial-xCoYJr-trialDuration", "dataLayerTrialDurationUnitsKey": "trial-xCoYJr-trialDurationUnits", "dataLayerTrackerEntryTimeKey": "trial-xCoYJr-trackerEntryTime", "dataLayerTrackerHitsKey": "trial-xCoYJr-trackerHits", "dataLayerTrialTimeRemainingKey": "trial-xCoYJr-trialTimeRemaining", "activeInDecision": true } }, "testGroups": { "6663d5ea-d1db-4104-893e-65a21a92e32e": "B" }, "activeProducts": [ "example product" ] } } } } } } } }, "summary": "Execute Browser feature decisions", "operationId": "executeBrowserFeaturesDecisions", "description": "Zephr HTML Features can be run in the browser by calling this API directly or using the Zephr Browser SDK. For compatibility with CDN, any web headers (Referrer, User-Agent) will be accepted and passed onto the rule engine.", "tags": [ "Browser Feature Transformations" ], "parameters": [ { "name": "Cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "blaize_session=...", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "featureIds": { "type": "array", "description": "Array of HTML Feature IDs", "items": {} }, "session": { "type": "string", "description": "Zephr Session ID" }, "referer": { "type": "string", "description": "Browser referer" }, "path": { "type": "string", "description": "Request path, defaults to \"/\". If available, include the content ID as a query parameter. For example, `/story.html?content_id=abc-123`." }, "content_metadata": { "type": "object", "properties": { "content_id": { "type": "string", "description": "Content ID, used to perform requests to a 3rd party API for additional content information used in making a decision." } } }, "giftToken": { "type": "string", "description": "Token to provide access to content for one session." }, "jwt": { "type": "string", "description": "A Json Web Token, may include identity or product holding claims." }, "customData": { "type": "object", "description": "Custom data to be used in Feature HTML browser rule. Accepts a JSON object." } }, "required": [ "featureIds" ], "example": { "featureIds": [ "featureX" ], "session": "xxx-xxx-xxx", "referer": "https://www.zephr.com/", "path": "/x.html", "content_metadata": { "content_id": "xxx-xxx-xxx" }, "giftToken": "xxx-xxx-xxx", "jwt": "xxx-xxx-xxx", "customData": { "key": "value" } } } } } } } }, "/zephr/feature-transformations": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/browser-features-transformations-response" }, "examples": { "response": { "value": { "featureResults": { "featureX": { "ruleTransformations": { "type": "string", "id": "rule-id", "contentLength": 100, "outcomeId": "outcome-id", "outcomeLabel": "Outcome Label", "ruleId": "rule-id", "ruleLabel": "Rule Label", "style": "block", "url": "https://example.com", "value": "Transformation Value" }, "zoneRuleTransformations": { "zone": "HEADER", "closeable": true, "css": { ".example { color": "red; }" }, "displayAfter": "5s", "scrollable": false, "ruleTransformations": [ { "type": "string", "id": "rule-id", "contentLength": 100, "outcomeId": "outcome-id", "outcomeLabel": "Outcome Label", "ruleId": "rule-id", "ruleLabel": "Rule Label", "style": "block", "url": "https://example.com", "value": "Transformation Value" } ] } } }, "accessDetails": { "authenticated": false, "accessDecisions": { "W28U8Z": false }, "entitlements": { "W28U8Z": { "usedInDecision": false, "decrementedInDecision": false } }, "credits": { "W28U8Z": { "usedInDecision": false, "decrementedInDecision": false, "totalCredits": 0, "remainingCredits": 0 } }, "meters": { "W28U8Z": { "usedInDecision": false, "decrementedInDecision": false, "totalCredits": 0, "remainingCredits": 0 } }, "trialTrackingDetails": [ { "entitlementId": "W28U8Z", "entitlementType": "entitlement", "trackCreditsUsed": false, "trackCreditsRemaining": false, "creditsUsedKey": "creditsUsed", "creditsRemainingKey": "creditsRemaining" } ], "trials": { "pLvjuu": { "totalCredits": 1, "remainingCredits": 0, "tracker": "", "reportInDataLayer": true, "dataLayerCreditsUsedKey": "trial-pLvjuu-creditsUsed", "dataLayerCreditsRemainingKey": "trial-pLvjuu-creditsRemaining", "decrementedInDecision": true, "usedInDecision": true } }, "timeTrials": { "xCoYJr": { "reportInDataLayer": true, "trialDurationUnits": "HOURS", "trialDuration": 1, "entryTime": "2024-02-08T08:48:33.056008906Z[UTC]", "trackerHits": 1, "timeRemainingInTrial": 0, "dataLayerTrialDurationKey": "trial-xCoYJr-trialDuration", "dataLayerTrialDurationUnitsKey": "trial-xCoYJr-trialDurationUnits", "dataLayerTrackerEntryTimeKey": "trial-xCoYJr-trackerEntryTime", "dataLayerTrackerHitsKey": "trial-xCoYJr-trackerHits", "dataLayerTrialTimeRemainingKey": "trial-xCoYJr-trialTimeRemaining", "activeInDecision": true } }, "testGroups": { "6663d5ea-d1db-4104-893e-65a21a92e32e": "B" }, "activeProducts": [ "example product" ] } } } } } } } }, "summary": "Execute Browser feature transformations", "operationId": "executeBrowserFeatureTransformations", "description": "Zephr HTML Features can be run in the browser by calling this API directly or using the Zephr Browser SDK. For compatibility with CDN, any web headers (Referrer, User-Agent) will be accepted and passed onto the rule engine.", "tags": [ "Browser Feature Transformations" ], "parameters": [ { "name": "Cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "blaize_session=...", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "featureIds": { "type": "array", "description": "An array of HTML Feature IDs.", "items": {} }, "session": { "type": "string", "description": "The Zephr Session ID." }, "referer": { "type": "string", "description": "Browser referer" }, "path": { "type": "string", "description": "Request path, defaults to \"/\". If available, include the content ID as a query parameter. For example, `/story.html?content_id=abc-123`." }, "content_metadata": { "type": "object", "properties": { "content_id": { "type": "string", "description": "Content ID, used to perform requests to a 3rd party API for additional content information used in making a decision." } } }, "giftToken": { "type": "string", "description": "Token to provide access to content for one session." }, "jwt": { "type": "string", "description": "A JSON Web Token, may include identity or product holding claims." }, "customData": { "type": "object", "description": "Custom data to be used in Feature HTML browser rule. Accepts a JSON object" } }, "required": [ "featureIds" ], "example": { "featureIds": [ "featureX" ], "session": "xxx-xxx-xxx", "referer": "https://www.zephr.com/", "path": "/x.html", "content_metadata": { "content_id": "xxx-xxx-xxx" }, "giftToken": "xxx-xxx-xxx", "jwt": "xxx-xxx-xxx", "customData": { "key": "value" } } } } } } } }, "/blaize/decision-engine": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access-decision-response" }, "examples": { "response": { "value": { "status": "301", "body": "Redirecting to login page...", "headers": { "Location": "/login.html" } } } } } } }, "409": { "description": "Conflict", "headers": {} } }, "summary": "Execute the Decision Engine", "operationId": "executeDecisionEngine", "description": "\nThe Blaize Decision Engine can be invoked via the Public API to calculate an HTTP Response based upon Request-Level Rules created in the Admin Console. This functionality is built into the Blaize Dynamic CDN but the API variant is useful for CMS or edge side integrations.\n", "tags": [ "Decision Engine" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "http_method": { "type": "string" }, "session": { "type": "string" }, "foreign_keys": { "type": "object", "properties": {}, "description": "Foreign system and ID used to identify the user." }, "request_headers": { "type": "object", "properties": { "User-Agent": { "type": "string" } } }, "content_metadata": { "type": "object", "properties": { "publishedDate": { "type": "string" } } }, "jwt": { "type": "string" }, "btr": { "type": "string", "description": "MD5-hex-encoding of: path + \"|\" + trusted referrer secret" } }, "required": [ "path" ], "example": { "path": "/x.html", "http_method": "POST", "session": "xxx-xxx-xxx", "foreign_keys": {}, "request_headers": { "User-Agent": "" }, "content_metadata": { "publishedDate": "" }, "jwt": "xxx-xxx-xxx", "btr": "17e74b9e49e66282e55d4b7ec73de951" } } } } } }, "get": { "responses": { "200": { "description": "Response status and body are determined by the executed rule. If there is an error executing the rule, a 200 will be returned.", "headers": {} } }, "summary": "Retrieve the Decision Engine", "operationId": "getDecisionEngine", "description": "For compatibility with CDN, any web headers (Referrer, User-Agent) will be accepted and passed onto the rule engine.", "tags": [ "Decision Engine" ], "parameters": [ { "name": "path", "in": "query", "description": "Uniquely identifies the content Zephr is making a decision about. Request rules can be configured to only execute when the request path matches a provided regular expression.", "required": true, "schema": { "type": "string" } }, { "name": "session", "in": "query", "description": "Zephr Session ID - same as the blaize_session cookie used by the CDN and authentication endpoints.", "required": true, "schema": { "type": "string" } }, { "name": "foreign_id.xxx", "in": "query", "description": "Foreign ID used to identify the user. The foreign system is parsed as the remainder of the parameter key name following 'foreign_id.'", "required": true, "schema": { "type": "string" } }, { "name": "content_id", "in": "query", "description": "Passed as `metadata.content_id` to the Content API template, used to\nperform requests to a 3rd party API for additional content\ninformation used in making a decision.\n", "required": true, "schema": { "type": "string" } }, { "name": "jwt", "in": "query", "description": "A JSON Web Token, may include identity or product holding claims.", "required": true, "schema": { "type": "string" } }, { "name": "btr", "in": "query", "description": "A trusted referrer token. If Zephr generates a matching token using path, passed-in Referer header and a configured secret, all entitlements used in this decision will be temporarily granted for this request.", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/public/decisions/v2/dynamic-offers": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dynamic-offer-decision-response" } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Process dynamic offer decisions", "operationId": "processDynamicOfferDecisions", "description": "The Dynamic Offer Decision Engine can be invoked via the Public API to calculate a decision output response based upon each property rule under the Dynamic Offer created in the Zephr Console.\n", "tags": [ "Dynamic Offer Decision Engine" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dynamic_offer": { "type": "object", "properties": { "slug": { "type": "string", "description": "Dynamic Offer slug" }, "inputs": { "type": "object", "properties": {}, "description": "Custom inputs configured in Dynamic Offer. This can be any single layer map of key-value pairs." } }, "required": [ "slug" ], "description": "The dynamic offer to evaluate, must specify the slug of the dynamic offer, and any custom input to be used in the rules." }, "session": { "type": "string", "description": "Zephr Session ID, required for trials" }, "foreign_keys": { "type": "object", "properties": {}, "description": "Foreign system and ID used to identify the user." }, "ip": { "type": "string", "description": "Client IP address, defaults to request IP." }, "user_agent": { "type": "string", "description": "Client user agent" }, "jwt": { "type": "string", "description": "A JSON Web Token, may include identity or product holding claims." }, "path": { "type": "string", "description": "Request path, required for trials if used." }, "content_id": { "type": "string", "description": "Content ID, used to perform requests to a 3rd party API for additional content information used in making a decision." } }, "required": [ "dynamic_offer" ], "example": { "dynamic_offer": { "slug": "offerX", "inputs": {} }, "session": "xxx-xxx-xxx", "foreign_keys": {}, "ip": "x.x.x.x", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11)...", "jwt": "xxx-xxx-xxx", "path": "/x.html", "content_id": "xxx-xxx-xxx" } } } } } } }, "/zephr/public/decisions/v2/dynamic-offers/{offerId}/validations/{validationId}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dynamic-offer-decision-response" } } } }, "400": { "description": "Bad Request", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Validate dynamic offer decisions", "operationId": "validateDynamicOfferDecisions", "description": "The Dynamic Offer Decision Engine can be tested via this endpoint to calculate a decision output response based on the criteria of the provided validation ID.\nValidation criteria is configured on the Zephr Console and determines the version of the dynamic offer being used.\n", "tags": [ "Dynamic Offer Decision Engine" ], "parameters": [ { "name": "offerId", "in": "path", "description": "The dynamic offer ID.", "required": true, "schema": { "type": "string" } }, { "name": "validationId", "in": "path", "description": "The dynamic offer validation ID.", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/public/decisions/v1/promo-codes": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dynamic-offer-decision-response" } } } }, "400": { "description": "Bad Request", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Process promo code decisions", "operationId": "processPromoCodeDecisions", "description": "The Promo Code decision would execute the discount rule defined behind the given promo code, which is configured from the Zephr console.\nThe decision request would require a list of relevant products with its pricing data, typically it would have come from a Dynamic Offer decision response.\nThe Promo Code decision would generate decision response like a regular Dynamic Offer, but with the discount output according to the Promo Code's discount rule.\n\nAlternatively, if configured and the feature is enabled, this api can execute a dynamic offer rule that is linked to this promo code. Selected products are not required for executing promo codes using this method.\nParameters supplied to the dynamic offers decisions api can also be supplied to this api for this promo code flow (session, foreign_keys, etc).\n", "tags": [ "Dynamic Offer Promo Code Decision" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "promo_code": { "type": "string", "description": "The Promo Code, generated from the Zephr console." }, "promo_code_definition": { "type": "string", "description": "The Definition ID of Promo Code, generated from the Zephr console. This is useful for previewing a draft promo code rule/offer as there won't be any downloadble/usable promo code generated." }, "selected_products": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/promo-code-decision-request-selected-product" } }, "session": { "type": "string", "nullable": true, "description": "Zephr Session ID, required for trials. Only relevant for executing promo code with a linked dynamic offer." }, "foreign_keys": { "type": "object", "nullable": true, "properties": {}, "description": "Foreign system and ID used to identify the user. Only relevant for executing promo code with a linked dynamic offer." }, "ip": { "type": "string", "nullable": true, "description": "Client IP address, defaults to request IP. Only relevant for executing promo code with a linked dynamic offer." }, "user_agent": { "type": "string", "nullable": true, "description": "Client user agent. Only relevant for executing promo code with a linked dynamic offer." }, "jwt": { "type": "string", "nullable": true, "description": "A Json Web Token, may include identity or product holding claims. Only relevant for executing promo code with a linked dynamic offer." }, "path": { "type": "string", "nullable": true, "description": "Request path, required for trials if used. Only relevant for executing promo code with a linked dynamic offer." }, "content_id": { "type": "string", "description": "Content ID, used to perform requests to a 3rd party API for additional content information used in making a decision. Only relevant for executing promo code with a linked dynamic offer." } } } } } } } }, "/blaize/oauth/state": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth-state-response" }, "examples": { "response": { "value": { "message": "State initialized" } } } } } } }, "summary": "Start an OAuth flow", "operationId": "startOAuthFlow", "description": "Starts the OAuth flow.", "tags": [ "OAuth Flow" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "start_url": { "type": "string" }, "target_url": { "type": "string" } }, "example": { "start_url": "http://blaize.io", "target_url": "http://blaize.io" } } } } } } }, "/blaize/oauth/google/callback": { "get": { "responses": { "302": { "description": "Found", "headers": { "Location": { "schema": { "type": "string" } }, "Set-Cookie": { "schema": { "type": "string" } } } } }, "summary": "Create a callback for the Google OAuth flow", "operationId": "createGoogleOAuthFlow", "description": "Callback for Google OAuth Flow.", "tags": [ "OAuth Flow" ], "parameters": [ { "name": "code", "in": "query", "description": "OAuth code", "required": true, "schema": { "type": "string" } } ] } }, "/blaize/oauth/facebook/callback": { "get": { "responses": { "302": { "description": "Found", "headers": { "Location": { "schema": { "type": "string" } }, "Set-Cookie": { "schema": { "type": "string" } } } } }, "summary": "Create a callback for the Facebook OAuth flow", "operationId": "createFacebookOAuthFlow", "description": "Callback for Facebook OAuth flow.", "tags": [ "OAuth Flow" ], "parameters": [ { "name": "code", "in": "query", "description": "OAuth code", "required": true, "schema": { "type": "string" } } ] } }, "/blaize/oauth/linkedin/callback": { "get": { "responses": { "302": { "description": "Found", "headers": { "Location": { "schema": { "type": "string" } }, "Set-Cookie": { "schema": { "type": "string" } } } } }, "summary": "Create a callback for the Linkedin OAuth flow", "operationId": "createLinkedinOAuthFlow", "description": "Callback for Linkedin OAuth flow.", "tags": [ "OAuth Flow" ], "parameters": [ { "name": "code", "in": "query", "description": "OAuth code", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/subscribe": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "example": "33d576c7-d036-40e7-8141-8a91998a5c79", "description": "New grant of product bundle to user." }, "client_secret": { "type": "string", "example": "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj`", "description": "(Stripe) reference to Stripe payment required to process payment in front end." }, "payment_intent_id": { "type": "string", "example": "pi_1GYZYWLgUJT2XNPAYQMomeqf", "description": "(Stripe) reference to the payment intent if payment requires confirmation." } } }, "examples": { "response": { "value": { "grant_id": "33d576c7-d036-40e7-8141-8a91998a5c79", "client_secret": "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj`", "payment_intent_id": "pi_1GYZYWLgUJT2XNPAYQMomeqf" } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "403": { "description": "Forbidden", "headers": {} } }, "summary": "Start the subscription", "operationId": "startSubscription", "description": "Uses the payment info captured by the payment provider drop-in UI and create a customer with a recurring payment.\nWhen the payment provider responds successfully, the logged-in user will be temporarily granted all entitlements in the product's associated bundle.\n", "tags": [ "Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID/slug" }, "plan_id": { "type": "string", "description": "Plan ID/slug" }, "discount_code": { "type": "string", "description": "Discount/promotion code" }, "vendor_fields": { "type": "object", "properties": { "payment_nonce": { "type": "string", "description": "(Stripe) Payment method nonce from Braintree drop-in UI." }, "skip_trial_period": { "type": "boolean", "description": "(Braintree) Whether or not to skip any trial period that may be associated with this subscription. This should be `null` or not set to use the configured trial period." }, "start_date": { "type": "string", "description": "(Braintree) ISO 8601 date format which determines when the subscription will start. When the attribute is passed, the value must be in the future. Otherwise, the subscription is expected to start immediately." }, "payment_method": { "type": "string", "description": "(Stripe) Payment method from Stripe Elements UI." }, "vault_payment_method": { "type": "boolean", "description": "(Braintree) If the payment nonce requires vaulting, for example if Google Pay is being used. Defaults to false." } }, "description": "Parameters specific to the payment provider in-use." } }, "required": [ "product_id" ], "example": { "product_id": "premium-access-monthly-recurring", "plan_id": "plan-5", "discount_code": "SAVE10", "vendor_fields": { "payment_nonce": "eyJ2ZXmsaW5nQW...(lots more random-looking characters)...dyZWmVubW8iOiJvZmYifQ==", "skip_trial_period": true, "start_date": "2021-01-01T00:00:00Z", "payment_method": "pm_123456789", "vault_payment_method": false } } } } } } } }, "/zephr/subscriptions/:subscriptionId": { "patch": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "example": "33d576c7-d036-40e7-8141-8a91998a5c79", "description": "New grant of product bundle to user." } } }, "examples": { "response": { "value": { "grant_id": "33d576c7-d036-40e7-8141-8a91998a5c79" } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Update the subscription", "operationId": "changeSubscription", "description": "Updates an existing subscription to change the associated product and plan. Updating the subscription may modify the price of the subscription, and if so the balance will be billed immediately at a pro-rated amount. Parameters specific to the vendor may be specified to change the payment method for the subscription. Changing to a plan with a different billing frequency from the existing subscription is not supported for some payment providers (Braintree).", "tags": [ "Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product Id/slug" }, "plan_id": { "type": "string", "description": "Plan Id/slug" }, "vendor_fields": { "type": "object", "properties": { "payment_nonce": { "type": "string", "description": "(Braintree) Payment method nonce from Braintree drop-in UI. If not specified, the existing payment method on the subscription will be retained." } }, "description": "Parameters specific to the payment provider in-use." }, "navigated_from": { "type": "string", "description": "Specify where the request was made from. Used as data to pass to change subscription webhooks." } }, "required": [ "product_id", "plan_id", "vendor_fields" ], "example": { "product_id": "premium-access-monthly-recurring", "plan_id": "plan-5", "vendor_fields": { "payment_nonce": "eyJ2ZXmsaW5nQWdyZWmVubW8iOiJvZmYifQ==" }, "navigated_from": "/some/path" } } } } } } }, "/zephr/public/products/v1/shares": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/product_sharing_response" }, "examples": { "response": { "value": { "owned_products": [ { "product_id": "product-1", "product_label": "Gold Product", "sharing_limit": 3, "shares": { "member_email": "name@domain.com", "sharing_id": "0nasdj-aso25-6454", "status": "active", "created_at": "2021-05-17T04:31:33Z" } } ], "member_products": [ { "product_id": "product-1", "product_label": "Gold Product", "sharing_id": "0nasdj-aso25-6454", "status": "active", "shared_by_email": "owner-user@domain.com", "created_at": "2021-05-17T04:31:33Z", "meta_data": {} } ] } } } } } }, "401": { "description": "Unauthorized", "headers": {} }, "403": { "description": "Forbidden", "headers": {} } }, "summary": "Retrieve the product sharing summary", "operationId": "getProductSharingSummary", "description": "Retrieves a summary of the products that the current user shares with other users, and products that are shared with the current user.", "tags": [ "Product Sharing" ] } }, "/zephr/public/products/v1/shares/{sharing_id}": { "delete": { "responses": { "200": { "description": "OK", "headers": {} }, "404": { "description": "Product share ID not found", "headers": {} } }, "summary": "Delete the product sharing by ID", "operationId": "deleteUserProductSharing", "description": "Deletes a user product share by ID. Pending invites and accepted shares can be deleted. Invoking this method will increase the number of shares that the user has available for the given product. If the sharing_id corresponds to an accepted share, the member will immediately lose access to the product unless they have separate access. The member will receive an email notification about their removal. This email can be configured in the Admin Console.", "tags": [ "Product Sharing" ], "parameters": [ { "name": "sharing_id", "in": "path", "description": "The ID of the user product share to delete.", "required": true, "example": "0nasdj-aso25-6454", "schema": { "type": "string" } } ] } }, "/zephr/public/products/v1/shares/invitations/emails": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "required": [ "sharing_id" ], "properties": { "sharing_id": { "type": "string", "example": "0nasdj-aso25-6454", "description": "The ID of the created product share." } } }, "examples": { "response": { "value": { "sharing_id": "0nasdj-aso25-6454" } } } } } }, "400": { "description": "Bad Request. Also returned if the product is not shareable.", "headers": {} }, "403": { "description": "Forbidden", "headers": {} }, "404": { "description": "Product ID not found.", "headers": {} }, "409": { "description": "Conflict. There already is a sharing invite for this product and email.", "headers": {} } }, "summary": "Create a product sharing invite via Email", "operationId": "createProductSharingInviteViaEmail", "description": "Creates a new user product share and send it via email. The exact contents of this email are configurable in the admin console. The email may include a link composed of the required attribute `base_url` and an additional path parameter `sharing_id`. It is expected that the specified `base_url` will direct invite recipients to a page that allows them to accept the invite and register/login. Custom metadata can also be passed to this method, which will be made available in the invitation email template and any later calls to access the publicly available share data. This metadata can be used, for example, to include the product owner's first name and a personalised message that is shown to the recipient in the invitation email and in a screen that allows the recipient to accept the invite. Invoking this method will reduce the number of shares that the user has available for the given product. The specified product must be shareable, the current user must have active grants for the product and must not have already exceeded the configured maximum number of shares for the product.", "tags": [ "Product Sharing" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the product that is being shared." }, "email_address": { "type": "string", "description": "The email address to send the invite to." }, "base_url": { "type": "string", "description": "The invite link destination URL. The path parameter 'sharing_id=xxx' will be added to this URL. Other path parameters and anchors are accepted." }, "meta_data": { "type": "object", "properties": {}, "description": "Extra information for the user product share, which can be included in the sent email." } }, "required": [ "product_id", "email_address", "base_url" ], "example": { "product_id": "product-1", "email_address": "name@domain.com", "base_url": "https://example.com/accept-invite" } } } } } } }, "/zephr/public/products/v1/shares/invitations/tokens": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "required": [ "sharing_id" ], "properties": { "sharing_id": { "type": "string", "example": "0nasdj-aso25-6454", "description": "The ID of the created product share." } } }, "examples": { "response": { "value": { "sharing_id": "0nasdj-aso25-6454" } } } } } }, "400": { "description": "Bad Request. Also returned if the product is not shareable.", "headers": {} }, "403": { "description": "Forbidden", "headers": {} }, "404": { "description": "Product ID not found.", "headers": {} }, "409": { "description": "Conflict. There already is a sharing invite for this product and email.", "headers": {} } }, "summary": "Create a product share invite token", "operationId": "createProductShareInviteToken", "description": "Creates a new user product share. Invoking this method will reduce the number of shares that the user has available for the given product. The returned token sharing ID can later be passed to the accept invite method. Custom metadata can also be passed to this method, which will be made available in later calls to access the publicly available share data. This metadata can be used, for example, to include the product owner's first name and a personalised message that is shown to the recipient in a screen that allows the recipient to accept the invite. Invoking this method will reduce the number of shares that the user has available for the given product. The specified product must be shareable, the current user must have active grants for the product and must not have already exceeded the configured maximum number of shares for the product.", "tags": [ "Product Sharing" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the product that is being shared." }, "meta_data": { "type": "object", "description": "Extra information for the user product share." } }, "required": [ "product_id" ], "example": { "product_id": "product-1" } } } } } } }, "/zephr/public/products/v1/shares/invitations/{sharing_id}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "example": "product-1", "description": "The ID of the product that is shared." }, "product_label": { "type": "string", "example": "Gold Product", "description": "The label of the product that is shared." }, "meta_data": { "type": "object", "properties": { "additionalProperties": { "type": "string" } }, "description": "Extra information for the user product share, defined at the point of creation." } } }, "examples": { "response": { "value": { "product_id": "product-1", "product_label": "Gold Product", "meta_data": {} } } } } } }, "404": { "description": "Not Found - No product share invite found with the supplied `sharing_id`.", "headers": {} }, "429": { "description": "Too Many Requests", "headers": {} } }, "summary": "Retrieve the product share invite public data", "operationId": "getProductShareInvitePublicData", "description": "Retrieves the publicly accessible data relating to a user product share invite. This can be used to inform the invitee of the details of the product that is being shared, and any meta_data added at the point of invite creation, such as the name of the user that sent the invite.\nThis endpoint is not authenticated. The information provided by this endpoint is available to anyone with a valid `sharing_id`.\nInvoking this endpoint too rapidly will result in a 429 error response.", "tags": [ "Product Sharing" ], "parameters": [ { "name": "sharing_id", "in": "path", "description": "The ID of the user product sharing invite.", "required": true, "example": "0nasdj-aso25-6454", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {} }, "400": { "description": "Bad request", "headers": {} }, "404": { "description": "Product share ID or product ID not found.", "headers": {} }, "409": { "description": "Conflict. The current user already has a product share for the same product from the same product owner.", "headers": {} } }, "summary": "Accept a product share invite", "operationId": "acceptProductShareInvite", "description": "Accepts a product sharing invite. The current user will gain access to the product linked to the sharing invite. The user that send the invite must have an active grant for the product at the point of acceptance. If the current user already has a product share for the same product from the same product owner, an error code 409 will be returned and the invite will not be accepted.", "tags": [ "Product Sharing" ], "parameters": [ { "name": "sharing_id", "in": "path", "description": "The ID of the user product sharing invite.", "required": true, "example": "0nasdj-aso25-6454", "schema": { "type": "string" } } ] } }, "/zephr/decide": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feature-decisions-response" }, "examples": { "response": { "value": { "results": [ { "sdkFeatureSlug": "featureX", "outputType": "ENUM", "outputValue": "YES", "error": "500: Internal error ..." } ] } } } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Process multiple decisions", "operationId": "processMultipleDecisions", "description": "Processes multiple decisions. The SDK Feature Decision Engine can be invoked via the Public API to calculate a decision output response based upon Feature SDK Rules created in the Zephr Console.\n", "tags": [ "SDK Feature Decision Engine" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "array", "description": "The list of features to evaluate. This must be contain at least one element. Features are evaluated sequentially, in the order they are provided.", "items": {} }, "session": { "type": "string", "description": "Zephr Session ID, required for trials." }, "foreign_keys": { "type": "object", "properties": {}, "description": "Foreign system and ID used to identify the user." }, "ip": { "type": "string", "description": "Client IP address, defaults to request IP." }, "user_agent": { "type": "string", "description": "Client user agent" }, "jwt": { "type": "string", "description": "A Json Web Token, may include identity or product holding claims." }, "dry_run_mode": { "type": "boolean", "default": false, "description": "A flag to indicate where the decision request would persist states such as user entitlement, segments, test groups, etc." } }, "required": [ "features" ], "example": { "features": [ { "slug": "featureX", "path": "/x.html", "content_id": "xxx-xxx-xxx", "inputs": {} } ], "session": "xxx-xxx-xxx", "foreign_keys": {}, "ip": "x.x.x.x", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11)...", "jwt": "xxx-xxx-xxx" } } } } } } }, "/zephr/decision-engine": { "post": { "responses": { "200": { "description": "OK. The output of the SDK feature rule, which may be wrapped with metadata according to the `raw` query parameter value.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feature-decision-response" }, "examples": { "success": { "value": { "sdkFeatureSlug": "sdk-feature-1", "outputType": "ENUM", "outputValue": "YES" } }, "error": { "value": { "sdkFeatureSlug": "sdk-feature-1", "error": "500: Internal error ..." } } } }, "none": { "schema": { "$ref": "#/components/schemas/feature-decision-response-raw" }, "examples": { "string": { "value": "YES" }, "json": { "value": { "custom-key": "custom-value" } } } } } } }, "summary": "Process a single decision", "operationId": "processSingleDecision", "description": "Processes a single SDK feature decision. An SDK feature rule can be configured in the console, and allows a custom decision to be made using a range of inputs to drive the behaviour of a website or app. SDK features can output any one of several data types as configured in the console.\n - String: The output can be any string.\n - Number: The output can be any numerical value\n - Enum: The output can be one of a list of strings as configured in the developer panel for the rule. This is used for short output strings.\n - Component: The output can be one of a list of strings as configured in the developer panel for the rule. This is used for long output strings, such as HTML or JSON.\n - JSON: The output can be any JSON object. JSON schema validation can optionally be enforced when creating JSON outputs in the console.\n - Transformation: The output will be a JSON array of transformations to be applied to content on a webpage or in an app. This allows the configuration of the same types of outcomes that can be built with an HTML feature rule, such as hiding content and displaying a payment form.\n\n\nSDK features permit business decisions to drive access or behaviour to be made in an app that is not using HTML content. SDK decisions are relevant for both anonymous and authenticated sessions. If no session is provided via the request then an anonymous session will not be created.\n\nInvoking an SDK decision may cause side effects as configured in the rule, such as invoking webhooks or recording trial usages. When `dryRunMode` is enabled in the request, trial usages will not be recorded.\n", "tags": [ "SDK Feature Decision Engine" ], "parameters": [ { "name": "raw", "in": "query", "description": "If set to true, then the decision output will be returned in it's raw form, without metadata.
If set to false, the decision output will be returned in an escaped form together with metadata about the decision.", "required": true, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sdkFeatureSlug": { "type": "string", "description": "Feature SDK slug as configured in the console." }, "session": { "type": "string", "description": "Zephr Session ID, required for trials and for user-based decisions." }, "foreign_keys": { "type": "object", "properties": {}, "description": "A map where the key is a foreign system and the value is an ID used to identify the user in that system." }, "ip": { "type": "string", "description": "Client IP address, defaults to request IP." }, "userAgent": { "type": "string", "description": "Client user agent." }, "path": { "type": "string", "description": "Request path representing the content being consumed for trials." }, "contentId": { "type": "string", "description": "Content ID, used to perform requests to a 3rd party API for additional content information used in making a decision. The endpoint and path format for content ID requests can be configured in the console." }, "jwt": { "type": "string", "description": "A Json Web Token, may include identity or product holding claims." }, "giftToken": { "type": "string", "description": "Enables a decision to be made in the rule based on whether access should be granted as the user has gift access." }, "dryRunMode": { "type": "boolean", "description": "If the decision should be run without recording trial usage." } }, "additionalProperties": { "type": "string", "description": "Custom inputs configured in Feature SDK rule." }, "required": [ "sdkFeatureSlug" ], "example": { "sdkFeatureSlug": "sdk-feature-1", "session": "0f88f32c-b03c-49cd-b977-0ca224d1acee", "foreign_keys": { "external-system": "user-1" }, "ip": "56.123.124.23", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11)...", "path": "/article.html", "contentId": "paid-article-123", "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "dryRunMode": false, "giftToken": "23810040-8149-4f4e-a4d1-c8268340be7f", "custom-input-1": "custom-value" } } } } } }, "get": { "responses": { "200": { "description": "Raw parameter response", "headers": {}, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/feature-decision-response" } } } } }, "summary": "Retrieve a single decision", "operationId": "getSingleDecision", "description": "For compatibility with CDN, any web headers (Referrer, User-Agent) will be accepted and passed onto the rule engine", "tags": [ "SDK Feature Decision Engine" ], "parameters": [ { "name": "sdkFeatureSlug", "in": "query", "description": "Feature SDK slug", "required": true, "example": "featureX", "schema": { "type": "string" } }, { "name": "session", "in": "query", "description": "Zephr Session ID, required for trials.", "required": true, "example": "xxx-xxx-xxx", "schema": { "type": "string" } }, { "name": "foreign_id.xxx", "in": "query", "description": "Foreign ID used to identify the user. The foreign system is parsed as the remainder of the parameter key name following 'foreign_id.'", "required": true, "example": "xxx-xxx-xxx", "schema": { "type": "string" } }, { "name": "ip", "in": "query", "description": "Client IP address, defaults to request IP.", "required": true, "example": "x.x.x.x", "schema": { "type": "string" } }, { "name": "userAgent", "in": "query", "description": "Client user agent", "required": true, "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11)...", "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Request path, required for trials.", "required": true, "example": "/x.html", "schema": { "type": "string" } }, { "name": "content_id", "in": "query", "description": "Content ID, used to perform requests to a 3rd party API for additional content information used in making a decision.", "required": true, "example": "xxx-xxx-xxx", "schema": { "type": "string" } }, { "name": "jwt", "in": "query", "description": "A Json web token, may include identity or product holding claims.", "required": true, "example": "xxx-xxx-xxx", "schema": { "type": "string" } }, { "name": "raw", "in": "query", "description": "Should output raw value", "required": true, "schema": { "type": "boolean", "default": false } } ] } }, "/zephr/public/sessions/v1/sessions": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "examples": { "response": { "value": [ { "id": "aba22-a5mfh-", "startDate": "2011-11-11T11:11:11.000", "deviceType": "pc", "deviceName": "Google Nexus 5", "browser": "Chrome", "os": "Android", "city": "Huston", "geoState": "Texas", "country": "USA", "isRequestingSession": true } ] } } } } }, "401": { "description": "Unauthorized", "headers": {} }, "403": { "description": "Forbidden", "headers": {} } }, "summary": "List all the user sessions", "operationId": "listUserSessions", "description": "Lists of all sessions for the current user and site.", "tags": [ "Sessions" ] }, "delete": { "responses": { "200": { "description": "OK", "headers": {} } }, "summary": "Delete all other sessions", "operationId": "deleteAllOtherSessions", "description": "Deletes all sessions for the current user and site apart from the session used to make the request.", "tags": [ "Sessions" ], "parameters": [ { "name": "except-current", "in": "query", "required": true, "schema": { "type": "boolean" } } ] } }, "/zephr/public/sessions/v1/sessions/{sessionId}": { "delete": { "responses": { "200": { "description": "OK", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Delete the session by ID", "operationId": "deleteSession", "description": "Deletes a session by ID. Returns a 404 if the specified session does not exist or does not belong to the current user.", "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "description": "The ID of the session to delete.", "required": true, "example": "0nasdj-aso25-6454", "schema": { "type": "string" } } ] } }, "/blaize/payment/stripe/publicKey": { "get": { "responses": { "200": { "description": "A stripe public key for the tenant.", "headers": {}, "content": { "application/json": { "schema": { "type": "string" }, "examples": { "keyFound": { "value": "pk_live_PFghBsstUo5FwUGcXBiNvIkY00X1YHtpnJ", "summary": "A stripe tenant public key is found." }, "keyNotFound": { "value": "No Stripe public key found", "summary": "A stripe tenant public key is not found." } } } } } }, "summary": "Retrieve the Stripe public key", "operationId": "getStripePublicKey", "description": "This API endpoint fetches the public key associated with a tenant for payment processing. If the user is authenticated and the tenant has a configured Stripe public key, the endpoint will return the Stripe public key in a String format.", "tags": [ "Stripe Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie is employed to ascertain whether a user is already authenticated or has an active session.", "required": true, "example": "blaize_session=57685913-7365-4dae-a425-1c2c2f72cc0", "schema": { "type": "string" } } ] } }, "/zephr/payment/stripe/setupIntentSecret": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientSecret": { "type": "string", "example": "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj", "description": "Reference to Stripe payment required to process payment in front end." } } }, "examples": { "response": { "value": { "clientSecret": "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj" } } } } } }, "404": { "description": "Could not find a Stripe customer for the current Zephr user.", "headers": {} } }, "summary": "Create a Stripe setup intent secret", "operationId": "createStripeSetupIntentSecret", "description": "Creates the client secret to update card details", "tags": [ "Stripe Payments" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] } }, "/blaize/payment/stripe/subscription/confirmation": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "example": "aa583cb8-51d1-4bd9-9ec7-3a43796ef8e5", "description": "New grant of product bundle to user" } } }, "examples": { "response": { "value": { "grant_id": "aa583cb8-51d1-4bd9-9ec7-3a43796ef8e5" } } } } } } }, "summary": "Start the Stripe subscription confirmation", "operationId": "startStripeSubscriptionConfirmation", "description": "If a payment requires confirmation (3dSecure etc), the payment is confirmed in the front end.", "tags": [ "Stripe Payments" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string" } }, "example": { "subscriptionId": "sub_H8eIeMFwMawg6w" } } } } } } }, "/zephr/payment/stripe/updateSubscription": { "post": { "responses": { "200": { "description": "OK", "headers": {} } }, "summary": "Update the Stripe subscription", "operationId": "updateStripeSubscription", "description": "Updates the payment method in the subscription. Payment method id will be provided by stripe on updating card details in the front end.", "tags": [ "Stripe Payments" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string" }, "payment_method_id": { "type": "string" } }, "required": [ "subscription_id", "payment_method_id" ], "example": { "subscription_id": "sub_H8eIeMFwMawg6w", "payment_method_id": "pm_2KrMmOCvDgIhZCB6u0Yn7COE" } } } } } } }, "/blaize/payment/stripe/buy": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string", "example": "aa583cb8-51d1-4bd9-9ec7-3a43796ef8e5", "description": "New grant of product bundle to user" }, "client_secret": { "type": "string", "example": "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj`", "description": "Reference to Stripe payment required to process payment in front end." }, "payment_intent_id": { "type": "string", "example": "pi_1GYZYWLgUJT2XNPAYQMomeqf", "description": "Reference to the payment intent if payment requires confirmation." } } }, "examples": { "response": { "value": { "grant_id": "aa583cb8-51d1-4bd9-9ec7-3a43796ef8e5", "client_secret": "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj`", "payment_intent_id": "pi_1GYZYWLgUJT2XNPAYQMomeqf" } } } } } } }, "summary": "Create a Stripe one-off payment", "operationId": "buyStripe", "description": "Uses the payment method collected by Stripe Elements to create a one off payment.", "tags": [ "Stripe Payments" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID/slug" }, "price_point_id": { "type": "string", "description": "Price Point ID/slug" }, "payment_method": { "type": "string", "description": "Payment method from Stripe Elements UI." }, "payment_intent_id": { "type": "string", "description": "PaymentIntent ID returned after confirming a card payment." } }, "required": [ "product_id", "price_point_id", "payment_method" ], "example": { "product_id": "lifetime-membership", "price_point_id": "gold-package", "payment_method": "pm_123456789", "payment_intent_id": "pi_1GYZYWLgUJT2XNPAYQMomeqf" } } } } } } }, "/blaize/payment/stripe/subscriptionChargedCallback": { "post": { "responses": { "200": { "description": "OK", "headers": {} } }, "summary": "Receive a webhook from Stripe for when a user is charged for a subscription.", "operationId": "callbackStripeSubscriptionCharged", "description": "To use subscriptions, Stripe Webhooks for `invoice.payment_succeeded` must be configured to point to this endpoint.", "tags": [ "Stripe Payments" ] } }, "/zephr/payment/stripe/subscription/{subscriptionId}/change-previews": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "*/*": { "schema": { "type": "object", "properties": { "total": { "type": "number", "example": 5000, "description": "The total amount of the prorate invoice in the relevant currency's lowest denomination (e.g. pence)." }, "sub_total": { "type": "number", "example": 4500, "description": "The total amount of the prorate invoice minus tax in the relevant currency's lowest denomination (e.g. pence)." } } } } } }, "400": { "description": "Bad Request", "headers": {} }, "401": { "description": "Unauthorized", "headers": {} } }, "summary": "Preview the Stripe subscription change", "operationId": "previewStripeChangeSubscription", "description": "Generates a preview of the invoice that Stripe will create for the customer if their\nsubscription is changed to a new plan. The invoice will be a prorated invoice for the\nprice difference between current and new subscription plans for the remainder of the current billing period.\nThe invoice will be billed immediately upon changing subscription.\nThe invoice amount may be negative if the customer is changing to a lower-priced plan.\n\n**Note**: This method does not modify the user's subscription.", "tags": [ "Stripe Payments" ], "parameters": [ { "name": "subscriptionId", "in": "path", "description": "The ID of the Stripe subscription to change.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The new Stripe price plan ID." } }, "required": [ "plan_id" ], "example": { "plan_id": "price_H8eIeMFwMawg6w" } } } } } } }, "/zephr/payment/stripe/create-subscription-previews": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "*/*": { "schema": { "type": "object", "properties": { "total": { "type": "number", "example": 5000, "description": "The total amount the user will be initially charged for the subscription in the relevant currency's lowest denomination (e.g. pence), i.e. for a monthly subscription, the first month's cost." }, "sub_total": { "type": "number", "example": 4500, "description": "The total amount minus tax for the initial charge in the relevant currency's lowest denomination (e.g. pence)." }, "tax": { "type": "number", "example": 500, "description": "The tax amount for the initial charge in the relevant currency's lowest denomination (e.g. pence)." }, "discount": { "type": "number", "description": "The discount amount for the initial charge in the relevant currency's lowest denomination (e.g. pence)." } } } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Preview the Stripe subscription price", "operationId": "previewStripeSubscriptionPrice", "description": "Generates a preview of the total price and tax amount that Stripe will charge the customer if they\ncreate a new subscription for the specified plan.\n\n**Note**: This method does not create any entities in Stripe and does not result in any payments being made.", "tags": [ "Stripe Payments" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the new Zephr product." }, "plan_id": { "type": "string", "description": "The new Stripe price plan ID." }, "promo_code": { "type": "string", "description": "The Stripe promo code that will be attached to the subscription." }, "billing_country": { "type": "string", "description": "The user's billing country, for tax calculation purposes." }, "billing_post_code": { "type": "string", "description": "The user's billing postal code, for tax calculation purposes." } }, "required": [ "product_id", "plan_id" ], "example": { "product_id": "zephr-prod-1", "plan_id": "price_H8eIeMFwMawg6w", "promo_code": "discount15", "billing_country": "US", "billing_post_code": "90210" } } } } } } }, "/zephr/payment/stripe/promo-code": { "get": { "summary": "Check a Stripe promo code for a user", "operationId": "checkStripePromoCode", "description": "Checks a Stripe promo code for the logged in user. The promo code is checked for validity of the current user based on first time order restriction, specific customer restriction, max allowed redemptions and expiration. The payment form payment options are checked to match the minimum payment amount requirements of the promo code.", "tags": [ "Stripe Payments" ], "parameters": [ { "name": "code", "in": "query", "description": "The ID of the Stripe promo code to check.", "required": true, "schema": { "type": "string" } }, { "name": "paymentForm", "in": "query", "description": "The slug of the Stripe payment form the promo code relates to.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripePromoCodeCheckResponse" } } } } } } }, "/zephr/payment/stripe/promo-code-check": { "post": { "summary": "Check a Stripe promo code for a user", "operationId": "checkStripePromoCodeWithPaymentOptions", "description": "Checks a Stripe promo code for the logged in user. The promo code is checked for validity of the current user based on first time order restriction, specific customer restriction, max allowed redemptions and expiration. The supplied payment payment options are checked to match the minimum payment amount requirements of the promo code.", "tags": [ "Stripe Payments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripePromoCodeCheckRequest" } } } }, "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripePromoCodeCheckResponse" } } } } } } }, "/zephr/payment/stripe/subscriptions/{externalId}/change-previews": { "post": { "summary": "Change the Stripe subscription price", "operationId": "previewEditStripeSubscriptionPrice", "description": "Generates a new preview of the price that Stripe will charge the customer if they create a new subscription for the specified plan.\nNote: This method does not create any entities in Stripe and does not result in any payments being made.", "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number", "example": 5000, "description": "The total amount the user will be initially charged for the subscription in the relevant currency's lowest denomination (e.g. pence), i.e. for a monthly subscription, the first month's cost." }, "sub_total": { "type": "number", "example": 4500, "description": "The total amount minus tax for the initial charge in the relevant currency's lowest denomination (e.g. pence)." } } } } } }, "400": { "description": "Bad Request", "headers": {} } } } }, "/blaize/payment/stripe/subscribe": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/stripe_start_response_body" } } } } }, "summary": "Start the Stripe subscription (Deprecated)", "operationId": "startStripeSubscription", "description": "(Deprecated - use [/zephr/subscribe](#payments-start-subscription-post))\nUses the payment method info captured by the Stripe Elements UI to create a Stripe customer with a recurring payment.\nWhen Stripe responds successfully, the logged-in user will be temporarily granted all entitlements in the product's associated bundle.", "tags": [ "Stripe Payments" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product Id/slug" }, "payment_method": { "type": "string", "description": "Payment method from Stripe Elements UI." }, "plan_id": { "type": "string" }, "discount_code": { "type": "string" } }, "required": [ "product_id", "payment_method" ], "example": { "product_id": "premium-access-monthly-recurring", "payment_method": "pm_123456789" } } } } } } }, "/blaize/payment/stripe/subscriptions": { "get": { "summary": "List the user's Stripe subscriptions", "operationId": "listStripeSubscriptions", "description": "Lists the user's Stripe subscriptions.", "tags": [ "Stripe Payments" ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StripeSubscription" } } } } }, "401": { "description": "Unauthenticated", "headers": {} } } } }, "/blaize/payment/stripe/subscriptions/{externalId}": { "delete": { "summary": "Cancel a user's Stripe subscription", "operationId": "cancelStripeSubscription", "description": "Cancels a user's Stripe subscription", "tags": [ "Stripe Payments" ], "parameters": [ { "name": "externalId", "in": "path", "description": "The ID of the Stripe subscription to cancel.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": {} }, "403": { "description": "Forbidden", "headers": {} }, "404": { "description": "Cannot find the subscription.", "headers": {} }, "409": { "description": "Subscription was already cancelled", "headers": {} } } } }, "/zephr/oauth2": { "get": { "responses": { "302": { "description": "Found", "headers": { "Location": { "schema": { "type": "string" } } } } }, "summary": "Start an authorization code flow", "operationId": "startOAuth2Flow", "description": "Starts OAuth2 Authorization Code Flow. The resource owner will be authenticated and be presented with the third-party application access request.", "tags": [ "Third-Party Authentication" ], "parameters": [ { "name": "client_id", "in": "query", "description": "Zephr Site Oauth2 Client ID.", "required": true, "schema": { "type": "string" } }, { "name": "response_type", "in": "query", "description": "Must be set to `code`.", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "description": "Client's redirection endpoint. Must be an absolute URI.", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "The scope of the access request.", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "An opaque value used by the client to maintain state between the request and callback.", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/oauth2/consent/{clientId}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list-oauth2-consent" }, "example": { "consent": [ "user.account:read", "user.account:write" ] } } } }, "400": { "description": "Missing required clientId parameter." }, "401": { "description": "User session not authenticated." } }, "summary": "Returns a list of your user's access scopes", "operationId": "listOAuth2ConsentFlow", "tags": [ "Third-Party Authentication" ], "parameters": [ { "name": "clientId", "in": "path", "description": "The Zephr site's Oauth2 client ID.", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/oauth2/token": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth2-token-response" } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Request oauth2 access token", "operationId": "requestOauth2AccessToken", "description": "Facilitates the acquisition of an OAuth2 access token. It requires either a basic authorization header or a client_id provided in the request body.", "tags": [ "Oauth2 Access Token" ], "parameters": [ { "name": "client_id", "in": "query", "required": false, "description": "The Zephr site's Oauth2 client ID.", "schema": { "type": "string", "example": "client_id=1234567890" } }, { "name": "authorization", "in": "header", "required": false, "description": "Encoded basic authorisation header that includes Zephr Site Oauth2 Client ID.", "example": "Authorization: Basic ZGVtbzpwQDU1dzByZA==", "schema": { "type": "string" } } ] } }, "/zephr/oauth2/grant": { "post": { "responses": { "200": { "description": "OK. The template variable \"BASICAUTH\" is set as the authorization header of \"$CLIENTID\" and \"$CLIENTSECRET\". The template variable \"AUTHCODE\" is set to the response body \"code\" field.", "headers": { "Location": { "schema": { "type": "string" } } }, "content": { "*/*": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "State (string)" }, "code": { "type": "string", "description": "Authorization code (string)" } } } } } }, "401": { "description": "Unauthorized", "headers": {}, "content": { "*/*": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "State (string)" }, "error": { "type": "string", "description": "Error type (string)" } } } } } } }, "summary": "Grant the access request", "operationId": "grantAccessRequest", "description": "The resource owner will consent or deny the third party application access request, and Zephr will return an authorization code upon user's consent.", "tags": [ "Third-Party Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth2-request-body" } } } } } }, "/zephr/oauth2/config": { "get": { "responses": { "200": { "description": "Public OAuth2 fields returned", "headers": {}, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/oauth2-config-response" } } } } }, "summary": "Retrieves the oauth2 configured fields", "operationId": "getOAuth2Config", "description": "Gets the public oauth2 fields configured on the Third Party Authentication section of the site", "tags": [ "Third-Party Authentication" ] } }, "/blaize/register": { "post": { "responses": { "200": { "description": "OK. The user was registered successfully.", "headers": { "Set-Cookie": { "description": "The authenticated user session.", "schema": { "type": "string", "example": "blaize_session=443ed68f-0b44-4f32-8443-553d584cb0dd; Expires=Fri, 16 Nov 2018 12:35:56 GMT; Path=/;" } }, "\u0000Set-Cookie": { "description": "The user tracking ID.", "schema": { "type": "string", "example": "blaize_tracking_id=b117093c-e1f7-4ee0-8dda-6b5205f7fbee; Expires=Fri, 16 Nov 2018 12:35:56 GMT; Path=/;" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-register-response" } } } }, "400": { "description": "Bad Request. The request included invalid syntax or was missing required parameters. This could alternatively be attributed to the absence of a user email address in the request body.", "headers": {} } }, "summary": "Register a user", "operationId": "registerUsers", "description": "This endpoint enables clients to initiate the creation of a new user account. If a contact with an identical email address already exists, that contact will be elevated to the status of a registered user. Essential attributes like `identifiers.email_address` and `validators.password` are mandatory for this endpoint. If any of these attributes are absent, registration attempts will trigger an error. Upon a successful request, session cookies like blaize_session and blaize_tracking_id are generated and included in the response header.", "tags": [ "User" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-register-request" } } } } } }, "/zephr/createContact": { "post": { "responses": { "200": { "description": "Created or updated a contact user", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "tracking_id": { "type": "string", "description": "A unique ID assigned to the created contact for tracking purposes." }, "message": { "type": "string", "description": "A human-readable message describing the result of the operation." } } }, "examples": { "Create-New-Contact": { "value": { "tracking_id": "0014fdc8-55d1-4916-bbde-5b83b5846766", "message": "Creating contact successful" } }, "Update-Existing-Contact": { "value": { "message": "Updating user attributes successful" } } } } } }, "400": { "description": "Bad Request\n\nReturned if a request is missing an email identifier, or if some user attributes are invalid.", "headers": {} }, "403": { "description": "Contact creation not enabled", "headers": {} }, "409": { "description": "User {email} already exists\n\nReturned when attempting to update the attributes of an already registered user.", "headers": {} } }, "summary": "Create or Update a Contact User", "operationId": "createContact", "description": "This endpoint creates a new contact user or updates the attributes of an existing contact user if one exists with the supplied email address.\nTo use this endpoint, 'contact users' must be enabled in the identity settings page in the console.\nA contact user is a type of user that has no validators and so no ability to create authenticated sessions. Contact users can be created to capture user information, such as email addresses, without fully registering users.\nThis endpoint cannot be used to update the attributes of a registered user. Attempting to do so will return a 409 response.\nAfter creating a contact with an anonomyous session, the session is updated to include a flag to identify that this has happened. In the rules builder, the 'Contact Capture' decision node can be used to test this flag value and so determine if the current anonymous session was used to create a contact. This can be used, for example, to prevent showing a contact form to anonymous users that have already filled in such a form.", "tags": [ "User" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contact-create-request" } } } } } }, "/blaize/forget-me": { "post": { "responses": { "200": { "description": "OK - User deleted successfully", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/delete-user-response" }, "examples": { "response": { "value": { "message": "User deleted successfully" } } } } } }, "500": { "description": "Internal Server Error", "headers": {} } }, "summary": "Delete the user data", "operationId": "deleteUserData", "description": "Deletes user related data like sessions, elasticSearch data, O2Auth tokens according to the provided `user_id` in the session cookie.", "tags": [ "User" ], "parameters": [ { "name": "Cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] } }, "/blaize/account": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-public-account" }, "examples": { "response": { "value": { "identifiers": { "email_address": "joe.blow@company.com" }, "tracking_id": "123" } } } } } }, "401": { "description": "Unauthorized", "headers": {} } }, "summary": "Retrieve the account", "operationId": "retrieveAccount", "description": "Retrieves the user's core account details.", "tags": [ "User" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] } }, "/blaize/profile": { "get": { "responses": { "200": { "description": "OK. The user attributes were successfully retrieved. Returns a single layer JSON object of this user's attributes.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/attributes" }, "examples": { "NameAttributes": { "value": { "first_name": "Joe", "surname": "Blow" } } } } } }, "401": { "description": "Unauthorized. This endpoint will return successfully for existing authenticated users only.", "headers": {} } }, "summary": "Retrieves the attributes for an authenticated user in the Zephr user store.", "operationId": "retrieveProfile", "description": "Retrieves the attributes for an authenticated user in the Zephr user store. In addition to the standard authenticators, this endpoint also accepts an OAuth bearer token through the Authorization header. The response will only include publicly accessible user attributes.", "tags": [ "User" ], "parameters": [ { "name": "Cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "blaize_session=57685913-7365-4dae-a425-1c2c2f72cc0", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "An OAuth access token key that references a previously created OAuth token. Such a token can be created using the '/zephr/oauth2/token' endpoint and is expected to have the scope 'user.profile:update'.", "required": false, "example": "Bearer AYjcyMzY3ZDhiNmJkNTYt0Zi", "schema": { "type": "string" } } ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/attributes" } } } }, "responses": { "200": { "description": "OK. The message 'User profile updated' is displayed to confirm that the user attributes were successfully saved.", "headers": {} }, "400": { "description": "Bad Request. The request body must be a single layer JSON object. All provided attributes must also pass any applicable attribute validation. All required attributes must be provided and be non-null. All provided attributes must be publicly writable.", "headers": {} }, "401": { "description": "Unauthorized. This endpoint will only return successfully for existing authenticated users.", "headers": {} } }, "operationId": "saveProfile", "summary": "Sets the attributes for an authenticated user in the Zephr user store.", "description": "Sets the attributes for an authenticated user in the Zephr user store. The provided attributes are saved for the user. Any existing attributes for the user are removed and replaced with this new set.", "tags": [ "User" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "blaize_session=57685913-7365-4dae-a425-1c2c2f72cc0", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "An OAuth access token key that references a previously created OAuth token. Such a token can be created using the '/zephr/oauth2/token' endpoint and is expected to have the scope 'user.profile:update'.", "required": false, "example": "Bearer AYjcyMzY3ZDhiNmJkNTYt0Zi", "schema": { "type": "string" } } ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-attributes" } } } }, "responses": { "200": { "description": "OK. The message 'User profile updated' is displayed, to confirm that the user attributes were successfully saved.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "If a 'blaize-validator' was supplied and successfully used to authenticate the request then the response will include blaize session cookies." } } }, "400": { "description": "Bad Request. The request body must be a single layer JSON object. All provided attributes must also pass any applicable attribute validation. All provided required attributes must be non-null. All provided attributes must be publicly writable.", "headers": {} }, "401": { "description": "Unauthorized. This endpoint will only return successfully for existing authenticated users.", "headers": {} } }, "operationId": "updateProfile", "summary": "Updates the attributes for an authenticated user in the Zephr user store.", "description": "Updates the attributes for an authenticated user in the Zephr user store. The behaviour for the POST and PATCH methods on this endpoint is identical. The provided attributes are saved for the user. Any new attributes are added. Any existing attributes with the same keys are updated. Any existing attributes with different keys remain unchanged. The request can also include an optional 'blaize-validator' property to authenticate a previously partially registered user.", "tags": [ "User" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "blaize_session=57685913-7365-4dae-a425-1c2c2f72cc0", "schema": { "type": "string" } } ] }, "patch": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-attributes" } } } }, "responses": { "200": { "description": "OK. The message 'User profile updated', to confirm that the user attributes were successfully saved.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "If a 'blaize-validator' was supplied and successfully used to authenticate the request then the response will include blaize session cookies." } } }, "400": { "description": "Bad Request. The request body must be a single layer JSON object. All provided attributes must also pass any applicable attribute validation. All provided required attributes must be non-null. All provided attributes must be publicly writable.", "headers": {} }, "401": { "description": "Unauthorized. This endpoint will only return successfully for existing authenticated users.", "headers": {} } }, "operationId": "updateProfilePatch", "summary": "Updates the attributes for an authenticated user in the Zephr user store.", "description": "Updates the attributes for an authenticated user in the Zephr user store. The behaviour for the POST and PATCH methods on this endpoint is identical. The provided attributes are saved for the user. Any new attributes are added. Any existing attributes with the same keys are updated. Any existing attributes with different keys remain unchanged. The request can also include an optional 'blaize-validator' property to authenticate a previously partially registered user.", "tags": [ "User" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "blaize_session=57685913-7365-4dae-a425-1c2c2f72cc0", "schema": { "type": "string" } } ] } }, "/blaize/profile/{appId}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/extended-profile" }, "examples": { "jsonExample": { "summary": "JSON Object", "value": { "first_name": "John", "last_name": "Doe", "user_details": { "email_address": "john.doe@zuora.com", "employment": { "company": "Zuora", "job_title": "Software Engineer" }, "consent_prefs": { "email": false, "sms": true }, "interests": [ "Reading", "Coding", "Hiking" ] } } }, "arrayExample": { "summary": "JSON Array", "value": [ { "first_name": "John", "last_name": "Doe", "user_details": { "email_address": "john.doe@zuora.com" } }, { "job_title": "Software Engineer" } ] } } } } }, "400": { "description": "Bad Request. Returned if the appId is invalid.", "headers": {} }, "401": { "description": "Unauthorized. Returned if no valid session was provided.", "headers": {} }, "404": { "description": "Not Found. Returned if the appId is not found.", "headers": {} } }, "summary": "Retrieve Extended Profile", "operationId": "retrieveExtendedProfile", "description": "Extended Profile is used to store additional user information that is not part of the core profile. This endpoint is designed to be used for retrieving the user's Extended Profile. The body can be any valid JSON.", "tags": [ "User" ], "parameters": [ { "name": "appId", "in": "path", "description": "Unique, caller-provided path parameter that represents the context under which the end user's data is stored within a tenant. This cannot start with '_restricted'.", "required": true, "schema": { "type": "string" } }, { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "Extended Profile is used to store additional user information that is not part of the core profile. This endpoint is designed to be used for updating the user's Extended Profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User extended profile updated" } } } } }, "headers": {} }, "400": { "description": "Bad Request. Returned if the appID or the provided body content is invalid.", "headers": {} }, "401": { "description": "Unauthorized. Returned if no valid session was provided.", "headers": {} } }, "summary": "Save Extended Profile", "operationId": "saveExtendedProfile", "description": "Extended Profile is used to store additional user information that is not part of the core profile. This endpoint will create an Extended Profile for the App ID if one did not exist already, or overwrite an existing Extended Profile for the App ID. The body can be any valid JSON.", "tags": [ "User" ], "parameters": [ { "name": "appId", "in": "path", "description": "Unique, caller-provided path parameter that represents the context under which the end user's data is stored within a tenant. This cannot start with '_restricted'.", "required": true, "schema": { "type": "string" } }, { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "`blaize_session=...` (string)", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/extended-profile" }, "examples": { "jsonExample": { "summary": "JSON Object", "value": { "first_name": "John", "last_name": "Doe", "user_details": { "email_address": "john.doe@zuora.com", "employment": { "company": "Zuora", "job_title": "Software Engineer" } }, "consent_prefs": { "email": false, "sms": true }, "interests": [ "Reading", "Coding", "Hiking" ] } }, "arrayExample": { "summary": "JSON Array", "value": [ { "first_name": "John", "last_name": "Doe", "user_details": { "email_address": "john.doe@zuora.com" } }, { "job_title": "Software Engineer" } ] } } } } } } }, "/blaize/authorization/challenge": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cdn-auth-challenge-response" }, "examples": { "response": { "value": { "68cc48be-e47e-4707-8958-1249d87fca86": false } } } } } }, "401": { "description": "Unauthorized", "headers": {} } }, "summary": "Create an authorization challenge", "operationId": "createAuthorizationChallenge", "description": "Authorization Challenge against array of entitlement IDs.", "tags": [ "User" ], "parameters": [ { "name": "cookie", "in": "header", "description": "The session cookie.", "required": false, "example": "blaize_session=5562c0cf-b07a-42d0-ac1a-c0e29735e73a;...", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentIdentifier": { "type": "string" }, "endUserIPAddress": { "type": "string" }, "entitlementIds": { "type": "array", "items": { "type": "string" } }, "giftToken": { "type": "string" }, "referrer": { "type": "string" }, "trustedReferrerToken": { "type": "string" } } } } } } } }, "/blaize/schema/users": { "get": { "responses": { "200": { "description": "OK. Returns a list of schema fields.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/blaize-schema-users-response" } } } }, "401": { "description": "Unauthorized. Returned if no valid authentication was provided.", "headers": {} } }, "summary": "Retrieve the user schema", "operationId": "retrieveUserSchema", "description": "Retrieves the user attribute schema for the tenant. This includes all fields configured in the admin console for the user schema.", "tags": [ "User" ] } }, "/zephr/public/gift-tokens/v1/gift-tokens": { "post": { "responses": { "201": { "description": "Created", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v4-gift-response" }, "examples": { "response": { "value": { "token": "absd-acsd34-casdae-1243c", "claimPath": "/my-path?gift=absd-acsd34-casdae-1243c" } } } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Create a gift V4", "operationId": "createV4Gift", "description": "Creates a gift (V4).", "tags": [ "V4 Gifts" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "The gift will be created for the provided path in the request body." } }, "required": [ "path" ], "example": { "path": "/my-path" } } } } } } }, "/blaize/datalayer": { "get": { "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "The response cache header max-age can be configured by support, and defaults to zero seconds." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "dataLayer": { "type": "array", "items": { "type": "object", "additionalProperties": { "description": "Resolved datalayer fields. Any fields that cannot be resolved will be present as fieldKey: null.\n", "title": "Resolved datalayer fields" } } } } }, "examples": { "Grouped-fields": { "value": { "dataLayer": [ { "zephrActivity": { "logged-in": true, "active-sessions": 1 } }, { "zephrUserSchema": { "user-attribute-1": "user-attribute-1-value" } }, { "zephrProducts": { "active-products": [ "active-product-1-id", "active-product-2-id" ] } }, { "zephrTestGroups": { "split-test-1": "split-test-1-group" } } ] } }, "Ungrouped-fields": { "value": { "dataLayer": [ { "logged-in": true }, { "active-sessions": 1 }, { "user-attribute-1": "user-attribute-1-value" }, { "active-products": [ "active-product-1-id", "active-product-2-id" ] }, { "split-test-1": "split-test-1-group" } ] } } } } } }, "401": { "description": "Unauthorized
Returned if no valid session was provided, either anonymous or authenticated.", "headers": {} } }, "summary": "Retrieve the datalayer", "operationId": "getDatalayer", "description": "Retrieves the Datalayer object for the current session. The datalayer can be used to provide contextual data when tracking user activity, for example providing values for 'User Attributes' in hotjar. The /blaize/profile endpoint is preferred for retrieving complete user profile information.
All fields configured in the admin console will be resolved against the current session and returned.
The top-level property in the response object defaults to 'dataLayer' and can be configured in the console under the data layer settings using the 'Data Layer Name' field.
Data layer fields can be grouped by their 'Entity' as configured in the console. An example of the possible groupings is included.", "tags": [ "Web Analytics" ] } }, "/zephr/public/rule-outcomes/v1/conversions": { "post": { "responses": { "201": { "description": "OK. The user conversion data has been successfully recorded.", "headers": {} }, "400": { "description": "Bad Request. Returned when the request is missing a blaize_tracking_id cookie.", "content": { "text/plain": { "schema": { "type": "string", "example": "Failed recording conversion for rule ID and outcome ID due to missing user tracking ID" } } }, "headers": {} } }, "summary": "Submit user conversion data", "operationId": "submitUserConversionData", "description": "Records a user conversion. In Zephr, a conversion typically represents a user state change, such as transitioning from anonymous to registered or becoming a paying customer. This endpoint can also be used to record any event, like a user clicking on an advert. Conversions are tracked against specific rule versions and outcomes, enabling performance comparison between different outcomes.
Recording this data enables the comparison of performance of different outcomes in a rule. For example, a split test could be set up with two slightly different 'advert' outcomes that each record a conversion when a user interacts with them. After traffic has been processed by the rule, the conversion rates between the two outcomes can be compared in 'analytics' mode in the console. For example, it might show that 5% of users who saw Outcome1 clicked a button, compared to 8% for Outcome2. This analytics data can be downloaded in CSV format for further analysis.
Conversion data is only used to evaluate the performance of outcomes in rules and cannot be accessed on a per-user basis. To track if a particular registered user has interacted with an outcome, update a user attribute value.
This endpoint is only relevant where the Zephr in-rule analytics feature is enabled.
This endpoint must be called with a populated blaize_tracking_id cookie.\n If this cookie is missing, a 400 response code is returned.", "parameters": [ { "in": "cookie", "name": "blaize_tracking_id", "required": true, "example": "dc8f7f9e-2deb-4485-a9f0-34b44fc7f45e", "description": "Zephr tracking ID cookie used to uniquely identify the user or anonymous session", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/conversion-request" } } } }, "tags": [ "Web Analytics" ] } }, "/zephr/features": { "get": { "responses": { "200": { "description": "OK. The response will be an array of features.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zephr-features-response-array" }, "examples": { "COMMENT_TAG": { "value": [ { "id": "feature-live", "targetType": "COMMENT_TAG", "label": "feature-label", "slug": "feature-slug" } ] }, "CSS_SELECTOR": { "value": [ { "id": "feature-live", "targetType": "CSS_SELECTOR", "label": "feature-label", "slug": "feature-slug", "cssSelector": ".feature-css-selector" } ] } } } } } }, "summary": "Retrieve the Zephr Feature", "operationId": "retrieveZephrFeature", "description": "Retrieves the Zephr browser features by default, or optionally with query parameter ?ruleType returns the given type, they can be HTML, browser, JSON, SDK.", "tags": [ "Zephr Features" ], "parameters": [ { "name": "ruleType", "in": "query", "description": "Type of the feature rule", "required": false, "schema": { "type": "string", "enum": [ "browser", "html", "json", "sdk" ] } } ] } }, "/zephr/public/component-library/v1/library-components/{componentId}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "" } } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Retrieve the Component Library", "operationId": "retrieveComponentLibrary", "description": "Components configured in the component library can be retrieved as rendered HTML. The componentId passed in the path can be versioned to reference a specific version of a library component. For example, ‘payment-form:1’, ‘payment-form:4’ or ‘payment-form:active’ to reference the default version of the component.\n", "tags": [ "Component Library" ], "parameters": [ { "name": "componentId", "in": "path", "description": "The versioned slug of the component in the library to render, as configured in the console.", "example": "my-component:1", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/public/template-components/v1/template-components/{templateConfigId}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "" } } } } }, "400": { "description": "Bad Request", "headers": {} } }, "summary": "Retrieve the Template Components", "operationId": "retrieveTemplateComponents", "description": "Template components can be retrieved as rendered HTML. This endpoint is intended to be consumed by callers processing the output of an SDK TRANSFORMATION rule, where templateConfigId will identify a particular instance of a template component being used in an outcome with variables specified.\n", "tags": [ "Component Library" ], "parameters": [ { "name": "templateConfigId", "in": "path", "description": "templateConfigId", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/public/ui-components/v1/ui-components/{componentId}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "" } } } } }, "400": { "description": "Bad Request", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Retrieve the UI Components", "operationId": "retrieveUIComponents", "description": "UI components can be retrieved as rendered HTML. This endpoint is intended to be consumed by callers processing the output of an SDK TRANSFORMATION rule, where componentId will reference a form or custom component created within an outcome of a rule.\n", "tags": [ "Component Library" ], "parameters": [ { "name": "componentId", "in": "path", "description": "componentId", "required": true, "schema": { "type": "string" } }, { "name": "ui component variable", "in": "query", "required": false, "description": "parameters can optionally be included and will be rendered where the matching param name exists in the UI component", "schema": { "type": "string" }, "example": "?myVar=test&otherVar=something" } ] } }, "/zephr/users/reset": { "post": { "responses": { "201": { "description": "Created. The user will be sent an email with a TOKEN template variable matching the pattern [0-9]{6} to be used to reset their password.", "headers": {} }, "400": { "description": "Bad Request", "headers": {} }, "404": { "description": "Not Found", "headers": {} } }, "summary": "Start a 2FA password reset", "operationId": "startPasswordReset", "description": "Starts the password reset for a 2FA user. This will send an email to the user with a 6 digit code, which can then be used to reset their password.\n", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-2fa-password-reset" } } } } } }, "/blaize/browser-fingerprint": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "" } } } } } }, "summary": "Fingerprint", "operationId": "browserFingerprint", "description": "Returns an HTML page that fingerprints the user's browser, sends the fingerprint data to POST /blaize/anonymous-session,\nand then redirects the user to a specified path provided as a query parameter (defaulting to '/').\n", "tags": [ "User" ], "parameters": [ { "name": "redirect", "in": "query", "description": "TODO", "required": false, "schema": { "type": "string", "default": "/", "description": "Defines the destination path after the fingerprint is sent to /POST /blaize/anonymous-session." } } ] } }, "/blaize/users/update-email-passwordless/{state}": { "post": { "responses": { "201": { "description": "An email with instructions to update your email has been sent to the new email address.", "headers": {} } }, "summary": "Start the email update flow for a passwordless user", "operationId": "startUpdateEmailPasswordless", "description": "Starts the email update flow for a passwordless user. An email will be sent to the new email address for verification.", "tags": [ "User" ], "parameters": [ { "name": "state", "in": "path", "required": true, "schema": { "type": "string" }, "description": "An identifier linking this request to a previous one, that set the new email address." } ] } }, "/zephr/subscriptions/{externalId}": { "delete": { "responses": { "200": { "description": "OK - Subscription has been cancelled successfully", "headers": {} }, "403": { "description": "Forbidden - Invalid subscription provided", "headers": {} }, "409": { "description": "Conflict - This subscription had already been cancelled", "headers": {} } }, "summary": "Cancel a subscription", "operationId": "cancelSubscription", "description": "It cancels the logged in user's subscription with the provided external identifier (`extenalId`). A logged in session is required for this operation.\n", "tags": [ "Subscription" ], "parameters": [ { "name": "externalId", "in": "path", "description": "The external identifier of the subscription", "required": true, "schema": { "type": "string", "example": "mySubscription1" } } ] } }, "/zephr/public/forms/v1/forms/{formId}": { "get": { "summary": "Retrieve a form by ID", "operationId": "getForm", "description": "Retrieves a form by ID and returns an HTML page that renders it.", "tags": [ "Component Library" ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "outcomeId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Used to render the form" }, { "name": "ruleId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Used to render the form" } ], "responses": { "200": { "description": "OK", "headers": {} }, "400": { "description": "Bad Request", "headers": {} } } } }, "/zephr/public/internal-templates/v1/internal-templates/{internalTemplateUsageId}": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "
Some HTML
" } } } } }, "400": { "description": "Bad Request", "headers": {} }, "403": { "description": "Forbidden", "headers": {} }, "404": { "description": "Form not found", "headers": {} } }, "summary": "List custom components", "operationId": "retrieveCustomComponents", "description": "Custom components can be retrieved as rendered HTML. This endpoint is intended to be consumed by callers processing the output of an SDK TRANSFORMATION rule, where internalTemplateUsageId will identify a particular instance of a custom component being used in an outcome with variables specified. The variables used by the custom component can be passed in as query parameters with the request which will override the values provided in the rule.\n", "tags": [ "Component Library" ], "parameters": [ { "name": "internalTemplateUsageId", "in": "path", "description": "The internal template usage ID.", "required": true, "schema": { "type": "string" } } ] } }, "/zephr/users/change-password": { "post": { "responses": { "200": { "description": "OK - The process of changing the user's password was started successfully", "headers": {} }, "400": { "description": "Bad Request - Wrong validators have been supplied with this request", "headers": {} }, "404": { "description": "Not Found - User was not found", "headers": {} } }, "summary": "Change the user's password", "operationId": "changeZephrUserPassword", "description": "This endpoint starts the process of changing a user's password. An active user session is required for this endpoint. This process ends with an OTP (One-time password) being sent to the user's email address.", "tags": [ "Authentication" ], "requestBody": { "$ref": "#/components/requestBodies/Change_Password_Body" } } }, "/blaize/two-factor-authentication": { "post": { "summary": "Start two factor authentication process", "operationId": "start2FA", "description": "Starts the two factor authentication process. An email will be sent to the email address provided in the request with a link to complete the process.", "tags": [ "User" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartTwoFactorAuthenticationRequest" } } } }, "responses": { "201": { "description": "OK", "headers": {} }, "404": { "description": "User not found", "headers": {} }, "405": { "description": "Two factor authentication is not active", "headers": {} } } } }, "/zephr/recognise-me": { "post": { "summary": "Recognise the user as a previously logged-in user", "operationId": "recogniseUser", "description": "Recognises the user as a previously logged-in user. Users can be fingerprinted on login\nbased on their email address, their user agent and their IP address. This endpoint can then be used\nwith the same parameters to give users a limited access to their logged-in experience. This is an opt-in feature.\n", "tags": [ "User" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "identifiers": { "type": "object", "properties": { "email_address": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "The lookup was performed successfully. If the user was recognised, a Set-Cookie header will be returned.", "headers": {} } } } }, "/zephr/users/change-password/{otp}": { "get": { "summary": "Complete the change password flow", "operationId": "changeCompletePasswordFlow", "description": "Complete the change password flow. This endpoint changes the password to the one submitted previously in another request. The otp in this request is used to match this request with the previous one that started the flow and submitted the new password.", "tags": [ "User" ], "parameters": [ { "name": "otp", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": {} }, "404": { "description": "User not found", "headers": {} } } } }, "/zephr/oauth2/error": { "get": { "summary": "Get the OAuth2 error page", "operationId": "getOAuth2ErrorPage", "description": "Gets the OAuth2 error page.", "tags": [ "Third-Party Authentication" ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "text/html": { "examples": { "response": { "value": "" } } } } } } } } }, "components": { "securitySchemes": { "CookieBlaizeSession": { "description": "This cookie is the default authentication mechanism and is set after a successful request to an endpoint such as `/blaize/login`. Such a cookie may also be obtained via other means, such as a social sign-in flow. Most endpoints in this API are sensitive to this cookie and will behave differently depending on the presence and value thereof. Some endpoints will only function for authenticated users, so this cookie or other form of authentication will be required in that case.", "type": "apiKey", "in": "cookie", "name": "blaize_session" }, "JwtQuery": { "description": "A JWT can be provided in a `jwt` request query parameter to Zephr. Zephr can use various forms of JWT to authenticate users. For details on this see: https://knowledgecenter.zuora.com/Zephr/Settings/JSON_Web_Tokens_(JWT)", "type": "apiKey", "in": "query", "name": "jwt" }, "JwtHeaderXBlaizeJwt": { "description": "A JWT can be provided in a `x-blaize-jwt` request header to Zephr. Zephr can use various forms of JWT to authenticate users. For details on this see: https://knowledgecenter.zuora.com/Zephr/Settings/JSON_Web_Tokens_(JWT)", "type": "apiKey", "in": "header", "name": "x-blaize-jwt" }, "JwtHeaderXZephrJwt": { "description": "A JWT can be provided in a `x-zephr-jwt` request header to Zephr. Zephr can use various forms of JWT to authenticate users. For details on this see: https://knowledgecenter.zuora.com/Zephr/Settings/JSON_Web_Tokens_(JWT)", "type": "apiKey", "in": "header", "name": "x-zephr-jwt" }, "JwtBearer": { "description": "A JWT can be provided as an HTTP bearer token in a request to Zephr. Zephr can use various forms of JWT to authenticate users. For details on this see: https://knowledgecenter.zuora.com/Zephr/Settings/JSON_Web_Tokens_(JWT)", "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "JwtCookie": { "description": "A JWT can be provided as a `blaize_jwt` cookie in a request to Zephr. Zephr can use various forms of JWT to authenticate users. For details on this see: https://knowledgecenter.zuora.com/Zephr/Settings/JSON_Web_Tokens_(JWT)", "type": "apiKey", "in": "cookie", "name": "blaize_jwt" } }, "requestBodies": { "Complete_password_resetBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "validators": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string" } } } }, "required": [ "validators" ], "example": { "validators": { "password": "mysecurepassword123" } } } } } }, "user-2fa-password-reset-complete": { "content": { "application/json": { "schema": { "type": "object", "properties": { "identifiers": { "type": "object", "properties": { "email_address": { "type": "string" } } }, "validators": { "type": "object", "properties": { "password": { "type": "string" } } } }, "required": [ "identifiers" ], "example": { "identifiers": { "email_address": "joe.blow@company.com" }, "validators": { "password": "mynewsecurepassword123" } } } } } }, "Change_Password_Body": { "content": { "application/json": { "schema": { "type": "object", "properties": { "current_validators": { "type": "object", "properties": { "password": { "type": "string" } } }, "new_validators": { "type": "object", "properties": { "password": { "type": "string" } } } }, "required": [ "current_validators", "new_validators" ], "example": { "current_validators": { "password": "mysecurepassword123" }, "new_validators": { "password": "mysecurepassword123" } } } } } }, "Save_ProfileBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "surname": { "type": "string" } }, "example": { "first_name": "Joe", "surname": "Blow" } } } } } }, "schemas": { "user-2fa-password-reset": { "type": "object", "example": { "identifiers": { "email_address": "joe.blow@company.com" } }, "properties": { "identifiers": { "type": "object", "required": [ "email_address" ], "properties": { "email_address": { "type": "string" } } } } }, "oauth2": { "type": "object", "properties": { "identifiers": { "type": "object", "properties": { "email_address": { "type": "string" }, "password": { "type": "string" } } } }, "required": [ "identifiers" ], "example": { "identifiers": { "email_address": "joe.blow@company.com", "password": "supersecret123!" } } }, "user-login-response": { "type": "object", "properties": { "cookie": { "type": "string", "description": "The authenticated user session.", "example": "blaize_session=443ed68f-0b44-4f32-8443-553d584cb0dd; Expires=Fri, 16 Nov 2018 12:35:56 GMT; Path=/;" }, "message": { "type": "string", "example": "Login successful" }, "tracking_id": { "type": "string", "description": "The user tracking ID.", "example": "4fac49a6-e423-4ac1-b0ad-d678979344422" } } }, "user-registration-request": { "type": "object", "properties": { "identifiers": { "type": "object", "properties": { "email_address": { "type": "string" } } }, "validators": { "type": "object", "properties": { "password": { "type": "string" }, "use_sso": { "type": "boolean", "description": "When this is present there should be no identifiers in the body. The user is identified through a blaize_session cookie." } } } }, "required": [ "identifiers", "validators" ], "example": { "identifiers": { "email_address": "abc@company.com" }, "validators": { "password": "securepassword@123" } } }, "user-registration-response": { "type": "object", "properties": { "cookie": { "type": "string", "example": "blaize_session=0123456789ABCD; Expires=Fri, 16 Nov 2018 12:35:56 GMT; Path=/;" }, "message": { "type": "string", "example": "Registration successful" }, "tracking_id": { "type": "string", "example": "TT0123456789ABCD" } } }, "admin-user-logout-request": { "type": "object", "properties": { "where": { "type": "string", "description": "An enum of describing which sessions/devices to log out of.\n\nOptions are `JUST_HERE`, `THIS_DEVICE`, `OTHER_DEVICES`, `EVERYWHERE`.\nThese options are only valid when Single Sign-On is configured.\nWhen SSO is configured as `autoLogin`, then the default behaviour is `THIS_DEVICE`.\nWhen SSO is configured as `optIn`, then the default behaviour is `JUST_HERE`.\n`JUST_HERE` is not a valid option when SSO is configured as `autoLogin`." } }, "example": { "where": "EVERYWHERE" } }, "admin-user-logout-response": { "type": "object", "properties": { "message": { "type": "string", "example": "Session deleted" } } }, "RetrieveStatusResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "example": "authenticated", "description": "The SSO status of the current user session. This can be:\n\n- `unknown`: The SSO token is not authenticated anywhere, or the current session is not associated with an SSO token.\n\n- `known`: The current session is anonymous, but the SSO token is authenticated on another site.\n\n- `authenticated`: The current session is authenticated through an SSO token." }, "meta": { "oneOf": [ { "$ref": "#/components/schemas/customer-meta" }, { "nullable": true, "type": "string" } ] } } }, "customer-meta": { "type": "object", "properties": {} }, "conversion-request": { "example": { "ruleId": "article-22", "outcomeId": "graph/1#1,graph/1#2,graph/1#3,graph/2#1,graph/2#2", "conversion": "REGISTERED" }, "properties": { "ruleId": { "type": "string", "description": "The ID of the specific Zephr rule version that led to the outcome causing this conversion." }, "outcomeId": { "type": "string", "description": "The ID of the outcome in the rule that triggered this conversion." }, "conversion": { "type": "string", "description": "The type of conversion to be recorded. For example, Zephr out-of-the-box components will submit conversion strings 'REGISTERED' and 'CUSTOMER' when registering a user or when a user purchases a product. Any string can be used for custom conversions." } }, "required": [ "conversion", "outcomeId", "ruleId" ], "type": "object" }, "passwordless-authentication-request": { "type": "object", "required": [ "identifiers", "action" ], "properties": { "identifiers": { "$ref": "#/components/schemas/identifiers" }, "action": { "type": "string", "enum": [ "login", "register", "completeRegistration" ] }, "redirect": { "type": "string", "description": "Either a relative path to the current site or a full URL for another site in the current tenant." } } }, "password-reset-request": { "type": "object", "properties": { "identifiers": { "$ref": "#/components/schemas/identifiers" } }, "required": [ "identifiers" ] }, "cdn-anonymous-session-response": { "type": "object", "properties": { "message": { "type": "string", "example": "Anonymous session created successfully" }, "tracking_id": { "type": "string" } } }, "start-update-your-current-email-address-request": { "type": "object", "properties": { "new_identifiers": { "type": "object", "properties": { "email_address": { "type": "string" } } } }, "required": [ "new_identifiers" ], "example": { "new_identifiers": { "email_address": "joe.blow@company.com" } } }, "start-update-your-current-zephr-email-address-request": { "type": "object", "properties": { "current_identifiers": { "$ref": "#/components/schemas/identifiers" }, "new_identifiers": { "$ref": "#/components/schemas/identifiers" }, "validators": { "$ref": "#/components/schemas/validators" } }, "required": [ "current_identifiers", "new_identifiers", "validators" ], "example": { "current_identifiers": { "email_address": "john.doe@company.com" }, "new_identifiers": { "email_address": "doe.john@company.com" }, "validators": { "password": "mysecurepassword123" } } }, "complete-update-your-current-zephr-email-address-request": { "type": "object", "properties": { "current_identifiers": { "$ref": "#/components/schemas/identifiers" }, "validators": { "$ref": "#/components/schemas/validators" } }, "required": [ "current_identifiers", "validators" ], "example": { "current_identifiers": { "email_address": "john.doe@company.com" }, "validators": { "password": "mysecurepassword123" } } }, "identifiers": { "type": "object", "properties": { "email_address": { "type": "string", "example": "joe.blow@company.com" } } }, "delivery": { "type": "object", "properties": { "method": { "type": "string", "example": "email" }, "destination": { "type": "string", "example": "joe.blow@company.com" }, "action": { "type": "string", "example": "login" }, "redirect": { "type": "string", "example": "/" } } }, "braintree-subscription-product": { "type": "object", "properties": { "tenantId": { "type": "string", "example": "your-tenant|site-slug", "description": "Zephr tenant ID and site slug" }, "subTenantId": { "type": "string", "example": "your-tenant|site-slug", "description": "Zephr subtenant ID and site slug" }, "id": { "type": "string", "example": "one-month-one-off", "description": "Zephr product ID" }, "label": { "type": "string", "example": "One month access", "description": "Zephr product label" }, "description": { "type": "string", "example": "One month access", "description": "Description of Zephr product" }, "entitlement": { "type": "object", "properties": { "id": { "type": "string", "example": "191f6d00-b8d4-46f1-a22d-2bf53f4f8fa3", "description": "Zephr product entitlement ID" }, "type": { "type": "string", "example": "bundle", "description": "Zephr product entitlement type" } } }, "mapping": { "type": "object", "properties": { "recurring": { "type": "object", "properties": { "plans": { "type": "array", "description": "Recurring plans assigned to this product", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "archived": { "type": "boolean" }, "billingCycles": { "type": "number", "description": "Number of billing cycles for this plan, `null` if none defined" }, "paymentProvider": { "type": "string", "description": "Payment provider name in lowercase", "example": "braintree" } } } }, "multiPhasedPlans": { "type": "array", "description": "Multi-phased plans are not supported in Braintree, this will be `null`", "default": null, "items": { "type": "object" } } } }, "oneOff": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "description": "always `null`" }, "archived": { "type": "boolean" }, "billingCycles": { "type": "number", "description": "always `null`" }, "paymentProvider": { "type": "string", "description": "Payment provider name in lowercase", "example": "braintree" }, "accessDuration": { "type": "object", "properties": { "duration": { "type": "number", "description": "Number of months this plan provides", "example": 2 }, "unit": { "type": "string", "description": "always 'MONTHS'", "example": "MONTHS" } } } } } } } }, "jwt": { "type": "object", "properties": { "claim_value": { "type": "string" } } } } }, "sharingLimit": { "type": "number", "description": "The number of users this product can be shared with. Users can share the product multiple times by canceling previous shares. A value of `0` indicates that the product is not shareable.", "example": 0 } } }, "payment_method": { "type": "object", "required": [ "token", "default", "nonce", "type" ], "properties": { "token": { "type": "string", "example": "8m2kc5g", "description": "The token identifier for this payment method." }, "default": { "type": "boolean", "description": "If this the default payment method for this user." }, "card_type": { "type": "string", "example": "Visa", "description": "In the case of a card payment method, the type of the card." }, "card_holder_name": { "type": "string", "example": "John Rambo", "description": "In the case of a credit card payment method, the name of the card holder." }, "card_number_masked": { "type": "string", "example": "654321******0987", "description": "In the case of a card payment method, the masked card number, compliant with PCI security standards." }, "expiration_date": { "type": "string", "example": "07/22", "description": "In the case of a card payment method, the expiration date, in the format of MM/YY or MM/YYYY." }, "expired": { "type": "boolean", "description": "In the case of a card payment method, if the card has expired." }, "expiring_soon": { "type": "boolean", "description": "In the case of a card payment method, if the card will expire within the configured number of days." }, "in_use": { "type": "boolean", "description": "Indicates if this payment method is used by any subscriptions that have not been finalised and would be cancelled if this payment method is deleted." }, "last_4": { "type": "string", "example": "1111", "description": "In the case of a card payment method, the last four digits of the card number." }, "nonce": { "type": "string", "example": "086128f3-04c2-069e-78d2-3f4de98508e5", "description": "A nonce that can be used for other payment method operations." }, "type": { "type": "string", "example": "CreditCard", "description": "The payment method type." }, "zipcode": { "type": "string", "example": "123456", "description": "In the case of a card payment method, the zip code associated with the card." } } }, "payment_methods": { "type": "array", "items": { "$ref": "#/components/schemas/payment_method" } }, "payment_plan": { "type": "object", "required": [ "id", "name", "currency_code", "base_price", "billing_interval_unit", "billing_interval", "billing_cycles", "zephr_product_id" ], "properties": { "id": { "type": "string", "example": "annual-plan", "description": "The identifier for this payment plan." }, "name": { "type": "string", "example": "Sports+ Membership Annual", "description": "The name of this payment plan." }, "currency_code": { "type": "string", "example": "USD", "description": "The ISO 4217 currency code for the transaction." }, "base_price": { "type": "number", "example": 10.2, "description": "The price of this plan, without any discounts applied." }, "billing_interval_unit": { "type": "string", "example": "MONTH", "description": "The time measurement unit for billing interval." }, "billing_interval": { "type": "number", "example": 3, "description": "How many time units lapse between billing events." }, "billing_cycles": { "type": "number", "example": 12, "description": "How many times billing will occur." }, "trial_duration_unit": { "type": "string", "example": "DAY", "description": "The time measurement unit for trial duration. This will always be present if `trial_duration` is set." }, "trial_duration": { "type": "number", "example": 30, "description": "How long the trial period lasts." }, "discounts": { "type": "array", "items": {}, "description": "Any discounts that may apply to this plan." }, "zephr_product_id": { "type": "string", "example": "product-123", "description": "The Zephr product ID associated with this plan." } } }, "add-ons": { "type": "array", "items": { "$ref": "#/components/schemas/add-on" } }, "add-on": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "paymentOptions": { "type": "array", "items": { "$ref": "#/components/schemas/add-on-payment-options" } } } }, "add-on-payment-options": { "type": "object", "properties": { "slug": { "type": "string", "example": "plan-123", "description": "The plan slug with which this add-on is associated." }, "currency": { "type": "string", "example": "$", "description": "The currency symbol." }, "addonPrice": { "type": "number", "example": 12.34 } } }, "promo-code-payment-options": { "type": "object", "properties": { "slug": { "type": "string", "example": "plan-123", "description": "The plan slug with which this promo code is associated." }, "currency": { "type": "string", "example": "$", "description": "The currency symbol." }, "pricePointId": { "type": "string", "example": "cost-123" }, "originalPrice": { "type": "number", "example": 3.45 }, "discountPrice": { "type": "number", "example": 2 } } }, "browser-features-response": { "type": "object", "properties": { "featureResults": { "type": "object", "properties": { "featureX": { "type": "string", "example": "blaize.transform.resource('...')", "description": "Feature result transformations" } }, "description": "Map of HTML Feature IDs and feature result transformations." }, "resources": { "type": "object", "properties": { "forms": { "type": "object", "properties": {}, "description": "Forms used in feature results." }, "paymentForms": { "type": "object", "properties": {}, "description": "Payment Forms used in feature results." }, "uiComponents": { "type": "object", "additionalProperties": { "type": "string", "description": "UI Components used in feature results." }, "example": "

Example

" }, "hostedUiComponents": { "type": "object", "properties": {}, "description": "Hosted UI Components used in feature results." }, "componentTemplates": { "type": "object", "properties": {}, "description": "Component Templates used in feature results." } }, "description": "Map of transformation resources" }, "accessDetails": { "type": "object", "properties": { "authenticated": { "type": "boolean", "description": "Is the session authenticated" }, "accessDecisions": { "type": "object", "additionalProperties": { "type": "boolean", "description": "Map of access decisions for this feature" } }, "entitlements": { "$ref": "#/components/schemas/access-details-usage-ent", "description": "Map of entitlement usage" }, "credits": { "$ref": "#/components/schemas/access-details-usage", "description": "Map of credit usage" }, "meters": { "$ref": "#/components/schemas/access-details-usage" }, "trialTrackingDetails": { "type": "array", "items": {}, "description": "Array of trial tracking details" }, "trials": { "$ref": "#/components/schemas/access-details-trial" }, "timeTrials": { "$ref": "#/components/schemas/access-details-time-trial" }, "testGroups": { "type": "object", "additionalProperties": { "description": "Map of split test ID and group ID." } }, "activeProducts": { "type": "array", "items": { "type": "string" }, "description": "Array of user's active products" } }, "description": "Feature access details" } } }, "browser-features-transformations-response": { "type": "object", "properties": { "featureResults": { "type": "object", "properties": { "featureX": { "type": "object", "properties": { "ruleTransformations": { "type": "object", "properties": { "type": { "type": "string", "description": "The transformation type." }, "id": { "type": "string", "description": "The rule ID." }, "contentLength": { "type": "number", "description": "Content length" }, "outcomeId": { "type": "string", "description": "The outcome ID." }, "outcomeLabel": { "type": "string", "description": "The outcome label." }, "ruleId": { "type": "string", "description": "The rule ID." }, "ruleLabel": { "type": "string", "description": "The rule label." }, "style": { "type": "string", "description": "The transformation style." }, "url": { "type": "string", "description": "The transformation URL." }, "value": { "type": "string", "description": "The string transformation value." } } }, "zoneRuleTransformations": { "type": "object", "properties": { "zone": { "type": "string", "description": "The zone type (HEADER, FOOTER, POPUP)." }, "closeable": { "type": "boolean", "description": "Indicates whether the zone can be closed." }, "css": { "type": "string", "description": "CSS" }, "displayAfter": { "type": "string", "description": "Specifies whether the content should be displayed after a specific condition or event." }, "scrollable": { "type": "boolean", "description": "Indicates whether the zone is scrollable." }, "ruleTransformations": { "type": "array", "items": {}, "description": "Rule transformations" } } } } } }, "description": "Map of HTML Feature IDs and feature result transformations" }, "resources": { "type": "object", "properties": { "forms": { "type": "object", "properties": {}, "description": "Forms used in feature results" }, "paymentForms": { "type": "object", "properties": {}, "description": "Payment Forms used in feature results" }, "uiComponents": { "type": "object", "properties": {}, "description": "UI Components used in feature results" } } } } }, "access-details-usage-ent": { "description": "Map of meter usage", "type": "object", "properties": { "usedInDecision": { "type": "boolean" }, "decrementedInDecision": { "type": "boolean" } } }, "access-details-usage": { "allOf": [ { "$ref": "#/components/schemas/access-details-usage-ent" }, { "type": "object", "properties": { "totalCredits": { "type": "number" }, "remainingCredits": { "type": "number" } } } ] }, "access-details-trial": { "description": "Map of trial usage", "type": "object", "properties": { "totalCredits": { "type": "number" }, "remainingCredits": { "type": "number" }, "tracker": { "type": "string" }, "reportInDataLayer": { "type": "boolean" }, "dataLayerCreditsUsedKey": { "type": "string" }, "dataLayerCreditsRemainingKey": { "type": "string" }, "decrementedInDecision": { "type": "boolean" }, "usedInDecision": { "type": "boolean" } } }, "access-details-time-trial": { "description": "Map of time trial usage", "type": "object", "properties": { "reportInDataLayer": { "type": "boolean" }, "trialDurationUnits": { "type": "string" }, "trialDuration": { "type": "number" }, "entryTime": { "type": "string" }, "trackerHits": { "type": "number" }, "timeRemainingInTrial": { "type": "number" }, "dataLayerTrialDurationKey": { "type": "string" }, "dataLayerTrialDurationUnitsKey": { "type": "string" }, "dataLayerTrackerEntryTimeKey": { "type": "string" }, "dataLayerTrackerHitsKey": { "type": "string" }, "dataLayerTrialTimeRemainingKey": { "type": "string" }, "activeInDecision": { "type": "boolean" } } }, "access-decision-response": { "type": "object", "properties": { "status": { "type": "string", "example": "301" }, "body": { "type": "string", "example": "Redirecting to login page..." }, "Location": { "type": "string", "example": "/login.html" } } }, "dynamic-offer-decision-response": { "type": "object", "description": "The dynamic offer decision outcomes. Product rule output will be under the products array. Price rule output will be under each product based on where its rate plan is associated with. Discount output will be under each charge based on the discount rule condition. Any custom property rule output will be under the custom object. If you have in rule analytics enabled, there will be an outcome object returned as part of the response.", "properties": { "products": { "type": "array", "description": "The processed output for mainly the Product rule. Price and Discount, if present, the output of those would be nested under each product element according to the rule specification.", "items": { "$ref": "#/components/schemas/do-product-response" } }, "tagline": { "type": "string", "description": "The tagline rule output" }, "custom": { "type": "object", "description": "key value pair of any custom property rule output. The key would be the property id, the value would be its rule output", "properties": {} }, "outcomes": { "type": "array", "description": "The rule outcome for each property rule within the offer. If you wish to record user conversion data, you would need to send these outcome data back to Zephr upon when the conversion is happening.", "items": { "type": "object", "properties": { "ruleId": { "type": "string", "description": "An identifier for the property rule" }, "outcomeId": { "type": "string", "description": "An identifier for the outcome of this property rule execution" } } } }, "errors": { "type": "array", "items": { "properties": { "property": { "type": "string", "description": "The offer property id in which the rule failed to execute" }, "error": { "type": "string", "description": "The error message explaining why this decision failed to resolve. Present only if there was an error." } } } } } }, "do-product-response": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/do-product-feature-response" } }, "sharingLimit": { "type": "number" }, "metadata": { "type": "object", "properties": { "order": { "type": "number" }, "recommended": { "type": "boolean" } } }, "paymentPlans": { "type": "array", "items": { "$ref": "#/components/schemas/do-product-price-response" } }, "attributes": { "type": "object", "description": "Product Attributes you've defined in the Product catalog and application overrides that you've specified in the Product rule." } } }, "do-product-feature-response": { "type": "object", "description": "The Feature defined in Zephr when configuring the product in Zephr's catalog", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" } } }, "do-product-price-response": { "type": "object", "description": "The price response for each returned product, it will contain data for each product's associated rate plans and their underlying charges", "properties": { "planId": { "type": "string" }, "planData": { "type": "object", "description": "Any addition fields on the product rate plan level", "properties": {} }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/do-product-price-charge-response" } } } }, "do-product-price-charge-response": { "type": "object", "description": "The charge response for each rate plan returned, it will contain processed price book items under each charge and any discount available according to the output and the condition defined in the Dynamic Offer's discount rule.", "properties": { "chargeId": { "type": "string" }, "prices": { "type": "array", "description": "The prices associated with this charge, filtered/sorted according to the price rule of the Dynamic Offer", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "price": { "type": "number" } } } }, "chargeDefinitionData": { "type": "object", "description": "Any addition fields on the product charge definition level", "properties": {} }, "chargeData": { "type": "object", "description": "Any addition fields on the product rate plan charge level", "properties": {} }, "discounts": { "type": "array", "description": "The discounts associated with this charge, according to the discount rule output of this Dynamic Offer.", "items": { "$ref": "#/components/schemas/do-product-price-charge-discount-response" } } } }, "do-product-price-charge-discount-response": { "type": "object", "description": "The discount output", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/do-product-price-charge-discount-item-response" } }, "orderType": { "type": "string", "description": "Specify how multiple discounts, if there is any, should be applied together", "enum": [ "SEQUENTIAL", "STACKED" ] } } }, "do-product-price-charge-discount-item-response": { "type": "object", "properties": { "order": { "type": "number", "description": "The order with defines the priority of this discount" }, "type": { "type": "string", "description": "The type of the discount", "enum": [ "FIXED", "PERCENTAGE", "OVERRIDE" ] }, "value": { "type": "number" }, "occurrence": { "type": "string", "description": "The frequency this discount occurs, if it's recurring then an end policy is expected to be present", "enum": [ "ONE_OFF", "RECURRING" ] }, "startPolicy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ON_CHARGE_START", "AFTER_CHARGE_START" ] }, "offset": { "type": "object", "format": "nullable", "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "CHARGE_BILLING_PERIOD", "DAY", "WEEK", "MONTH", "YEAR" ] } } } } }, "endPolicy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ON_CHARGE_START", "ON_CHARGE_END", "AFTER_CHARGE_START", "AFTER_DISCOUNT_START" ] }, "offset": { "type": "object", "format": "nullable", "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "CHARGE_BILLING_PERIOD", "DAY", "WEEK", "MONTH", "YEAR" ] } } } } }, "attributes": { "type": "object", "description": "Discount Attributes you've defined in the Discount output within the Discount rule." } } }, "oauth-state-response": { "type": "object", "properties": { "message": { "type": "string", "example": "State initialized" } } }, "oauth2-token-response": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Oauth2 access token" }, "token_type": { "type": "string" }, "expires_in": { "type": "number", "description": "Oauth2 token expiry time in seconds" }, "refresh_token": { "type": "string", "description": "Oauth2 refresh token to reuest a new Oauth2 token" }, "user_id": { "type": "string", "description": "Authenticated user ID" } } }, "oauth2-request-body": { "type": "object", "properties": { "client_id": { "type": "string", "description": "Zephr Site Oauth2 Client ID" }, "response_type": { "type": "string", "description": "Must be set to `code`" }, "redirect_uri": { "type": "string", "description": "Client's redirection endpoint. Must be an absolute URI" }, "scope": { "type": "string", "description": "The scope of the access request. Supported scopes: user.account:read, user.profile:read and user.profile:update" }, "state": { "type": "string", "description": "An opaque value used by the client to maintain state between the request and callback" }, "allow": { "type": "boolean", "description": "Resource owner consent" } }, "required": [ "client_id", "response_type", "redirect_uri", "scope", "state", "allow" ], "example": { "client_id": "1234567890", "response_type": "code", "redirect_uri": "https://someUrl.com/callback", "scope": "user.account:read user.profile:read", "state": "abcdefghijklmnopqrstuvwsyz", "allow": true } }, "owned_products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the product that is shared" }, "product_label": { "type": "string", "description": "The label of the product that is shared" }, "sharing_limit": { "type": "number", "description": "The maximum number of users that this product can be shared with by the owner" }, "shares": { "type": "object", "properties": { "member_email": { "type": "string", "description": "The email of the user that this product is shared with. This will be null if this product share has not yet been accepted" }, "sharing_id": { "type": "string", "description": "The ID of the user product share" }, "status": { "type": "string", "description": "The status of the user product share. One of 'active', 'inactive', 'pending'" }, "created_at": { "type": "string", "description": "ISO-8601 formatted time at which the share was created." } } } } } }, "member_products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the product that is shared." }, "product_label": { "type": "string", "description": "The label of the product that is shared." }, "sharing_id": { "type": "string", "description": "The ID of the user product share." }, "status": { "type": "string", "description": "The status of the user product share. One of 'active', 'inactive', 'pending'." }, "shared_by_email": { "type": "string", "description": "The email of the product owner." }, "created_at": { "type": "string", "description": "ISO-8601 formatted time at which the share was created." }, "meta_data": { "type": "object", "properties": {}, "description": "Any metadata configured for the user product share, defined at the point of creation." } } } }, "product_sharing_response": { "type": "object", "properties": { "member_products": { "$ref": "#/components/schemas/member_products" }, "owned_products": { "$ref": "#/components/schemas/owned_products" } } }, "feature-decisions-response": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/feature-decision-response" }, "description": "List of feature decision outcomes. These will be ordered as provided in the request." } } }, "feature-decision-response": { "type": "object", "required": [ "sdkFeatureSlug" ], "properties": { "sdkFeatureSlug": { "type": "string", "example": "sdk-feature-1", "description": "The slug of the SDK feature which has been evaluated." }, "outputType": { "type": "string", "enum": [ "ENUM", "STRING", "NUMBER", "JSON", "TRANSFORMATION", "COMPONENT" ], "description": "Feature output type. Present if there were no errors." }, "outputValue": { "type": "string", "example": "YES", "description": "Feature output value. Present if there were no errors.\n - For the 'JSON_COMPONENT' output type, the response will be stringified JSON.\n - For the 'TRANSFORMATION' output type, the response will contain a stringified JSON array of transformations to be applied, including ENABLE_CONTENT, CUSTOM_COMPONENT, TEMPLATE_COMPONENT and FORM.\n" }, "error": { "type": "string", "example": "500: Internal error ...", "description": "The error message explaining why this decision failed to resolve. Present only if there was an error." } } }, "feature-decision-response-raw": { "description": "The raw output of the SDK feature rule, which will be of the datatype that corresponds to the configured rule output type. The possible types are 'string' or 'JSON'." }, "Session": { "type": "object", "properties": { "id": { "type": "string", "example": "aba22-a5mfh-", "description": "The ID of the session" }, "startDate": { "type": "string", "format": "date-time", "example": "2011-11-11T11:11:11.000", "description": "The creation date-time of the session" }, "deviceType": { "type": "string", "example": "pc", "description": "The type of device this session was created on" }, "deviceName": { "type": "string", "example": "Google Nexus 5", "description": "The name of the device this session was created on" }, "ip": { "type": "string", "example": "10.10.10.1", "description": "The IP address this session was created from" }, "browser": { "type": "string", "example": "Chrome", "description": "The name of the browser that this session was created from" }, "os": { "type": "string", "example": "Android", "description": "The operating system of the device that this session was created from" }, "city": { "type": "string", "example": "Huston", "description": "The name of the city that this session was created from" }, "geoState": { "type": "string", "example": "Texas", "description": "The name of the state that this session was created from" }, "country": { "type": "string", "example": "USA", "description": "The name of the country that this session was created from" }, "isRequestingSession": { "type": "boolean", "example": true, "description": "True if this session is the session that made the request to this endpoint, otherwise false" } } }, "stripe_start_response_body": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "New grant of product bundle to user" }, "clientSecret": { "type": "string", "description": "reference to Stripe payment required to process payment in front end" }, "paymentIntentStatus": { "type": "string", "description": "status of the payment which may require further action" } } }, "contact-create-request": { "type": "object", "properties": { "identifiers": { "$ref": "#/components/schemas/identifiers" }, "attributes": { "$ref": "#/components/schemas/attributes" } }, "required": [ "identifiers" ] }, "user-register-request": { "type": "object", "properties": { "identifiers": { "$ref": "#/components/schemas/identifiers" }, "validators": { "$ref": "#/components/schemas/validators" }, "attributes": { "$ref": "#/components/schemas/attributes" } }, "required": [ "identifiers", "validators" ] }, "user-register-response": { "type": "object", "properties": { "cookie": { "type": "string" }, "message": { "type": "string" }, "tracking_id": { "type": "string" } } }, "oauth2-config-response": { "type": "object", "properties": { "login_text": { "type": "string" }, "identifier_placeholder": { "type": "string" }, "logo_id": { "type": "string" }, "consent_text": { "type": "string" }, "background": { "type": "string" } } }, "delete-user-response": { "type": "object", "properties": { "message": { "type": "string" } } }, "user-public-account": { "type": "object", "properties": { "identifiers": { "$ref": "#/components/schemas/identifiers" }, "tracking_id": { "type": "string", "example": "123", "description": "456 (string)" }, "email_verified": { "type": "boolean", "example": true, "description": "A user email verification status." } } }, "validators": { "type": "object", "properties": { "password": { "type": "string", "example": "mysecurepassword123" }, "use_sso": { "type": "boolean", "description": "When this is present there should be no identifiers in the body. The user is identified through a blaize_session cookie." } } }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" } ] } }, "update-attributes": { "type": "object", "properties": { "blaize-validator": { "type": "string", "description": "An optional password that can be used to validate an outstanding partial registration." } }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" } ] }, "example": "Blow" }, "extended-profile": { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object" } ] } } ] }, "cdn-auth-challenge-response": { "type": "object", "description": "A map from entitlement ID to the decision outcome", "additionalProperties": { "type": "boolean" } }, "v4-gift-response": { "type": "object", "properties": { "token": { "type": "string", "example": "absd-acsd34-casdae-1243c", "description": "The token of the created gift." }, "claimPath": { "type": "string", "example": "/my-path?gift=absd-acsd34-casdae-1243c", "description": "The path that was generated for claiming the gift." } } }, "zephr-features-response-array": { "type": "array", "items": { "$ref": "#/components/schemas/zephr-features-response" } }, "zephr-features-response": { "type": "object", "properties": { "id": { "type": "string", "example": "feature-live" }, "label": { "type": "string", "example": "feature-label" }, "slug": { "type": "string", "example": "feature-slug" }, "targetType": { "type": "string", "enum": [ "CSS_SELECTOR", "COMMENT_TAG" ], "nullable": true }, "cssSelector": { "type": "string", "example": ".feature-css-selector", "description": "If the feature has a `targetType` of `CSS_SELECTOR` then the response will include a `cssSelector` field." } } }, "promo-code-decision-request-selected-product": { "type": "object", "properties": { "id": { "type": "string", "description": "The product identifier", "example": "product-a" }, "payment_plan": { "type": "object", "properties": { "provider": { "type": "string", "description": "The payment provider that provides the pricing data associated with the product", "example": "zuora-billing" }, "plan_id": { "type": "string", "description": "The payment plan identifier, typically this would be the product rate plan id" }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/promo-code-decision-request-selected-product-charge" } } } } } }, "promo-code-decision-request-selected-product-charge": { "type": "object", "properties": { "charge_definition_id": { "type": "string", "description": "The Product Charge Definition identifier" }, "currency": { "type": "string", "description": "The chosen currency against this product" }, "price": { "type": "number", "description": "The chosen price against this product" } } }, "StripeSubscription": { "type": "object", "properties": { "billingFrequency": { "type": "integer" }, "billingFrequencyUnit": { "$ref": "#/components/schemas/StripeSubscriptionInterval" }, "blaizeProduct": { "$ref": "#/components/schemas/StripeSubscriptionProduct" }, "currencyCode": { "type": "string" }, "discountsApplied": { "type": "boolean" }, "ended": { "type": "string", "format": "date-time" }, "ends": { "type": "string", "format": "date-time" }, "externalId": { "type": "string" }, "managedBy": { "type": "string" }, "multiphasePlan": { "type": "boolean" }, "nextBillingTime": { "type": "string", "format": "date-time" }, "paidThroughDate": { "type": "string", "format": "date-time" }, "planId": { "type": "string" }, "planName": { "type": "string" }, "preDiscountPrice": { "type": "number" }, "state": { "type": "string" }, "taxRates": { "type": "array", "items": { "$ref": "#/components/schemas/StripeSubscriptionTaxRate" } }, "transactionRecords": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRecord" } } } }, "StripeSubscriptionTaxRate": { "type": "object", "properties": { "active": { "type": "boolean" }, "displayName": { "type": "string" }, "isTaxInclusive": { "type": "boolean" }, "taxPercent": { "type": "number" } } }, "TransactionRecord": { "type": "object", "properties": { "cents": { "type": "number" }, "currency": { "$ref": "#/components/schemas/StripeSubscriptionCurrency" }, "cycle": { "type": "string" }, "cycleCount": { "type": "integer" }, "humanReadableAmount": { "type": "string" }, "taxRate": { "$ref": "#/components/schemas/StripeSubscriptionTaxRate" }, "time": { "type": "string", "format": "date-time" } } }, "StripeSubscriptionCurrency": { "type": "object", "properties": { "currencyCode": { "type": "string" } } }, "StripeSubscriptionInterval": { "type": "string", "enum": [ "DAY", "WEEK", "MONTH", "YEAR" ] }, "StripeSubscriptionProduct": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "subTenantId": { "type": "string" }, "tenantId": { "type": "string" } } }, "StripePromoCodeCheckResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Same code supplied as a query parameter in the request" }, "discount": { "type": "string", "description": "The discount offered by this promo code" }, "paymentOptions": { "type": "array", "description": "The payment options (either from the supplied payment form or from the request body) filtered for promo code validity", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "productId": { "type": "string" }, "currency": { "type": "string" }, "pricePointId": { "type": "string" }, "originalPrice": { "type": "number" }, "discountPrice": { "type": "number" } } } } } }, "StripePromoCodeCheckRequest": { "type": "object", "properties": { "paymentOptions": { "type": "object", "properties": { "currency": { "type": "string" }, "description": { "type": "string" }, "label": { "type": "string" }, "order": { "type": "integer" }, "price": { "type": "number" }, "pricePointId": { "type": "string" }, "productId": { "type": "string" }, "recommended": { "type": "boolean" }, "slug": { "type": "string" }, "subTenantId": { "type": "string" }, "tenantId": { "type": "string" }, "type": { "type": "string", "enum": [ "PRICE_POINT", "ONE_OFF", "REGULAR", "MULTI_PHASED" ] } } }, "promoCode": { "type": "string", "description": "The promo code ID that must be checked." } } }, "StartTwoFactorAuthenticationRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "login", "register", "completeRegistration" ] }, "identifiers": { "type": "object", "properties": { "email_address": { "type": "string" } } }, "method": { "type": "string", "enum": [ "email" ] } } }, "list-oauth2-consent": { "type": "object", "properties": { "consent": { "type": "array", "items": { "type": "string" } } } }, "blaize-schema-users-response": { "type": "array", "items": { "$ref": "#/components/schemas/blaize-schema-field" } }, "blaize-schema-field": { "type": "object", "properties": { "tenantId": { "type": "string", "example": "company" }, "subTenantId": { "type": "string", "example": "company|demo" }, "slug": { "type": "string", "description": "The unique identifier for the schema field.", "example": "first-name" }, "visibility": { "enum": [ "PUBLIC" ], "description": "The visibility of the schema field. This is used to determine who can see the field. By default, all fields are PUBLIC. Those fields are visible to all users.", "example": "PUBLIC" }, "context": { "type": "string", "description": "The context of the schema field. It is used to group fields together into different contexts. By default, all fields are used in the `null` context.", "example": "ZUORA_BILLING" }, "label": { "type": "string", "example": "First Name" }, "required": { "type": "boolean", "example": true }, "internal-description": { "type": "string", "example": "The first name of the user" }, "public-description": { "type": "string", "example": "The first name of the user" }, "validation-expression": { "type": "string", "example": "[a-z]+$" }, "input-type": { "enum": [ "text", "color", "number", "range", "time", "datetime-local", "date", "week", "month", "email", "tel", "url", "password", "select", "checkbox", "radio", "textarea", "hidden" ], "example": "text" }, "select-options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "default": { "type": "boolean" } } }, "example": "[ {key1: value1}, {key2: value2} ]" }, "range-start": { "type": "number", "example": 0 }, "range-end": { "type": "number", "example": 100 }, "range-step": { "type": "number", "example": 1 }, "decision-point": { "type": "boolean", "description": "The decision point of the schema field. It determines whether the field is used in the decision engine. If set to true, this field will be evaluated by the decision engine to influence the outcome of decisions. For example, a field marked as a decision point might be used to grant or deny access to a specific feature.", "example": true }, "publicly-writable": { "type": "boolean", "example": true }, "form-use": { "type": "boolean", "example": false } } } } } }