Attach arbitrary key-value string pairs to a 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:
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, 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.
One documented exception: "compression": "true" inside metadata is read by Truememory as a control flag — see Message compression.