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

# Deploy a built agent image

> Deploy a successfully built agent image to Kubernetes as a Helm release.

Takes a completed build (referenced by `build_id`, or by `image_name` +
`image_tag`) together with the agent manifest and environment config, then
starts an asynchronous Temporal workflow that provisions the agent as a Helm
release. The call returns immediately with the deployment record in `PENDING`
status — it does not wait for the release to become healthy; poll
`GET /v5/agentex/deployments/{deployment_id}` for status and Kubernetes events
and `GET /v5/agentex/deployments/{deployment_id}/logs` for progress. This is the
deploy counterpart to `POST /v5/agentex/builds`: a build produces the container
image, a deployment runs that image. The referenced build must have finished
successfully, and the manifest's agent name must match the build's agent.

Set `preview=True` for an ephemeral deployment: it gets a globally unique Helm
release name (so concurrent redeploys never collide), an optional `preview_label`
for grouping, and an expiry (`expires_at`, defaulting to 8 hours from now);
`preview_label` and `expires_at` are rejected on non-preview deploys. A
non-preview (production) deploy instead supersedes any prior active deployment
that shares its Helm release name. Fails with a client error if the build is
missing or not in a successful state, if the manifest or environment YAML is
invalid or their agent names disagree, or if a secret referenced by the manifest
does not exist. Returns 409 if the target agent has an active key migration or
an applicable incomplete managed-key handoff.



## OpenAPI

````yaml /openapi/v5.yaml post /v5/agentex/deployments
openapi: 3.1.0
info:
  title: EGP API V5
  description: >-
    This is the parent API for all EGP APIs. If you are looking for the EGP API,
    please go to https://api.egp.scale.com/docs.
  contact:
    name: Scale Generative AI Platform
    url: https://scale.com/genai-platform
  version: 0.1.0
servers:
  - url: https://api.egp.scale.com
security: []
paths:
  /v5/agentex/deployments:
    post:
      tags:
        - Agentex Cloud Deploy
      summary: Deploy a built agent image
      description: >-
        Deploy a successfully built agent image to Kubernetes as a Helm release.


        Takes a completed build (referenced by `build_id`, or by `image_name` +

        `image_tag`) together with the agent manifest and environment config,
        then

        starts an asynchronous Temporal workflow that provisions the agent as a
        Helm

        release. The call returns immediately with the deployment record in
        `PENDING`

        status — it does not wait for the release to become healthy; poll

        `GET /v5/agentex/deployments/{deployment_id}` for status and Kubernetes
        events

        and `GET /v5/agentex/deployments/{deployment_id}/logs` for progress.
        This is the

        deploy counterpart to `POST /v5/agentex/builds`: a build produces the
        container

        image, a deployment runs that image. The referenced build must have
        finished

        successfully, and the manifest's agent name must match the build's
        agent.


        Set `preview=True` for an ephemeral deployment: it gets a globally
        unique Helm

        release name (so concurrent redeploys never collide), an optional
        `preview_label`

        for grouping, and an expiry (`expires_at`, defaulting to 8 hours from
        now);

        `preview_label` and `expires_at` are rejected on non-preview deploys. A

        non-preview (production) deploy instead supersedes any prior active
        deployment

        that shares its Helm release name. Fails with a client error if the
        build is

        missing or not in a successful state, if the manifest or environment
        YAML is

        invalid or their agent names disagree, or if a secret referenced by the
        manifest

        does not exist. Returns 409 if the target agent has an active key
        migration or

        an applicable incomplete managed-key handoff.
      operationId: POST-V5-/agentex/deployments
      parameters:
        - name: x-selected-account-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentexCloudDeployCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentexCloudDeploy'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AgentexCloudDeployCreateRequest:
      properties:
        build_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Build Id
          description: >-
            The build_id of the cloud build. Required if image_name and
            image_tag are not provided.
        manifest_file:
          type: string
          title: Manifest File
          description: YAML content of manifest configuration.
        environment_config:
          type: string
          title: Environment Config
          description: >-
            YAML content of environment configuration from the environment
            config file.
        image_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Name
          description: Name of the image to deploy. Required if build_id is not provided.
        image_tag:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Tag
          description: Tag of the image to deploy. Required if build_id is not provided.
        preview:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Preview
          description: >-
            When True, creates a preview deployment with a unique deployment-id
            suffix appended to the helm release name.
          default: false
        preview_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Preview Label
          description: >-
            Non-unique grouping label for the preview (e.g. branch name, PR
            number). Persisted on the deployment record so callers can list all
            deploys for a given label via `GET
            /v5/agentex/deployments?preview_label=X` (add
            `sort_order=desc&limit=1` for the latest). Sanitized to lowercase
            alphanumeric + hyphens for K8s DNS-label compatibility (max 30
            characters after sanitization). Each deploy still gets a unique helm
            release name regardless of label, so concurrent redeploys never
            share K8s resources. Only valid when preview=True.
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
          description: >-
            ISO 8601 expiry timestamp. Only valid for preview deployments. If
            omitted on a preview deployment, defaults to 8 hours from now.
            Previews are always ephemeral and always have an expires_at.
      type: object
      required:
        - manifest_file
        - environment_config
      title: AgentexCloudDeployCreateRequest
    AgentexCloudDeploy:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the deployment.
        object:
          type: string
          const: agentex_cloud_deploy
          title: Object
          default: agentex_cloud_deploy
        build_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Build Id
          description: The build_id of the cloud build that produced the deployed image.
        image_digest:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Digest
          description: >-
            Registry manifest digest of the deployed image, served from the
            linked build record. Null when the build recorded no digest.
        namespace:
          type: string
          title: Namespace
          description: Kubernetes namespace where the deployment is deployed.
        helm_release_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Helm Release Name
          description: Helm release name after successful deployment.
        manifest_file:
          type: string
          title: Manifest File
          description: YAML content of manifest configuration.
        environment_config:
          type: string
          title: Environment Config
          description: >-
            YAML content of environment configuration from the environment
            config file.
        status:
          type: string
          title: Status
          description: >-
            Deployment status: pending, running, completed, failed, or
            cancelled.
        account_id:
          type: string
          title: Account Id
          description: The ID of the account that owns the given entity.
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
          description: >-
            When this deployment will be cleaned up. Always set on preview
            deployments (defaults to 8 hours from creation if the request omits
            it). Null on non-preview deployments — they have no TTL.
        preview_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Preview Label
          description: >-
            Non-unique grouping label for preview deployments. Filter
            `?preview_label=X&sort_order=desc&limit=1` returns the latest deploy
            for the label. Sanitized (lowercase alphanumeric + hyphens) and
            capped at 30 characters.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the entity was created in ISO format.
        created_by:
          $ref: '#/components/schemas/Identity'
          description: The identity that created the entity.
        deploy_events:
          items:
            $ref: '#/components/schemas/AgentexCloudDeployEvent'
          type: array
          title: Deploy Events
          description: Kubernetes events for this deployment.
      type: object
      required:
        - id
        - namespace
        - manifest_file
        - environment_config
        - status
        - account_id
        - created_at
        - created_by
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Identity:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: identity
          title: Object
          default: identity
        type:
          $ref: '#/components/schemas/IdentityType'
      type: object
      required:
        - id
        - type
      title: Identity
    AgentexCloudDeployEvent:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: Event type, e.g. 'Normal' or 'Warning'.
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: Short reason, e.g. 'Pulling', 'Scheduled'.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Full event message.
        timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Timestamp
          description: When the event was observed.
      type: object
      title: AgentexCloudDeployEvent
      description: Slim event representation for the API response.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    IdentityType:
      type: string
      enum:
        - user
        - service_account
      title: IdentityType
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````