List conversations

List the diner's recent conversations with the AI waiter, newest first.

GET/api/v1/conversationsClient API

The session's diner's recent conversations, each with its status, channel, language, times and a short title.

Authentication

Client API. Send your publishable key in x-tamr-key and the diner's session in x-tamr-session, from Start a session. For a guest's session, also send its device id in x-tamr-device. A browser may call it only from an origin listed on the key.

Headers

NameTypeRequiredDescription
x-tamr-devicestringNoGuest sessions only: the device id the session was exchanged with. Matches ^[A-Za-z0-9_-]{8,128}$.
x-tamr-appstringNoNative apps only: the app's iOS bundle id or Android package name. A key used from an app it doesn't list is logged, never refused. Matches ^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$.

Response

A ConversationList.

FieldTypeDescription
conversationsarray of objectAt most 50 items.
conversations[].conversationIdstring1 to 200 characters.
conversations[].statusstringOne of active, resolved, escalated, fallback, abandoned, unknown. An open list: read a value you don't know as unknown.
conversations[].channelstringOne of qr, widget, app, mcp, unknown. An open list: read a value you don't know as unknown.
conversations[].localestring or nullA language tag, such as ar or en-GB.
conversations[].startedAtstring (date-time)
conversations[].updatedAtstring (date-time)
conversations[].titlestring or nullAt most 200 characters.

Example

curl https://tamr.link/api/v1/conversations \
  -H "x-tamr-key: $TAMR_APP_KEY" \
  -H "x-tamr-session: $TAMR_SESSION"

Example response

{
  "conversations": [
    {
      "conversationId": "cmconv0001",
      "status": "active",
      "channel": "app",
      "locale": "en",
      "startedAt": "2026-10-28T08:00:00Z",
      "updatedAt": "2026-10-28T08:05:00Z",
      "title": "Asked for something light"
    }
  ]
}

Errors

Every error has the same body; switch on data.code. See Errors and rate limits.

data.codeStatusWhat to do
app_key_invalid401The key is wrong, revoked or of another kind. Check it in the dashboard.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.
origin_not_allowed403A browser called from an origin the key doesn't list. Add the origin to the key.
session_expired401Start a new session with a fresh token or code, then send the call again once.
invalid_request400A field doesn't match the spec. The message says which.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.