Managing Model Configurations via the API

Last updated: May 1, 2026

The LangSmith UI lets workspace admins create and manage model configurations under Settings > Model configurations. The same operations are available via REST API, which is useful for scripting, CI/CD pipelines, or programmatic workspace setup.

Note: This API is not yet covered in the public docs. The UI-only guide is at https://docs.langchain.com/langsmith/model-configurations

Prerequisites

Auth: Include your workspace API key as X-API-Key in every request.
Permissions: Creating, updating, or deleting configurations, and setting per-feature defaults, requires workspace admin access.

Base URLs

Region	Base URL
US	`https://api.smith.langchain.com`
EU	`https://eu.api.smith.langchain.com`

export BASE_URL="https://api.smith.langchain.com"     # or eu.api.smith.langchain.com
export LS_API_KEY="ls__..."

Create a model configuration

curl -X POST "$BASE_URL/api/v1/playground-settings" \
  -H "X-API-Key: $LS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-proxy-model",
    "settings_type": "simple",
    "settings": {
      "modelId": "openai:gpt-4o",
      "envVarName": "MY_PROXY_API_KEY",
      "baseUrl": "https://your-proxy.example.com/v1"
    }
  }'

settings_type: Use "simple" for the fields above. "complex" accepts a raw LangChain serialized constructor — only needed for advanced use cases.
modelId format: "provider:model-name", e.g. "openai:gpt-4o", "anthropic:claude-sonnet-4-6", "azure_openai:gpt-4". For custom proxy or Vertex AI setups the format extends to "openai:vertex_ai/<model-name>@<version>".
envVarName: The name of the workspace secret (configured under Settings > Workspace secrets) that holds the API key for this provider.
baseUrl: Optional. Set this when using a custom proxy or alternative endpoint.

The response includes an id field — save it, you'll need it for updates and to set feature defaults:

{
  "id": "abc12345-...",
  "name": "my-proxy-model",
  "settings_type": "simple",
  "settings": { ... },
  "available_in_playground": true,
  "available_in_evaluators": true,
  "available_in_agent_builder": false,
  "available_in_polly": false,
  "available_in_insights_heavy": false,
  "available_in_insights_light": false,
  ...
}

Note the defaults: new configurations are enabled in Playground and Evaluators but not in Fleet (agent-builder), Polly, or Insights.

List configurations

curl "$BASE_URL/api/v1/playground-settings" \
  -H "X-API-Key: $LS_API_KEY"

Get a single configuration

curl "$BASE_URL/api/v1/playground-settings/{id}" \
  -H "X-API-Key: $LS_API_KEY"

Control feature availability

Use PATCH to enable or disable a configuration for specific features:

curl -X PATCH "$BASE_URL/api/v1/playground-settings/{id}" \
  -H "X-API-Key: $LS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "available_in_agent_builder": true,
    "available_in_polly": true,
    "available_in_insights_heavy": true,
    "available_in_insights_light": true
  }'

All availability fields:

Field	Feature
`available_in_playground`	Playground
`available_in_evaluators`	Evaluators
`available_in_agent_builder`	Fleet
`available_in_polly`	Polly
`available_in_insights_heavy`	Insights (Thinking)
`available_in_insights_light`	Insights (Summarization)

You can also update name, description, and settings in the same PATCH call.

Delete a configuration

curl -X DELETE "$BASE_URL/api/v1/playground-settings/{id}" \
  -H "X-API-Key: $LS_API_KEY"

Set the default model for a feature

To set the model that is pre-selected when a user opens a feature, use the platform features API.

# Set default for Polly
curl -X PUT "$BASE_URL/v1/platform/features/polly/default-model" \
  -H "X-API-Key: $LS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "abc12345-..."}'

The model value can be either:

The id UUID of a configuration you created via /api/v1/playground-settings
A built-in model ID string (e.g. "anthropic:claude-sonnet-4-6")

Returns HTTP 204 on success.

Valid feature names:

Feature name	Maps to
`playground`	Playground
`evaluators`	Evaluators
`agent-builder`	Fleet
`polly`	Polly
`insights-heavy`	Insights (Thinking)
`insights-light`	Insights (Summarization)

Get current feature defaults

curl "$BASE_URL/v1/platform/features" \
  -H "X-API-Key: $LS_API_KEY"

Returns an array of { feature, default_model, disabled_models } objects.

Clear a feature default

curl -X DELETE "$BASE_URL/v1/platform/features/polly/default-model" \
  -H "X-API-Key: $LS_API_KEY"

Returns HTTP 204 on success.

Full example: create a config and set it as the Polly default

# 1. Create the configuration
CONFIG_ID=$(curl -s -X POST "$BASE_URL/api/v1/playground-settings" \
  -H "X-API-Key: $LS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-proxy-model",
    "settings_type": "simple",
    "settings": {
      "modelId": "openai:gpt-4o",
      "envVarName": "MY_PROXY_API_KEY",
      "baseUrl": "https://your-proxy.example.com/v1"
    }
  }' | jq -r '.id')

# 2. Enable it for Polly and Insights
curl -X PATCH "$BASE_URL/api/v1/playground-settings/$CONFIG_ID" \
  -H "X-API-Key: $LS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "available_in_polly": true,
    "available_in_insights_heavy": true,
    "available_in_insights_light": true
  }'

# 3. Set it as the Polly default
curl -X PUT "$BASE_URL/v1/platform/features/polly/default-model" \
  -H "X-API-Key: $LS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$CONFIG_ID\"}"

Notes

This API is available on both Cloud (US and EU) and self-hosted deployments.
The Swagger/ReDoc page lists the existence of playground-settings but does not document the request/response schema in full - use this article as the reference until official docs are published.