Request Metadata Validation

The meta_data field in a Chat Completions or Threads-Run request carries optional context about the end user (e.g. licence, preferences). Which fields inside meta_data are required depends on the copilot's configuration.

Structure

The top-level meta_data object currently supports the following structure:

{
  "meta_data": {
    "user_data": {
      "licence": "<string>"
    }
  }
}

All fields default to null and are optional unless the Copilot requires them.

Copilot-Specific Required Fields

Each Copilot can require different fields. If a required field is missing or null, the API returns HTTP 422 Unprocessable Entity. Look up the required fields via GET /v1/assistants/{assistant_id}.

Example — request with required user_data

If the Copilot requires user_data.licence, the following request is valid:

{
  "assistant_id": "00000000-0000-0000-0000-000000000200",
  "messages": [{ "role": "user", "content": "What is BEM?" }],
  "meta_data": {
    "user_data": {
      "licence": "PI123"
    }
  }
}

Example — request missing a required field

If user_data is required but omitted, the API returns 422:

{
  "error_code": "request_metadata_missing_or_incomplete",
  "detail": "Request lacks required request metadata"
}