iAdvizeDocs

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.

GET
/api/v1/labels/vocabulary

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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.1",    "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://www.iadvize.ninja/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`.