Tags

Tags let you attach custom key:value metadata to requests sent through Kimchi. Once attached, tags appear in Analytics, where you can filter usage and cost data by any combination of tags.

Tag format

Tags follow a key:value format validated against the following pattern:

^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?:[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$

Constraint	Limit
Format	`key:value`
Key length	1–64 characters
Value length	1–64 characters
Tags per request	10 maximum
First/last character	Must be alphanumeric (`a-z`, `A-Z`, `0-9`)
Interior characters	Letters, numbers, hyphens (`-`), underscores (`_`), dots (`.`)

📘
Valid examples: env:prod, team:ml-platform, experiment.v2:run-42, region:us.west.1

Attaching tags to requests

Request body

curl -X POST https://llm.kimchi.dev/openai/v1/chat/completions \
  -H "Authorization: Bearer $KIMCHI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "tags": ["env:prod", "team:ml", "feature:onboarding"]
  }'

HTTP headers

curl -X POST https://llm.kimchi.dev/openai/v1/chat/completions \
  -H "Authorization: Bearer $KIMCHI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Tags: env:prod,team:ml,feature:onboarding" \
  -d '{
    "model": "minimax-m3",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Header	Description
`X-Tags`	Primary tag header
`X-LiteLLM-Tags`	Alternative header for LiteLLM compatibility

When tags are provided in both headers and the request body, Kimchi merges and deduplicates them.

Managing tags with /tags

Use the /tags command inside a Kimchi session to view and change your active tags:

Command	What it does
`/tags`	List all currently active tags
`/tags add key:value ...`	Add one or more tags
`/tags remove tag ...`	Remove one or more user-defined tags
`/tags clear`	Remove all user-defined tags at once

Tags added with /tags add are saved to ~/.config/kimchi/tags.json and persist across sessions. They remain active until you explicitly remove them with /tags remove or /tags clear.

📘
Static tags set via the KIMCHI_TAGS environment variable cannot be modified with /tags. User-defined tags (added with /tags add) are the ones you can remove.

Example: replace a tag

/tags remove env:staging
/tags add env:prod
/tags

Tag query API

Three endpoints let you look up tags used across your organization. All endpoints require authentication via the X-API-Key header and return at most 50 results.

Endpoint	Description
`SearchTagKeys`	Returns tag keys used in your organization, ranked by popularity. Supports filtering by key prefix.
`SearchTagValues`	Returns values for a specific tag key, ranked by popularity. Supports filtering by value prefix.
`SearchTags`	Returns full `key:value` tag combinations, ranked by popularity. Supports filtering by key prefix.

CEL filter syntax

The GenerateAnalytics and GenerateLatestInferenceSummaries API endpoints accept a filter field that uses CEL (Common Expression Language) syntax to narrow results by tag.

Expression	Meaning	Example
`tags["key"] == "value"`	Match requests with an exact `key:value` tag	`tags["env"] == "prod"`
`"key" in tags`	Match requests that have any value for the key	`"env" in tags`
`expr1 && expr2`	Combine multiple conditions with AND	`tags["env"] == "prod" && tags["team"] == "ml"`

Expressions can be combined freely. For example, to match production requests that have any experiment tag:

tags["env"] == "prod" && "experiment" in tags

Filtering analytics by tags

After you start sending tagged requests, use the Tags filter on the Analytics page to break down usage and cost data by tag.