Skip to main content
POST
Create virtual key

Authorizations

X-Auth-Token
string
header
required

Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.

Headers

Idempotency-Key
string

A caller-chosen key, 8 to 255 characters, that makes this create safe to retry. The first request to use a key runs normally and its response is stored for 24 hours. A later request with the same key and the same body is not executed again: it returns the stored response, marked with X-Idempotent-Replay: true. The same key with a different body is refused 409 idempotency_error, as is a retry sent while the original is still running. Only successful responses are stored, so a create that failed can simply be retried with the same key.

Required string length: 8 - 255

Body

application/json
name
string
required
Required string length: 1 - 128
description
string
principal_user_id
string | null
scopes
object[]
Minimum array length: 1
trace_project_id
string | null
routing_policy_id
string | null
routing_mode
enum<string>
Available options:
none,
fallback_all,
policy
expires_at
string

When the key stops serving. Omit it and the key never expires. A date that has already passed is refused with virtual_key_expiry_in_past, rather than writing a key that is dead on arrival.

budget
object | null
config
object
external_id
string | null
Required string length: 1 - 128
metadata
object
purpose
string
Allowed value: "user"

Response

Virtual key created

virtual_key
object
required
secret
string
required
Last modified on May 19, 2026