API Reference

Get Message Metadata Keys

Overview

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

Use the returned keys to build filter UIs for metadata.<key> query parameters on List Messages. Each entry includes how often the key appears, how many distinct values exist, and example values.

When to use this endpoint?

Use Get Message Metadata Keys when:

Building admin filters that query metadata.<key>=value on List Messages.
You need to know which metadata keys exist before hard-coding filter fields.
Showing facet counts or sample values in a moderation or analytics UI.
Auditing which custom fields your app has attached to messages.

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

Authentication

Required (Bearer token)

Tenant-scoped

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

Request Headers

Header	Value	Description
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)

On success, the API returns the metadata keys found on messages, with counts and sample values.

json

{
  "success": true,
  "message": "Metadata keys fetched successfully",
  "data": {
    "keys": [
      {
        "key": "workspaceId",
        "count": 128,
        "totalValues": 3,
        "values": [
          "c1",
          "c2",
          "c3"
        ]
      },
      {
        "key": "flagged",
        "count": 6,
        "totalValues": 2,
        "values": [
          false,
          true
        ]
      }
    ]
  },
  "error": null
}

Common Errors

HTTP 200 OK means the keys were fetched successfully. Requests fail when tenant headers or authentication are missing or invalid.

Code	Reason
400 Bad Request	Required headers are missing or invalid.
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching metadata keys.

Best Practices

Call this endpoint when building filter UIs so you only offer keys that actually exist.
Map each returned key to a metadata.<key> query param on List Messages.
Use values as suggestions for dropdowns, but allow free text when new values appear.
Re-fetch keys after bulk metadata updates so filter options stay current.
Always send is-tenant: true and a valid x-client-id with a Bearer token.

Ready to filter by metadata

Use the returned keys with List Messages query params such as metadata.workspaceId=c1 to narrow results in your admin UI.

Header

Value

Description

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": 128, "totalValues": 3, "values": [ "c1", "c2", "c3" ] }, { "key": "flagged", "count": 6, "totalValues": 2, "values": [ false, true ] } ] }, "error": null }

Code

Reason

400 Bad Request

Required headers are missing or invalid.

401 Unauthorized

Access Token is missing, invalid, or expired.

500 Internal Server Error

An unexpected error occurred while fetching metadata keys.