Server API
UXWizz v10 exposes a versioned API with read access and optional write scopes. The full base URL is the dashboard origin plus /server/api/v1/, for example https://analytics.example.com/server/api/v1/. API tokens use the same current role and domain permissions as their owner, so reducing a user's access immediately reduces their tokens' permissions.
Create a token
Open Settings → API access, create an API token, select only the scopes and domains the integration needs, and set an expiry when possible. The secret is shown once. Store it like a password and revoke it when unused.
Read scopes cover domains, domain access grants, analytics, bots, visitors, tags, recordings, heatmaps, events, autocomplete data, A/B tests, goals, segments, and your screen layouts. Each has its own scope; goals.read does not grant segment access, and write scopes do not grant read access. Autocomplete data contains visitor tags, IP addresses, referrer domains, and country codes used for suggestions.
Write scopes are unchecked by default. Existing tokens keep their current scopes; use Edit access to grant writes. Tokens cannot create/delete users, delete sessions, heatmaps or recordings, change settings, run updates, or edit A/B tests.
Read core data
These endpoints use GET and require the named scope plus current user and domain access:
goals.read
goals/?action=list
domain
{items, canShare} with visible goals.
goals.read
goals/?action=get
domain, id
{item, canShare} for one visible goal.
segments.read
segments/?action=list or get
domain; id for get
Same shapes as goals, for segments.
goals.read and/or segments.read
saved-filters/?action=list or get
domain, optional kind; id for get
Only the kinds granted to the token.
tags.read
visitors/?action=tags
domain, clientID
{tags: ["checkout"]} for that visitor, sorted.
domain-access.read
domains/?action=access
domain, optional targetUserId
{domain, items: [{id, name}]}. Administrators can read other users; other roles see only themselves.
layouts.read
layouts/?action=list
Optional surface, signature
{items} for your screen layouts.
domains.read
domains/?action=list
None
Array of domains allowed by both owner and token.
Goal/segment responses retain id, kind, name, color, definition, ownerUserId, scope, domainId, domainNames, visibility, userIds, and updatedAt. Lists use the same private/shared and domain/global/selected visibility as the dashboard. Missing, hidden, wrong-kind, or unavailable records return 404 on single-record reads. Missing scopes or domain access return 403. Reads return saved definitions; use analytics endpoints for counts over a date range.
tags.read also permits POST autocomplete/?action=tags with domain to list distinct tags on the domain. It does not grant IP or other autocomplete reads. Existing visitor/analytics scopes still return the data those endpoints normally contain.
Example: read goals without granting write or segment access:
Legacy saved-filters.read and saved-filters.write scopes still grant both goal and segment access. New tokens use the granular choices. Editing a legacy token shows its combined grant as both granular choices; saving keeps equivalent access unless you deselect one. Existing tokens gain no scope automatically.
Write operations
All writes use POST and require the named scope plus your current role and access rights.
tags.write
visitors/?action=add-tag or remove-tag
domain, clientID as a decimal string, tagContent (1–128 characters). Analyst role or higher.
goals.write or segments.write
saved-filters/?action=save
domain, kind (goal/segment), name, definition (JSON string). Optional id updates an owned record. Scope must cover the requested and existing kind.
goals.write or segments.write
saved-filters/?action=delete
domain, id, optional scope (domain/all). Scope must cover the stored kind.
domain-access.write
domains/?action=add-access or remove-access
domain and targetUserId. One existing user and registered domain. Administrator permission is required for other users.
layouts.write
layouts/?action=save
surface, signature, layout (responsive JSON string), optional profileKey and profileName.
Saved goals and segments have the same availability options as the dashboard:
scope:domain(default),selectedwithdomainNames(JSON string array), orglobal.visibility:private(default),selectedwithuserIds(JSON string array), orall. Sharing requires administrator permission.Optional
colorfor display.definitionuses the dashboard filters, such astagFilters,pagesFilter,countriesand excluded filters; dates belong to the active view.
The token and its owner must have access to every selected domain. Updating a record requires access to its existing domains and its new domains. Global changes require an all-domains token. Read existing records and their complete availability configuration with the read endpoints above.
Goal deletion defaults to removal from the requested domain, retaining other domains. Set scope=all to delete the whole goal. Segment deletion removes the whole segment, as in the dashboard. Whole-record deletion requires token access to all affected domains.
Screen layouts use the dashboard's existing per-user screen, content signature and profile model. layouts.read and layouts.write cover your layouts across domains; they cannot read or write another user's layout. For the Stats screen, the signature input is stats-v1: followed by the sorted, comma-separated visible goal IDs. The API accepts this input or its SHA-256 hash. The default profile is shared / Shared, meaning shared across your devices. Layout JSON retains responsive breakpoint keys such as lg and sm.
Domain access changes keep recorded data and user accounts intact. They honor agency domain limits and the token's selected domains. They cannot register a new domain, create its database, or grant access beyond the token owner's access.
Example: create a goal shared with selected users on selected domains:
The response contains item with the saved ID and configuration. Tag and domain-access writes return {"ok":true}, including repeated adds/removals. Bearer writes do not require a browser CSRF token.
Make a request
Resources use a directory plus an action query parameter. No URL rewriting is required. Example:
POST requests accept JSON objects or form data; action always stays in the query string. Treat database BIGINT identifiers as decimal strings in JavaScript to avoid precision loss.
Time-series actions such as visitors, pageviews, page-load-time, session-length, and bounce-rate accept dateInterval as HOUR, DAY, WEEK, or MONTH. It defaults to DAY. Date filters are inclusive local calendar dates in YYYY-MM-DD format; send both startDate and endDate, and send the local offset from UTC as dateOffset in minutes.
Time-series rows contain date and value. Visitors and pageviews are counts, page-load time is seconds, session length is minutes, and bounce rate is percent. The number action instead returns sessionLength in seconds.
Authenticated API description
Open /server/api/v1/ or /server/api/v1/openapi/ with an authenticated browser session or bearer token. UXWizz returns an OpenAPI 3.1 document filtered to the caller's authentication type, current role, token scopes, and available build features. A browser session can list dashboard-only routes that bearer tokens cannot use. Fetch the document with the intended token to discover its exact integration surface. If an action is absent, that caller cannot use it.
x-uxwizz-actions describes each supported action and form field, including allowed values and defaults. scopeAlternatives lists other accepted scopes alongside scope; one is required, and saved-filter operations further check the actual record kind. Discovery also respects restricted-account route policies. Domain, ownership, sharing and target-user checks run on each request. A 403 response is an access denial, not an empty analytics result.
Cross-origin integrations require a bearer token and an origin listed in UXWIZZ_API_CORS_ORIGINS. A separately hosted UXWizz dashboard instead uses UXWIZZ_DASHBOARD_ORIGINS; those exact trusted origins may use the HttpOnly session cookie and must be served over HTTPS. Reverse proxies must forward the Authorization header to PHP.
Last updated
Was this helpful?