Context

The LangSmith Control Plane API allows you to programmatically manage deployments, including listing existing deployments and creating new ones. This is useful for automation and CI/CD workflows where you need to interact with the platform without using the web UI.

Answer

API Authentication Requirements

To use the Control Plane API, you need:

1. An organization-level API key with admin role (not a personal or project-level key)

2. The workspace/tenant ID if working with specific workspaces

Generate your API key from LangSmith UI: Settings → Organization Settings → API Keys

API Endpoint Structure

The Control Plane API endpoints follow this pattern:

https://your-platform-url/api-host/v2/deployments

Required Headers

All API requests must include these headers:

• X-Api-Key: Your organization-level API key

• Content-Type: application/json

• X-Tenant-Id: Your workspace ID (when working with specific workspaces)

Listing Deployments

Use this Python script to list deployments:

#!/usr/bin/env python3
import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_BASE_URL = "https://your-platform-url/api-host/v2"
API_KEY = os.environ["LANGSMITH_API_KEY"]
WORKSPACE_ID = "your-workspace-id"

def list_deployments(name_contains=None):
    headers = {
        "X-Api-Key": API_KEY,
        "X-Tenant-Id": WORKSPACE_ID,
        "Content-Type": "application/json",
    }

    params = {}
    if name_contains:
        params["name_contains"] = name_contains

    resp = requests.get(f"{API_BASE_URL}/deployments", headers=headers, params=params)

    if resp.status_code == 200:
        return resp.json()
    else:
        raise RuntimeError(f"Failed: {resp.status_code} - {resp.text}")

if __name__ == "__main__":
    data = list_deployments()
    for d in data.get("resources", []):
        print(f"{d.get('id'):<20} {d.get('name')}")

Creating Deployments with Docker Images

To create a deployment using a pre-built Docker image, use the external_docker source type, for example

request_body = {
    "name": "my-deployment",
    "source": "external_docker",
    "source_config": {
        "integration_id": None,
        "repo_url": None,
        "deployment_type": None,
        "build_on_push": None,
        "custom_url": None,
        "resource_spec": {
            "min_scale": 1,
            "max_scale": 1,
            "cpu": 1,
            "memory_mb": 1024,
        },
    },
    "source_revision_config": {
        "repo_ref": None,
        "langgraph_config_path": None,
        "image_uri": "your-docker-image:tag",
    },
    "secrets": [
        {
            "name": "OPENAI_API_KEY",
            "value": "your-api-key",
        }
    ],
}

Common Issues and Solutions

403 Forbidden Error

If you receive a 403 Forbidden error:

• Verify you're using an organization-level API key with admin role

• Ensure you're including the Content-Type: application/json header

• Check that you're using the correct API endpoint with /api-host/v2/ prefix

• Include the X-Tenant-Id header with your workspace ID

HTML Response Instead of JSON

If you receive HTML instead of JSON, you're likely hitting the wrong endpoint. Make sure to use /api-host/v2/deployments instead of just /v2/deployments.

For more information, refer to the LangSmith Control Plane API reference and organization management documentation.