Get the label vocabulary
Returns the published label taxonomy: every label with its key, kind, block and allowed values, an English display name for each label, block and value, and the derived tokens. A token is `<key>:<value>`. The vocabulary is exactly the set of tokens the `labels.all`, `labels.any` and `labels.none` filters of the conversation collection accept, so build a filter from what you read here. The display names are English text for explaining a label to a person: match on `key` and on the tokens, never on a `displayName`. It needs a valid API key like every route and returns no tenant data: it is the same for every organization.
Authorization
ApiKeyAuth A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).
In: header
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/api/v1/labels/vocabulary"{ "data": { "taxonomyVersion": "v1.2", "blocks": [ { "key": "resolution", "displayName": "Resolution" }, { "key": "types", "displayName": "Conversation type" }, { "key": "criteria", "displayName": "Criteria" }, { "key": "gaps", "displayName": "Content gaps" } ], "labels": [ { "key": "resolution", "displayName": "Resolution", "block": "resolution", "kind": "categorical", "values": [ "resolved", "partly_resolved", "unresolved", "no_real_need", "visitor_left" ], "valueNames": { "resolved": "Resolved", "partly_resolved": "Partly resolved", "unresolved": "Unresolved", "no_real_need": "No real need", "visitor_left": "Visitor left" } }, { "key": "product_question", "displayName": "Product question", "block": "types", "kind": "boolean", "values": [ "true" ], "valueNames": { "true": "Yes" } }, { "key": "grounded", "displayName": "Stuck to known facts", "block": "criteria", "kind": "criterion", "values": [ "pass", "fail" ], "valueNames": { "pass": "Passed", "fail": "Failed" } }, { "key": "gap_info_topic", "displayName": "Missing info about", "block": "gaps", "kind": "categorical", "values": [ "size_fit", "specs_performance", "composition", "compatibility", "usage_care", "variants", "other" ], "valueNames": { "size_fit": "Size or fit", "specs_performance": "Specs or performance", "composition": "Materials", "compatibility": "Compatibility", "usage_care": "Use or care", "variants": "Variants", "other": "Other" } } ], "derivedTokens": [ "sales_phase:pre_sales", "containment:contained", "transfer_reason:visitor_request" ], "documentationUrl": "https://iadvize.ai/docs/product/conversation-labeling" }}Get a conversation's labels
Returns the label record of one conversation under the published labeling configuration: its `labelStatus`, the `taxonomyVersion` of the read, and `labels`, the current run. `labels` is `null` unless `labelStatus` is `labeled`, and a status never carries a reason. When present, `answers` holds the judge's answer for each label with the ids of the messages that justify it, and `tokens` lists the conversation's label tokens. Only the current run is returned. A conversation of another site, another organization's conversation and an unknown id all answer the same `404`.
List a site's engagement exposure events over a period
Returns the raw funnel events the dashboard's Exposures tab lists, newest first: a widget shown, a launcher shown, a conversation opened, a starter question shown, the resume button. This is a debug-grade view of single events, not a metric: read the Engagement report for aggregates. A row carries an opaque session id and, when one exists, the conversation id. The page has no total. A cursor is bound to the period, the device and the type it was issued for. `from` and `to` are required UTC days, at most 366 days apart.