> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.modular.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create deployment

> Create a new dedicated inference endpoint. `name` and `model_id` are immutable after creation.

> **Not yet available.** Self-serve deployment creation is coming soon. [Sign up for private preview access](https://console.modular.com/signup) to be notified when it launches.



## OpenAPI

````yaml /reference/openapi-deployments.json post /v1/deployments
openapi: 3.1.0
info:
  title: Modular Cloud Deployments API
  version: 0.1.0
  description: >-
    REST API for Modular Cloud deployments. All endpoints are served at
    `https://api.modular.com`.


    Create and manage dedicated inference endpoints on Modular Cloud
    infrastructure.


    > **Not yet available.** Self-serve deployment is coming soon. [Sign up for
    private preview access](https://console.modular.com/signup) to be notified
    when it launches.
servers:
  - url: https://api.modular.com
security:
  - BearerAuth: []
tags:
  - name: Deployments
    description: >-
      Create and manage dedicated inference endpoints on Modular Cloud
      infrastructure.


      > **Not yet available.** Self-serve deployment is coming soon. [Sign up
      for private preview access](https://console.modular.com/signup) to be
      notified when it launches.
paths:
  /v1/deployments:
    post:
      tags:
        - Deployments
      summary: Create deployment
      description: >-
        Create a new dedicated inference endpoint. `name` and `model_id` are
        immutable after creation.


        > **Not yet available.** Self-serve deployment creation is coming soon.
        [Sign up for private preview access](https://console.modular.com/signup)
        to be notified when it launches.
      operationId: createDeployment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
            example:
              name: my-gemma-deployment
              model_id: google/gemma-4-31B-it
              region_group: us
              scaling:
                min_replicas: 1
                max_replicas: 3
              configuration:
                model_path: google/gemma-4-31B-it
                engine: max
      responses:
        '200':
          description: Deployment created. `endpoint_url` is null while provisioning.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponse'
              example:
                name: my-gemma-deployment
                model_id: google/gemma-4-31B-it
                status: deploying
                endpoint_url: null
                region_group: us
                scaling:
                  min_replicas: 1
                  max_replicas: 3
                configuration:
                  model_path: google/gemma-4-31B-it
                  engine: max
                deployment_id: cpa9k2xyz
                created_at: '2026-04-24T00:00:00Z'
                created_by: user@example.com
                updated_at: '2026-04-24T00:00:00Z'
                updated_by: user@example.com
      x-codeSamples:
        - lang: Python
          label: Python
          source: |-
            import os
            import requests

            response = requests.post(
                "https://api.modular.com/v1/deployments",
                headers={
                    "Authorization": f"Bearer {os.environ['MODULAR_API_KEY']}",
                    "Content-Type": "application/json",
                },
                json={
                    "name": "my-gemma-deployment",
                    "model_id": "google/gemma-4-31B-it",
                    "region_group": "us",
                    "scaling": {"min_replicas": 1, "max_replicas": 3},
                    "configuration": {
                        "model_path": "google/gemma-4-31B-it",
                        "engine": "max",
                    },
                },
            )

            deployment = response.json()
            print(deployment["status"])
        - lang: Shell
          label: curl
          source: |-
            curl -X POST https://api.modular.com/v1/deployments \
              -H "Authorization: Bearer $MODULAR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "name": "my-gemma-deployment",
                "model_id": "google/gemma-4-31B-it",
                "region_group": "us",
                "scaling": {"min_replicas": 1, "max_replicas": 3},
                "configuration": {
                  "model_path": "google/gemma-4-31B-it",
                  "engine": "max"
                }
              }'
components:
  schemas:
    CreateDeploymentRequest:
      type: object
      properties:
        name:
          type: string
          description: URL-safe slug, max 50 characters. Immutable after creation.
          pattern: ^[a-z][a-z0-9-]{0,49}$
          maxLength: 50
        display_name:
          type: string
          description: Human-readable label for the deployment.
        model_id:
          type: string
          description: >-
            Model identifier from the console Models page. Immutable after
            creation.
          example: google/gemma-4-31B-it
        region_group:
          type: string
          enum:
            - us
            - eu
            - global
          description: Geographic region group for the deployment.
        scaling:
          $ref: '#/components/schemas/CreateDeploymentScaling'
        configuration:
          $ref: '#/components/schemas/CreateDeploymentConfiguration'
      required:
        - name
        - model_id
        - configuration
    DeploymentResponse:
      type: object
      properties:
        name:
          type: string
          description: Deployment name (the URL-safe slug).
        display_name:
          type: string
        deployment_id:
          type: string
          description: Unique deployment identifier.
        model_id:
          type: string
          description: Model identifier.
        status:
          $ref: '#/components/schemas/DeploymentStatus'
        endpoint_url:
          type: string
          nullable: true
          description: Inference endpoint URL. Null until the deployment is running.
        region_group:
          type: string
        scaling:
          $ref: '#/components/schemas/DeploymentScaling'
        configuration:
          $ref: '#/components/schemas/DeploymentConfiguration'
        replicas:
          $ref: '#/components/schemas/ReplicaStatus'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
      required:
        - name
        - deployment_id
        - model_id
        - status
        - scaling
        - configuration
        - created_at
        - created_by
        - updated_at
        - updated_by
    CreateDeploymentScaling:
      type: object
      properties:
        min_replicas:
          type: integer
        max_replicas:
          type: integer
        behavior:
          $ref: '#/components/schemas/ScalingBehavior'
    CreateDeploymentConfiguration:
      type: object
      properties:
        model_path:
          type: string
        engine:
          type: string
        mode:
          type: string
      required:
        - model_path
    DeploymentStatus:
      type: string
      enum:
        - unknown
        - non-deployed
        - deploying
        - running
        - unhealthy
        - failed
        - updating
        - scaling
        - terminating
        - terminated
        - image-building
        - image-build-failed
        - model-seed-failed
        - image-build-succeeded
        - scaled-to-zero
        - scaling-up
        - scaling-down
      description: Current lifecycle status of a deployment.
    DeploymentScaling:
      type: object
      properties:
        min_replicas:
          type: integer
          description: Minimum number of running replicas.
        max_replicas:
          type: integer
          description: Maximum number of running replicas.
        behavior:
          $ref: '#/components/schemas/ScalingBehavior'
      required:
        - min_replicas
        - max_replicas
    DeploymentConfiguration:
      type: object
      properties:
        model_path:
          type: string
          description: >-
            Model identifier passed to the inference engine (typically the same
            as `model_id`).
        engine:
          type: string
          description: Inference engine. Use `"max"` for the MAX engine.
          example: max
        mode:
          type: string
          description: Optional deployment mode override.
      required:
        - model_path
    ReplicaStatus:
      type: object
      properties:
        current:
          type: integer
          description: Number of currently running replicas.
        desired:
          type: integer
          description: Number of desired replicas.
      required:
        - current
        - desired
    ScalingBehavior:
      type: object
      properties:
        scale_up:
          $ref: '#/components/schemas/ScalingWindowConfig'
        scale_down:
          $ref: '#/components/schemas/ScalingWindowConfig'
    ScalingWindowConfig:
      type: object
      properties:
        stabilization_window_seconds:
          type: integer
          description: Seconds to wait before acting on scale signals.
      required:
        - stabilization_window_seconds
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Modular Cloud API token. Obtain from the [API Tokens
        page](https://console.modular.com/api_tokens).

````