---
title: "Custom metadata"
description: "Attach key-value pairs to a request — persisted with the thread and echoed back to the client."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom metadata

Attach arbitrary key-value string pairs to a [chat completions](/ai-gateway/chat-completions/) request using the root-level `metadata` parameter. This is useful for storing client context (source app, user location, image URLs, UI hints) alongside the conversation without changing the message schema.

**Constraints:**

| Limit | Value |
|-------|-------|
| Max keys per request | 16 |
| Max key length | 64 characters |
| Max value length | 512 characters |
| Value type | string only |

**Example:**

```bash
curl -X POST https://your-tie-host/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "Describe this image"}
    ],
    "metadata": {
      "session_id": "8b94776f-31ae-49ac-9f06-3be137d69186",
      "platform": "ios",
      "app_version": "2.4.1"
    }
  }'
```

Metadata is echoed back in the response and persisted with the thread. When you retrieve [thread history](/ai-gateway/threads/#get-thread-history), metadata appears on the user message it was attached to.

When streaming, metadata is included in the **first SSE chunk** so clients can act on it immediately (e.g. render skill-specific UI before content arrives):

```
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1711234567,"model":"anthropic/claude-sonnet-4-5","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}],"metadata":{"active_skill":"menu","super_skill":"keto"}}
```

Subsequent chunks do not contain metadata.

:::note
Metadata is for client use. The LLM does not see it — only `content` is visible to the model.
:::

One documented exception: `"compression": "true"` inside `metadata` is read by Truememory as a control flag — see [Message compression](/ai-gateway/features/message-compression/).

Source: https://truememory-docs.mvstg.com/ai-gateway/features/custom-metadata/index.mdx