API reference

This page documents the analytics gateway and managed embed runtime. External model execution is a separate production service documented under Dashnet inference, with model discovery at GET https://inference.dashnet.ai/v1/models and messages at POST https://inference.dashnet.ai/v1/messages.

This page documents the DashQ Analytics gateway contract. Use the base URL and credential assigned to your environment; do not copy a host from examples or construct embed hosts manually.

Authentication model

Surface	Credential	Where it is used
Token/session issuance	x-api-key	Trusted backend only
Widget and dashboard catalogs	X-Widget-Session-Token	Trusted backend after session issuance
Native widget data	X-Widget-Session-Token	Trusted backend after session issuance
Dashboard runtime	Signed embed URL, then secure embed session	DashQ-rendered iframe
Assistant runtime	Signed Assistant URL	DashQ-rendered iframe
Dictionary APIs	Gateway policy plus server-side visibility filtering	Trusted backend

The legacy Authorization: Bearer <widget-session> form may be disabled. New integrations must use X-Widget-Session-Token.

Current defaults:

• Dashboard and Assistant embed URLs: 300-second issuance lifetime.
• Widget sessions: 300-second lifetime.
• Omitted date range: most recent 30 days.
• Widget row limit: 31 by default, capped at 90 unless your environment sets another maximum.
• Embed/runtime and dictionary responses use non-cacheable or short-lived scoped behavior; do not add a broader shared cache.

Common conventions

• IDs are strings. Account, dashboard, property, and user identifiers accept letters, digits, _, and - where noted.
• Dates use YYYY-MM-DD; startDate must be on or before endDate.
• Array scopes may accept JSON arrays; selected endpoints also accept comma-separated strings.
• Resolve identity and authorization on your backend. Browser values may request a filter but must never define the allowed scope.
• Successful JSON responses use Content-Type: application/json. Error responses use { "error": "..." } and may include a stable code/title on embed-runtime routes.

Discovery and health

GET /api/health

Minimal liveness response:

{ "ok": true }

GET /api/embed-dashboard-catalog

Returns the registered dashboard catalog for embed selection:

{ "dashboards": [] }

Use the session-scoped /api/v1/dashboards/catalog when selection must reflect a requested widget subset.

Dashboard embed issuance

POST /api/embed-url

Requires x-api-key. Issues a signed dashboard URL and applies Cache-Control: no-store.

Request body:

Field	Required	Description
accountId	Yes	Authorized account ID.
dashboardId	No	Defaults to portfolio_foundation_v1; must be registered.
buildingIds	No	Authorized property IDs as an array or comma-separated string.
externalUserId, userId, user_id, dashqUserId	No	Equivalent identity aliases; supplied values must agree.
userEmail, user_email, email	No	Email aliases, normalized and hashed before token issuance.
userEmailHash, user_email_hash	No	Pre-hashed identity aliases; must agree with any email supplied.
startDate, endDate	No	Defaults to the configured recent window.

For numeric DashQ user IDs, the gateway can resolve the directory identity for the account. A conflicting alias, unknown dashboard, invalid date range, or unresolved required identity returns an error instead of widening scope.

Response:

{
  "embedUrl": "https://ASSIGNED_DASHQ_EMBED/...",
  "expiresInSeconds": 300,
  "accountId": "ACCOUNT_ID",
  "dashboardId": "portfolio_foundation_v1",
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "buildingIds": ["BUILDING_ID"],
  "userId": "USER_ID"
}

Registered foundation dashboards:

ID	Surface
portfolio_foundation_v1	Portfolio Performance
lead_to_lease_foundation_v1	Lead-to-Lease
tour_foundation_v1	Tour Performance
application_foundation_v1	Application Operations
marketing_foundation_v1	Marketing / Acquisition
communication_foundation_v1	Communication Performance

Assistant embed issuance

POST /v1/embed/url

Requires x-api-key. Issues a signed DashQ Assistant URL.

Field	Required	Description
accountId	Yes	Authorized account ID.
buildingIds	No	Authorized property scope.
externalUserId, userId, user_id, dashqUserId, or userEmail	One stable identity for Analytics Assistant	Must identify a user, not only the account.
userName	No	Display name, normalized to a bounded length.
userRole, user_role, dashqUserRole	No	Equivalent trusted role aliases.
dashboardId	No	Seeds default starter questions from a dashboard manifest.
starterQuestions	No	Array; blanks and duplicates removed, maximum three.
startDate, endDate	No	Must be provided together and in order.

Numeric user IDs may be enriched from the DashQ user directory. Response fields include embedUrl, expiresInSeconds, resolved user identity/name/role fields, and normalized dates when supplied.

Native widget session

POST /api/v1/widgets/session

Requires x-api-key. Creates the scoped session used by the native catalog and data routes.

Field	Required	Description
accountId	Yes	Authorized account ID.
requestedWidgetIds	No	Registered widget IDs. Omit to request the complete current registry. Unknown IDs return 400.
userId, user_id, dashqUserId	No	Equivalent server-derived identity aliases.
Email/hash aliases	No	Same normalization and consistency rules as dashboard issuance.

Response:

{
  "sessionToken": "SHORT_LIVED_TOKEN",
  "expiresInSeconds": 300,
  "widgetIds": ["leasing_funnel"],
  "accountId": "ACCOUNT_ID",
  "userId": "USER_ID"
}

Do not return sessionToken to the browser. Your backend should use it and return the minimum scoped data required by the UI.

Catalogs

Both routes require X-Widget-Session-Token.

GET /api/v1/widgets/catalog

Returns only widgets named in the session. Each widget includes its ID, title, description, kind, semantic model, required fields, allowed filters, and allowed metrics.

GET /api/v1/dashboards/catalog

Returns dashboard manifests compatible with the session's widgets, including dashboard ID/title, target view, audience, sections, included and pending modules, widget presentation metadata, and filter capabilities.

Widget data

POST /api/v1/widgets/{widget_id}/data

Requires X-Widget-Session-Token. The widget must exist and be allowed by the session.

Optional request fields:

Field	Behavior
startDate, endDate	Defaults to the recent configured window.
buildingIds	Building scope. An explicit empty/none selection returns no building data.
buildingPropertyIds	Alternate property mapping scope.
representativeIds	Representative scope where the widget supports it.
unitTypes or unitType	Unit-type scope.
stage	Funnel/application stage.
source	Marketing or lead source.
leaseAttributionMode	Supported attribution mode for compatible manifests.
limit	Defaults to 31 and is capped by the environment maximum.
offset	Defaults to 0.

The sort field is rejected. Use catalog-defined ordering plus limit/offset pagination.

Response:

{
  "widgetId": "WIDGET_ID",
  "meta": {
    "accountId": "ACCOUNT_ID",
    "startDate": "2026-01-01",
    "endDate": "2026-01-31",
    "mode": "bigquery",
    "effectiveBuildingIds": ["BUILDING_ID"],
    "limit": 31,
    "offset": 0
  },
  "data": []
}

Additional meta fields report the selected properties, representatives, unit types, stage, source, attribution mode, and widget-specific pagination when applicable.

Dictionary APIs

Dictionary results are filtered to metadata visible to the runtime identity. Use the public Data Dictionary for the complete public snapshot.

GET /api/v1/dictionary/categories

Query fields: optional query and category. Returns categories[] with id, label, termCount, plus totals and active filters in meta.

GET /api/v1/dictionary/terms

Query fields:

• query: searches term, description, formula, grain, cadence, usage, notes, logic, lineage, and linked asset metadata.
• category: category ID or label.
• limit: defaults to 100, maximum 500.
• offset: defaults to 0.

Each term can include:

• Business identity: id, term, description, categoryId, category, visibility and publication metadata.
• Definition context: formula, grain, usage, notes, cadence, logicExplanation, and term-level lineage.
• Linked assets[]: dataset, table, column, fully qualified path, data type, nullability, definition, SQL expression/logic, model lineage, and table metadata such as grain, keys, date columns, time zone, access scope, and refresh cadence.

Response meta includes the runtime member, filters, limit/offset, returned count, and total count.

GET /api/v1/dictionary/terms/{term_id}

Returns one visible term. Unknown or inaccessible IDs return 404.

Managed dashboard runtime

The signed URL launches a DashQ-managed runtime. These routes are documented so integrators understand behavior, logs, CSP/CORS policy, and report workflows. Do not reconstruct their requests or replace the signed session with a host-app credential.

Endpoint	Purpose
GET /embed/dashboard	Secure dashboard shell and signed-session establishment.
GET /embed/dashboard/shell	Authoritative shell metadata and immediately required scope.
GET /embed/dashboard/deferred	Deferred filter/options metadata.
GET /embed/dashboard/data	Compatibility data route.
GET /embed/dashboard/widget-data	One runtime widget payload.
GET /embed/dashboard/widget-data/batch	Batched widget payloads.
GET /embed/dashboard/widget-standalone-data	Standalone table/detail payload with pagination.
GET /embed/dashboard/drilldown	Governed drilldown rows for the active scope.
POST /embed/dashboard/insights	Generated insight summary for trusted computed metrics.
GET /embed/dashboard/report	Backend-rendered PDF for the active dashboard or suite.

Runtime scope fields include dashboard, dates, building IDs, building-property IDs, representatives, unit type, stage, source, and lease attribution mode. Each route resolves these values against the signed session and governed user/property access before querying.

Reports

GET /embed/dashboard/report accepts the active runtime scope plus:

• dashboardId: single dashboard selection.
• suite: true by default for the dashboard suite.
• widgetIds: optional comma-separated subset.

The response is a generated PDF with a scope-derived filename. Report generation can have a longer timeout than interactive data routes.

Insights

POST /embed/dashboard/insights accepts the active scope at the top level or inside filters. If accountId is supplied, it must match the signed session.

Response fields:

• summary
• positive[]
• negative[]
• generatedAt
• meta: dashboard ID/title, target view, provider, highlight count, and coverage warnings

DashQ computes the metric brief first. The language provider phrases and prioritizes those trusted facts; it does not choose the account or query arbitrary data.

Errors and retries

Status	Meaning	Action
400	Invalid JSON, ID, date, filter, alias conflict, or unsupported option	Correct the request; do not retry unchanged.
401	Missing, invalid, or expired credential/session	Re-authenticate or issue a new session. Rotate a credential if exposure is possible.
403	Resource or scope is not allowed	Stop; do not enumerate or broaden the request.
404	Unknown or invisible dashboard/widget/term	Refresh the relevant catalog.
429	Rate or cost guardrail	Back off with jitter and reduce concurrency or query scope.
5xx	Temporary service or configured-provider failure	Retry boundedly and retain a non-sensitive correlation ID.

Security layers

1. The host backend authenticates its user and resolves entitlements.
2. The gateway authenticates issuance calls.
3. The serving API validates IDs, dates, dashboards, widgets, aliases, and filters.
4. Short-lived tokens bind account, user, property, widget, and date context.
5. Runtime resolution intersects requested scope with governed building/user access.
6. Dictionary and warehouse metadata are visibility-filtered.
7. Responses are bounded, and logs must redact credentials, signed URLs, tokens, cookies, prompts, and raw business rows.

See Embedded experiences, Data APIs, Catalog discovery, and Security for implementation guidance.