The Deployments (v2) API from LangGraph — 5 operation(s) for deployments (v2).
openapi: 3.1.0
info:
title: LangSmith Deployment Control Plane Agent Connections (v2) Agent Connections (v2) Deployments (v2) API
description: 'The LangSmith Deployment Control Plane API is used to programmatically create and manage
Agent Server deployments. For example, the APIs can be orchestrated to
create custom CI/CD workflows.
## Host
https://api.host.langchain.com
## Authentication
To authenticate with the LangSmith Deployment Control Plane API, set the `X-Api-Key` header
to a valid [LangSmith API key](https://docs.langchain.com/langsmith/create-account-api-key#create-an-api-key).
## Versioning
Each endpoint path is prefixed with a version (e.g. `v1`, `v2`).
## Quick Start
1. Call `POST /v2/deployments` to create a new Deployment. The response body contains the Deployment ID (`id`) and the ID of the latest (and first) revision (`latest_revision_id`).
1. Call `GET /v2/deployments/{deployment_id}` to retrieve the Deployment. Set `deployment_id` in the URL to the value of Deployment ID (`id`).
1. Poll for revision `status` until `status` is `DEPLOYED` by calling `GET /v2/deployments/{deployment_id}/revisions/{latest_revision_id}`.
1. Call `PATCH /v2/deployments/{deployment_id}` to update the deployment.
'
version: 0.1.0
tags:
- name: Deployments (v2)
paths:
/v2/deployments:
get:
tags:
- Deployments (v2)
summary: List Deployments
description: List all deployments.
operationId: list_deployments_v2_deployments_get
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Maximum number of resources to return.
default: 20
title: Limit
description: Maximum number of resources to return.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Pagination offset. Pass this value to subsequent requests to fetch the next page of resources.
default: 0
title: Offset
description: Pagination offset. Pass this value to subsequent requests to fetch the next page of resources.
- name: name_contains
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Name of the deployment to filter by.
title: Name Contains
description: Name of the deployment to filter by.
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: '`status` of the deployment to filter by.'
title: Status
description: '`status` of the deployment to filter by.'
- name: remote_reconciled
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Flag to filter by remote reconciled deployments.
title: Remote Reconciled
description: Flag to filter by remote reconciled deployments.
- name: tag_value_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma separated list of tag value IDs of the deployment to filter by.
title: Tag Value Ids
description: Comma separated list of tag value IDs of the deployment to filter by.
- name: image_version
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Image version to filter by.
title: Image Version
description: Image version to filter by.
- name: deployment_type
in: query
required: false
schema:
anyOf:
- enum:
- dev_free
- dev
- prod
type: string
- type: 'null'
description: Deployment type to filter by.
title: Deployment Type
description: Deployment type to filter by.
- name: deployment_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma separated list of deployment IDs to filter by.
title: Deployment Ids
description: Comma separated list of deployment IDs to filter by.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentsList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Deployments (v2)
summary: Create Deployment
description: Create a new deployment.
operationId: create_deployment_v2_deployments_post
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentCreateRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
'400':
description: Bad Request
content:
application/json:
example:
detail: Error description.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Deployments (v2)
summary: Delete Deployments
description: "Delete multiple deployments with partial success support.\n\nReturns:\n - 200: All deployments deleted successfully\n - 207: Some deployments deleted successfully, some failed"
operationId: delete_deployments_v2_deployments_delete
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: deployment_ids
in: query
required: true
schema:
type: array
items:
type: string
format: uuid
maxItems: 100
title: Deployment Ids
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'404':
description: Not Found
content:
application/json:
example:
detail: Deployment ID {deployment_id} not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v2/deployments/{deployment_id}:
get:
tags:
- Deployments (v2)
summary: Get Deployment
description: Get a deployment by ID.
operationId: get_deployment_v2_deployments__deployment_id__get
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: deployment_id
in: path
required: true
schema:
type: string
format: uuid
title: Deployment ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
'404':
description: Not Found
content:
application/json:
example:
detail: Deployment ID {deployment_id} not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Deployments (v2)
summary: Patch Deployment
description: Patch a deployment by ID.
operationId: patch_deployment_v2_deployments__deployment_id__patch
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: deployment_id
in: path
required: true
schema:
type: string
format: uuid
title: Deployment ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentPatchRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
'404':
description: Not Found
content:
application/json:
example:
detail: Deployment ID {deployment_id} not found.
'400':
description: Bad Request
content:
application/json:
example:
detail: Error description.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Deployments (v2)
summary: Delete Deployment
description: Delete a deployment by ID.
operationId: delete_deployment_v2_deployments__deployment_id__delete
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: deployment_id
in: path
required: true
schema:
type: string
format: uuid
title: Deployment ID
- name: delete_tracing_project
in: query
required: false
schema:
type: boolean
description: Optionally delete tracing project for the deployment.
default: false
title: Delete Tracing Project
description: Optionally delete tracing project for the deployment.
responses:
'204':
description: Successful Response
'404':
description: Not Found
content:
application/json:
example:
detail: Deployment ID {deployment_id} not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v2/deployments/{deployment_id}/revisions:
get:
tags:
- Deployments (v2)
summary: List Revisions
description: List all revisions for a deployment.
operationId: list_revisions_v2_deployments__deployment_id__revisions_get
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: deployment_id
in: path
required: true
schema:
type: string
format: uuid
title: Deployment ID
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Maximum number of resources to return.
default: 20
title: Limit
description: Maximum number of resources to return.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Pagination offset. Pass this value to subsequent requests to fetch the next page of resources.
default: 0
title: Offset
description: Pagination offset. Pass this value to subsequent requests to fetch the next page of resources.
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma separated list of revision `status` (CREATING, QUEUED, AWAITING_BUILD, BUILDING, AWAITING_DEPLOY, DEPLOYING, CREATE_FAILED, BUILD_FAILED, DEPLOY_FAILED, DEPLOYED, SKIPPED, INTERRUPTED, UNKNOWN) fields to filter by.
title: Status
description: Comma separated list of revision `status` (CREATING, QUEUED, AWAITING_BUILD, BUILDING, AWAITING_DEPLOY, DEPLOYING, CREATE_FAILED, BUILD_FAILED, DEPLOY_FAILED, DEPLOYED, SKIPPED, INTERRUPTED, UNKNOWN) fields to filter by.
- name: remote_reconciled
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Flag to filter by remote reconciled revisions.
title: Remote Reconciled
description: Flag to filter by remote reconciled revisions.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RevisionsList'
'404':
description: Not Found
content:
application/json:
example:
detail: Deployment ID {deployment_id} not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v2/deployments/{deployment_id}/revisions/{revision_id}:
get:
tags:
- Deployments (v2)
summary: Get Revision
description: Get a revision by ID for a deployment.
operationId: get_revision_v2_deployments__deployment_id__revisions__revision_id__get
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: deployment_id
in: path
required: true
schema:
type: string
format: uuid
title: Deployment ID
- name: revision_id
in: path
required: true
schema:
type: string
format: uuid
title: Revision ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Revision'
'404':
description: Not Found
content:
application/json:
example:
detail: Deployment ID {deployment_id} not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v2/deployments/{deployment_id}/revisions/{revision_id}/redeploy:
post:
tags:
- Deployments (v2)
summary: Redeploy Revision
description: Redeploy a specific revision ID.
operationId: redeploy_revision_v2_deployments__deployment_id__revisions__revision_id__redeploy_post
security:
- API Key: []
- Tenant ID: []
- Bearer Auth: []
parameters:
- name: deployment_id
in: path
required: true
schema:
type: string
format: uuid
title: Deployment ID
- name: revision_id
in: path
required: true
schema:
type: string
format: uuid
title: Revision ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
'404':
description: Not Found
content:
application/json:
example:
detail: Deployment ID {deployment_id} not found.
'400':
description: Bad Request
content:
application/json:
example:
detail: Error description.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
DeploymentsList:
properties:
resources:
items:
$ref: '#/components/schemas/Deployment'
type: array
title: Resources
offset:
type: integer
title: Offset
description: Pagination offset. Pass this value to subsequent requests to fetch the next page.
type: object
required:
- resources
- offset
title: DeploymentsList
Deployment:
properties:
name:
type: string
title: Name
description: Name of the deployment.<br><br>A LangSmith tracing project with the same name will also automatically be created. This cannot be changed once the deployment is created.
source:
type: string
enum:
- github
- external_docker
- internal_docker
- internal_source
title: Source
description: Deploy from a GitHub repository (`github`) or an external Docker image (`external_docker`).<br><br>Deploying from GitHub is only available for Cloud SaaS deployments. Deploying from an external Docker image is only available for self-hosted deployments. This cannot be changed once the deployment is created.
source_config:
$ref: '#/components/schemas/SourceConfig'
source_revision_config:
$ref: '#/components/schemas/SourceRevisionConfig'
secrets:
items:
$ref: '#/components/schemas/Secret'
type: array
title: Secrets
secret_references:
anyOf:
- items:
$ref: '#/components/schemas/SecretReference'
type: array
- type: 'null'
title: Secret References
description: List of Kubernetes Secret references.<br><br>Only applicable for `external_docker` source.
id:
type: string
format: uuid
title: ID
description: The ID of the deployment.<br><br>This is a read-only field.
tenant_id:
type: string
format: uuid
title: Tenant ID
description: The ID of the tenant that owns the deployment.<br><br>This is a read-only field.
created_at:
type: string
format: date-time
title: Created At
description: The creation time of the deployment.<br><br>This is a read-only field.
updated_at:
type: string
format: date-time
title: Updated At
description: The last update time of the deployment.<br><br>This is a read-only field.
status:
type: string
enum:
- AWAITING_DATABASE
- READY
- UNUSED
- AWAITING_DELETE
- UNKNOWN
title: Status
description: The status of the deployment.<br><br>This is a read-only field.
latest_revision_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Latest Revision ID
description: The ID of the latest revision of the deployment.<br><br>This is a read-only field.
active_revision_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Active Revision ID
description: The ID of the current (actively deployed) revision of the deployment.<br><br>This is a read-only field.
image_version:
anyOf:
- type: string
- type: 'null'
title: Image Version
description: Image version of the deployment.
type: object
required:
- name
- source
- source_config
- source_revision_config
- secrets
- id
- tenant_id
- created_at
- updated_at
- status
- latest_revision_id
- active_revision_id
title: Deployment
description: Deployment resource.
SourceRevisionConfig:
properties:
repo_ref:
anyOf:
- type: string
- type: 'null'
title: Repo Ref
description: 'The git ref of the repository used for the deployment.<br><br>Supports:<br>- **Branches**: Specify just the branch name (e.g., `main`, `develop`)<br>- **Tags**: Specify the full ref path (e.g., `refs/tags/v1.0.0`)<br><br>When using a tag, `source_config.build_on_push` must be set to `false` since tags are immutable.<br><br>When updating a deployment (`PATCH`), setting this field to a non-null value will trigger creation of a new revision. Only applicable for `github` source.'
langgraph_config_path:
anyOf:
- type: string
- type: 'null'
title: LangGraph Configuration Path
description: The path to the LangGraph configuration file (`langgraph.json`) used for the deployment.<br><br>Required on create for buildable sources (`github`, `internal_source`). Must be `null` for all other sources.<br><br>When updating a deployment (`PATCH`), setting this field to a non-null value will trigger creation of a new revision.
image_uri:
anyOf:
- type: string
- type: 'null'
title: Image URI
description: The URI of the Docker image used for the deployment.<br><br>When updating a deployment (`PATCH`), setting this field to a non-null value will trigger creation of a new revision. Applicable for `external_docker` source.
source_tarball_path:
anyOf:
- type: string
- type: 'null'
title: Source Tarball Path
description: The object path of the uploaded source tarball.<br><br>Must be an object path obtained from the `POST /deployments/{deployment_id}/upload-url` endpoint. Arbitrary paths are not accepted.<br><br>When updating a deployment (`PATCH`), setting this field to a non-null value will trigger creation of a new revision. Only applicable for `internal_source` source.
repo_commit_sha:
anyOf:
- type: string
- type: 'null'
title: Repo commit SHA
description: The commit SHA of the git repository used for the deployment.<br><br>This is a read-only field. Only applicable for `github` source.
type: object
title: SourceRevisionConfig
description: 'Source revision configuration.<br>
<br>
For a `Deployment` resource, the field values refer to the latest revision of the `Deployment`. For a `Revision` resource, the field values refer to the `Revision` itself.'
ResourceRequirements:
properties:
limits:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Limits
description: Limits describes the maximum amount of compute resources allowed.
requests:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Requests
description: Requests describes the minimum amount of compute resources required.
type: object
title: ResourceRequirements
description: Compute resource requirements.
Secret:
properties:
name:
type: string
title: Name
description: Name of the secret
value:
type: string
title: Value
description: Value of the secret
type: object
required:
- name
- value
title: Secret
description: 'Secret for a deployment.<br>
<br>
Secrets are accessible as environment variables in the deployment''s container. In addition to user-defined secrets, Agent Server supports [pre-defined environment variables](https://langchain-ai.github.io/langgraph/cloud/reference/env_var/) that can be configured to augment the functionality of a deployment. When updating a deployment (`PATCH`), setting this field to a non-null value will trigger creation of a new revision.'
LocalObjectReference:
properties:
name:
type: string
title: Name
description: Name of the referent (e.g., name of a Secret for imagePullSecrets).
type: object
required:
- name
title: LocalObjectReference
description: Reference to an object in the same namespace.
RevisionsList:
properties:
resources:
items:
$ref: '#/components/schemas/Revision'
type: array
title: Resources
offset:
type: integer
title: Offset
description: Pagination offset. Pass this value to subsequent requests to fetch the next page.
type: object
required:
- resources
- offset
title: RevisionsList
EnvVar:
properties:
name:
type: string
title: Name
description: Name of the environment variable. Must be a C_IDENTIFIER.
value:
anyOf:
- type: string
- type: 'null'
title: Value
description: Variable value. Defaults to empty string.
valueFrom:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Valuefrom
description: Source for the environment variable's value. Cannot be used if value is not empty.
type: object
required:
- name
title: EnvVar
description: Environment variable for a container.
SourceConfig:
properties:
integration_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Integration ID
description: The ID of the integration used for the deployment.<br><br>Retrieve this value from the `GET /v1/integrations/github/install` endpoint. This cannot be changed (`PATCH`) once the deployment is created. Only applicable for `github` source.
repo_url:
anyOf:
- type: string
- type: 'null'
title: Repository URL
description: The URL of the git repository used for the deployment.<br><br>This cannot be changed (`PATCH`) once the deployment is created. Only applicable for `github` source.
deployment_type:
anyOf:
- type: string
enum:
- dev_free
- dev
- prod
- type: 'null'
title: Deployment Type
description: The type of deployment to create.<br><br>See [Deployment Types](https://langchain-ai.github.io/langgraph/concepts/langgraph_control_plane/#deployment-types) for more details. This cannot be changed (`PATCH`) once the deployment is created. Only applicable for `github` source.
build_on_push:
anyOf:
- type: boolean
- type: 'null'
title: Build On Push
description: Whether to build a new revision for the deployment on push to the `source_revision_config.repo_ref` (e.g. git branch).<br><br>Cannot be enabled when `source_revision_config.repo_ref` specifies a tag (starts with `refs/tags/`). Tags are immutable and cannot trigger automatic builds on push.<br><br>Only applicable for `github` source.
custom_url:
anyOf:
- type: string
- type: 'null'
title: Custom URL
description: The custom URL of the deployment.<br><br>This field can only be set for `external_docker` source deployments. However, it will be set automatically for `github` source deployments (read only).
resource_spec:
anyOf:
- $ref: '#/components/schemas/ResourceSpec-Output'
- type: 'null'
listener_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Listener ID
description: The ID of the listener used for the deployment.<br><br>Retrieve this value from the `GET /v2/listeners` endpoint. This cannot be changed (`PATCH`) once the deployment is created. Only applicable for `external_docker` source.
listener_config:
anyOf:
- $ref: '#/components/schemas/ListenerConfig'
- type: 'null'
install_command:
anyOf:
- type: string
- type: 'null'
title: Install Command
description: The custom install command to run for your deployment. This only applies to JS deployments. This command will be run from the root of your repository - NOT where your langgraph.json file lives (unless these are the same place). If not provided, we will autodetect the command based on the presence of yarn/npm/etc. files.
build_command:
anyOf:
- type: string
- type: 'null'
title: Build Command
description: The custom build command to run for your deployment. This only applies to JS deployments. This command will be run from where your langgraph.json file lives. This is helpful for using shared workspaces in your deployments, without having to provide a postinstall command or something similar in your package.json.
type: object
title: SourceConfig
description: Source configuration.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ResourceSpec-Output:
properties:
min_scale:
anyOf:
- type: integer
- type: 'null'
title: Min Scale
description: The minimum scale (number of replicas) of the deployment.
max_scale:
anyOf:
- type: integer
- type: 'null'
title: Max Scale
description: The maximum scale (number of replicas) of the deployment.
cpu:
anyOf:
- type: number
maximum: 8.0
minimum: 0.1
- type: 'null'
title: CPU
description: CPU request in cores for a single replica of the deployment. Supports fractional values (e.g. 0.5 for 500m). Values are rounded to 1 decimal place. If cpu_limit is not set, limit defaults to 2x this value.
examples:
- 0.1
- 0.5
- 1
- 2
- 4
cpu_limit:
anyOf:
- type: number
maximum: 16.0
minimum: 0.1
- type: 'null'
title: CPU Limit
description: CPU limit in cores for a single replica of the deployment. Supports fractional values (e.g. 0.5 for 500m). Values are rounded to 1 decimal place. If not set, defaults to 2x cpu.
examples:
- 0.2
- 1
- 2
- 4
- 8
- 16
memory_mb:
anyOf:
- type: integer
- type: 'null'
title: Memory (MB)
description: Memory request (MB) of a single replica of the deployment. If memory_limit_mb is not set, limit defaults to 2x this value.
memory_limit_mb:
anyOf:
- type: integer
- type: 'null'
title: Memory Limit (MB)
description: Memory limit (MB) of a single replica of the deployment. If not set, defaults to 2x memory_mb.
queue_min_scale:
anyOf:
- type: integer
- type: 'null'
title: Queue Min Scale
description: The minimum scale (number of replicas) of the queue deployment. If not provided, defaults to the same value as `min_scale`.
queue_max_scale:
anyOf:
- type: integer
- type: 'null'
title: Queue Max Scale
description: The maximum scale (number of replicas
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/langgraph/refs/heads/main/openapi/langgraph-deployments-v2-api-openapi.yml