API Reference

Get Conversation Metadata Keys

Overview

Discover the custom metadata keys (and sample values) currently stored on conversations in the tenant workspace.

Use this endpoint to build filter UIs for metadata.<key> query parameters on List Conversations — for example metadata.workspaceId=c1 or metadata.department=support.

When to use this endpoint?

Use Get Conversation Metadata Keys when:

Building dynamic filters, facets, or dropdowns for conversation lists.
Discovering which metadata keys exist before hard-coding filter fields.
Showing admins how many conversations use each key and which values appear.
Keeping filter UIs in sync as your app stores new metadata over time.

After discovering keys, apply them as metadata.<yourKey>=value on Conversations → List Conversations.

GET{baseUrl}/api/{apiVersion}/client/conversations/metadata-keys

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Access Token from Login Client or Register Client.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.

Success Response (HTTP 200 OK)

Each entry includes the metadata key, how many conversations use it (count), distinct value count, and sample values.

json

{
  "success": true,
  "message": "Metadata keys fetched successfully",
  "data": {
    "keys": [
      {
        "key": "workspaceId",
        "count": 42,
        "totalValues": 3,
        "values": [
          "c1",
          "c2",
          "c3"
        ]
      },
      {
        "key": "department",
        "count": 17,
        "totalValues": 2,
        "values": [
          "sales",
          "support"
        ]
      }
    ]
  },
  "error": null
}

Common Errors

Metadata key discovery fails when authentication or tenant headers are missing or invalid.

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Client account is inactive or tenant access is restricted.
500 Internal Server Error	An unexpected error occurred while fetching metadata keys.

Best Practices

Call this endpoint when building or refreshing conversation filter UIs — do not hard-code keys if they can change.
Map each returned key to a metadata.<key> query param on List Conversations.
Use values as suggestions for filter dropdowns; treat them as samples, not a complete enum.
Always send tenant headers (is-tenant, x-client-id) with a valid Bearer token.

Filters ready to wire

Apply discovered keys as metadata.<key>=value on Conversations → List Conversations to filter the inbox by your custom fields.

Header

Value

Description

Authorization

Bearer <access_token>

Access Token from Login Client or Register Client.

is-tenant

true

Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).

x-client-id

Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.

{ "success": true, "message": "Metadata keys fetched successfully", "data": { "keys": [ { "key": "workspaceId", "count": 42, "totalValues": 3, "values": [ "c1", "c2", "c3" ] }, { "key": "department", "count": 17, "totalValues": 2, "values": [ "sales", "support" ] } ] }, "error": null }

Code

Reason

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

Client account is inactive or tenant access is restricted.

500 Internal Server Error

An unexpected error occurred while fetching metadata keys.