iAdvizeDocs

Get a conversation with messages

Returns a single conversation: every field of the collection item, plus the playground `metadata` and the full ordered `messages` array. Read-only and tenant-scoped; messages have no API of their own. A conversation whose agent belongs to a different site than the one in the path, another organization's conversation and an unknown id all answer the same `404`.

GET
/api/v1/sites/{siteId}/conversations/{id}

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

Path Parameters

siteId*string

The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.

id*string

The conversation id (prefixed conv_).

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/api/v1/sites/string/conversations/string"
{  "data": {    "id": "conv_01kvnwmagvf27rc9cze5rm9e1r",    "title": "Looking for a waterproof jacket",    "channel": "web",    "language": "en",    "createdAt": "2026-09-28T14:00:00.000Z",    "updatedAt": "2026-09-28T14:03:00.000Z",    "siteId": "site_01kvnwmagvf27rc9cze5rm9e1r",    "agentId": "agt_01kvnwmagvf27rc9cze5rm9e1r",    "agentName": "Storefront assistant",    "agentVersion": 2,    "agentVersionId": "agtv_01kvnwmagwf27rc9d7zef4qksf",    "entryWidget": {      "id": "ewgt_01kvnwmagvf27rc9cze5rm9e1r",      "name": "Product page launcher",      "format": "launcher",      "version": 3    },    "pageContext": {      "pageType": "category",      "productId": null,      "categoryName": "Jackets",      "pageUrl": "https://shop.example/collections/jackets"    },    "messageCount": 2,    "durationMs": 180000,    "feedback": {      "positive": 1,      "negative": 0    },    "productEngagement": {      "impressions": 1,      "clicks": 1    },    "labelStatus": "labeled",    "labelSummary": {      "resolution": "resolved",      "reviewReason": null,      "scores": {        "quality": 0.92,        "service": 1,        "trust": 1      },      "failedCriteria": []    },    "metadata": null,    "messages": [      {        "id": "msg_01kvnwmagvf27rc9cze5rm9e1r",        "role": "shopper",        "content": [          {            "type": "text",            "text": "I need a waterproof jacket for hiking."          }        ],        "feedback": null,        "createdAt": "2026-06-27T14:00:00.000Z"      },      {        "id": "msg_01kvnwmagwf27rc9d7zef4qksf",        "role": "assistant",        "content": [          {            "type": "text",            "text": "Here are two jackets that hold up in rain."          },          {            "type": "product_cards",            "products": [              {                "id": "prod_1",                "title": "Trail Shell",                "url": "https://shop.example/products/trail-shell",                "imageUrl": "https://shop.example/img/trail-shell.jpg",                "price": {                  "minMinor": 12900,                  "maxMinor": 12900,                  "currency": "EUR"                },                "available": true,                "pitch": "Light and fully taped seams."              }            ]          }        ],        "feedback": {          "value": "positive",          "category": null,          "comment": null,          "createdAt": "2026-06-27T14:02:00.000Z"        },        "createdAt": "2026-06-27T14:01:00.000Z"      }    ]  }}

List a site's conversations

Returns the conversations run through this site's agents, newest first by creation time, with their context, feedback, engagement and a summary of their labels. The list is scoped to the site in the path and to the organization of the API key. Filters combine with AND: `labels.all` needs every token, each `labels.any` group (tokens separated by `|`) needs one of its tokens, and `labels.none` excludes tokens and needs a positive label filter or a date range. `limit` is 1 to 100 (25 by default), and a cursor is bound to the filters it was issued for. Read-only: conversations are created by the agent, never via this API.

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`.