Customer experience API

Build a website or mobile app with published catalogue browsing, email sign-in, customer profiles, product/routine chat, face analysis, feedback and analytics. Your backend calls these authenticated endpoints; your customers never receive your account integration key.

Two separate credentials

The integration owner is never used as the visitor automatically. A general Dashboard/Admin token is not accepted as X-Visitor-Token. Your backend must associate each visitor credential with the correct authenticated application session. Do not let a caller select another customer's credentials or arbitrary guest device IDs. Redact all credential headers in application/proxy logs.

Base path: https://api.incele.ai/v1/workspaces/WORKSPACE_ID/experience.

Permissions

• storefront:read: bootstrap, published products, collections and tags.
• visitors:read: customer profile and session status.
• visitors:write: customer email sign-in, renewal, logout, safe profile updates, feedback, events and conversation deletion.
• ai:write: product chat, routine chat and face analysis, charged to the workspace wallet.

All calls also require the integration owner's current ownership of the active workspace. Revocation, source blocking and connection rate limits apply. Read-only catalogue lists honor site access policy and return published/active resources, unlike owner management lists.

Bootstrap a guest

Generate a stable, unpredictable guest device ID in your own application session. Keep the same ID on all calls for that visitor.

curl https://api.incele.ai/v1/workspaces/WORKSPACE_ID/experience/bootstrap \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'X-Guest-Device-Id: YOUR_VISITOR_UUID'

The response contains workspace, accessPolicy, viewer, guestToken and turnstileSiteKey. Save guestToken with that visitor's session and send it as X-Guest-Token on subsequent calls. Render the configured Turnstile challenge when required and send its result in turnstileToken. A missing guest header does not authenticate the integration owner as a visitor.

Browse your catalogue

Use GET /products, /products/{productId}, /products/slug/{productSlug}, /collections, /collections/{collectionId}/products, /tags, /tags/{tagId}/products and /tags/{tagId}/collections under the base path. Preserve visitor/guest headers. List endpoints support their existing pagination/search filters. Read website configuration using the separately scoped website management operations; render only the public fields your frontend needs.

Customer email sign-in

1. POST /customer/otp/request with {"name":"Ada Example","email":"[email protected]","turnstileToken":"CHALLENGE_RESULT"}. Phone is optional. Name/email validation, disposable-address protections and resend cooldown apply.
2. POST /customer/otp/verify with {"email":"[email protected]","code":"123456"}. Codes expire, allow five failed attempts and can be consumed only once.
3. Save the returned token and sessionExpiresAt in that customer's secure application session. Send it using X-Visitor-Token on later calls.
4. GET /customer/session, POST /customer/refresh with {}, and POST /customer/logout with {} to maintain or revoke the session.

Session responses include only a customer profile and visitor credential, without account roles, memberships or billing details. A tenant customer token cannot create API keys, manage workspaces or access Administration. Customer sessions default to 365 days and renew while active; expired/revoked sessions require sign-in.

GET /customer/profile returns id, name, email, phone and language. PUT /customer/profile updates name, phone and language while sending the unchanged email. Account email changes require account sign-in in the İncele dashboard, preventing a third-party customer session from taking over a platform identity.

AI interactions

POST /chat/product:

{
  "message": "Is this suitable for dry skin?",
  "productId": "YOUR_PUBLISHED_PRODUCT_ID",
  "productName": "Your product name",
  "thinkingLevel": "LOW",
  "turnstileToken": "CHALLENGE_RESULT_WHEN_REQUIRED"
}

POST /chat/routine supports message, userProfile, userSelectedRoutineProducts, allowAiSuggestions, thinkingLevel, optional images and Turnstile result. Use the published catalogue IDs. POST /chat/analyze-face accepts image as a base64 image/data URL and an optional turnstileToken. Send only images the visitor has consented to process. Thinking level is LOW, MEDIUM or HIGH; requests remain subject to the overall 5 MiB JSON limit.

Responses include threadId, the AI response and access/credit information where applicable. Preserve the exact opaque threadId when continuing a conversation. DELETE /threads/{threadId} removes only a conversation signed for that workspace and visitor. Switching visitor identities requires starting a new conversation; never share conversation identifiers publicly.

AI calls preserve the hosted site's visitor access policy, Turnstile checks, per-visitor quota, rate limits and atomic workspace credit reservations. Insufficient credits or restricted access is an error, not an invitation to bypass the check. A successful API key check alone does not grant AI access. AI calls use real credits in their selected environment; do not automatically retry after an uncertain response.

Feedback and events

POST /feedback accepts {"message":"Your visitor feedback"} (1–500 characters) and returns an empty successful response when accepted. POST /events accepts the current analytics event schema; see Swagger. Send events for the current visitor only and honor the visitor's privacy choices.

Errors and deployment

Use the API contract for status handling and rate limits. Visitor controllers may return either {status,code,message} or {error,code}; use the HTTP status first and never depend on localized text. AI responses and visitor profiles must be escaped in your frontend.

Use XYZ for development, with separate accounts, keys, media and credits. Do not send production customer credentials to XYZ. Deploy your own backend and frontend independently; selecting an İncele template does not deploy your external code. Review the Swagger explorer for the exact supported external paths and required scopes.