Scale AI Agentex Cloud Deploy API

openapi: 3.2.0
info:
  title: EGP API V5 Agentex Cloud Deploy API
  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: []
tags:
- name: Agentex Cloud Deploy
paths:
  /v5/agentex/deployments/{deployment_id}:
    delete:
      tags:
      - Agentex Cloud Deploy
      summary: Delete and tear down a deployment
      description: 'Delete an agent deployment and tear down its Kubernetes resources.


        Deletes the deployment''s Kubernetes resources first, then marks the record as

        `DELETED`; the underlying Helm release is subsequently uninstalled

        asynchronously by FluxCD once the resource is removed. If the Kubernetes teardown

        fails, the record is left unchanged and the call errors, so the delete can be

        safely retried. Rejects the call with a client error if the deployment is already

        in a terminal state (`DELETED`, `CANCELLED`, or `SUPERSEDED`) — a `SUPERSEDED`

        record shares its Helm release with the deployment that replaced it, so deleting

        it would tear down the live release. Returns 404 if no deployment with this ID

        exists for the caller''s account. This removes a running deployment, not the image

        build behind it, which is managed separately through the agentex builds API.'
      operationId: DELETE-V5-/agentex/deployments/deployment_id
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          title: Deployment Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      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: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-deploy/delete-and-tear-down-a-deployment
    get:
      tags:
      - Agentex Cloud Deploy
      summary: Get an agent deployment
      description: 'Get a single agent deployment by ID, including its current status and Kubernetes events.


        Returns the deployment record with its latest status and the associated

        Kubernetes events (`deploy_events`) observed for the release, which are useful

        for diagnosing why a deployment is still pending or unhealthy. Poll this after

        `POST /v5/agentex/deployments` to track the asynchronous deploy to completion.

        For the incremental log output rather than status and events, use

        `GET /v5/agentex/deployments/{deployment_id}/logs`. Returns 404 if no deployment

        with this ID exists for the caller''s account.'
      operationId: GET-V5-/agentex/deployments/deployment_id
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          title: Deployment Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      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: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-deploy/get-an-agent-deployment
  /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.'
      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: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-deploy/deploy-a-built-agent-image
    get:
      tags:
      - Agentex Cloud Deploy
      summary: List agent deployments
      description: 'List the account''s agent deployments, with pagination and optional filters.


        Returns the deployments the caller is authorized to read. Optionally filter by

        `build_id`, by `agent_name` (matched through each deployment''s associated build),

        or by `preview_label`. A `preview_label` is non-unique — many deployments can

        share one (for example every deploy for a branch) — so combine it with `limit=1`

        to fetch the latest deployment for that label. This lists deployments (the running

        or attempted agent instances); to list the image builds they run, use the agentex

        builds API.'
      operationId: GET-V5-/agentex/deployments
      parameters:
      - name: build_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter deployments by build ID
          title: Build Id
        description: Filter deployments by build ID
      - name: agent_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter deployments by agent name (via associated build)
          title: Agent Name
        description: Filter deployments by agent name (via associated build)
      - name: preview_label
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter deployments by preview label (e.g. branch name). The label is non-unique — many deployments can share it. Combine with limit=1 to get the latest deploy for that label.
          title: Preview Label
        description: Filter deployments by preview label (e.g. branch name). The label is non-unique — many deployments can share it. Combine with limit=1 to get the latest deploy for that label.
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: ending_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ending Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          default: 100
          title: Limit
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          default: asc
          title: Sort Order
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_AgentexCloudDeploy_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-deploy/list-agent-deployments
  /v5/agentex/deployments/{deployment_id}/logs:
    get:
      tags:
      - Agentex Cloud Deploy
      summary: Get agent deployment logs
      description: 'Get structured deployment log lines, with cursor-based pagination.


        Returns the deployment''s log lines in time order together with a `next_cursor`

        and a `has_more` flag. Poll to stream logs incrementally: make the first call

        without a cursor, then pass the previous response''s `next_cursor` as `cursor` on

        each subsequent call, stopping once the deployment reaches a terminal status.

        Unlike `GET /v5/agentex/deployments/{deployment_id}`, which returns the

        deployment''s status and Kubernetes events, this returns the raw log output from

        the deploy process. Returns 404 if no deployment with this ID exists for the

        caller''s account.'
      operationId: GET-V5-/agentex/deployments/deployment_id/logs
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          title: Deployment Id
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          description: Cursor from previous response's next_cursor field
          default: ''
          title: Cursor
        description: Cursor from previous response's next_cursor field
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Maximum number of log lines to return
          default: 100
          title: Limit
        description: Maximum number of log lines to return
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentexCloudDeployLogsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-deploy/get-agent-deployment-logs
components:
  schemas:
    AgentexCloudDeployLog:
      properties:
        id:
          type: string
          title: Id
          description: Unique log line identifier (time-ordered)
        timestamp:
          title: Timestamp
          description: Parsed K8s log timestamp
          type: string
          format: date-time
        log_level:
          type: string
          title: Log Level
          description: Parsed log level (INFO, ERROR, WARN, DEBUG, FATAL)
          default: INFO
        message:
          type: string
          title: Message
          description: Log line content after the K8s timestamp
      type: object
      required:
      - id
      - message
      title: AgentexCloudDeployLog
      description: A single structured log line from the deployment process.
    IdentityType:
      type: string
      enum:
      - user
      - service_account
      title: IdentityType
    PaginatedList_AgentexCloudDeploy_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/AgentexCloudDeploy'
          type: array
          title: Items
        limit:
          type: integer
          title: Limit
          description: The maximum number of items to return.
          default: 100
        total:
          type: integer
          title: Total
          description: The total of items that match the query. This is greater than or equal to the number of items returned.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items left to be fetched.
      type: object
      required:
      - items
      - total
      - has_more
    AgentexCloudDeployCreateRequest:
      properties:
        build_id:
          title: Build Id
          description: The build_id of the cloud build. Required if image_name and image_tag are not provided.
          type: string
        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:
          title: Image Name
          description: Name of the image to deploy. Required if build_id is not provided.
          type: string
        image_tag:
          title: Image Tag
          description: Tag of the image to deploy. Required if build_id is not provided.
          type: string
        preview:
          title: Preview
          description: When True, creates a preview deployment with a unique deployment-id suffix appended to the helm release name.
          default: false
          type: boolean
        preview_label:
          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&limit=1` (get 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.
          type: string
        expires_at:
          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: string
          format: date-time
      type: object
      required:
      - manifest_file
      - environment_config
      title: AgentexCloudDeployCreateRequest
    AgentexCloudDeployLogsResponse:
      properties:
        deployment_id:
          type: string
          title: Deployment Id
          description: The deployment ID
        lines:
          items:
            $ref: '#/components/schemas/AgentexCloudDeployLog'
          type: array
          title: Lines
          description: Structured log lines
        next_cursor:
          type: string
          title: Next Cursor
          description: Cursor for the next page. Pass this as the after_id query parameter to get subsequent logs.
          default: ''
        has_more:
          type: boolean
          title: Has More
          description: True if there may be more lines beyond this page (len(lines) == limit).
      type: object
      required:
      - deployment_id
      - has_more
      title: AgentexCloudDeployLogsResponse
      description: 'Response containing structured deployment log lines with cursor-based pagination.


        The CLI can poll this endpoint to stream logs incrementally:

        1. First call: no after_id

        2. Subsequent calls: after_id=next_cursor from previous response

        3. Stop polling when has_more is False and the deployment reaches a terminal status'
    AgentexCloudDeployEvent:
      properties:
        type:
          title: Type
          description: Event type, e.g. 'Normal' or 'Warning'.
          type: string
        reason:
          title: Reason
          description: Short reason, e.g. 'Pulling', 'Scheduled'.
          type: string
        message:
          title: Message
          description: Full event message.
          type: string
        timestamp:
          title: Timestamp
          description: When the event was observed.
          type: string
          format: date-time
      type: object
      title: AgentexCloudDeployEvent
      description: Slim event representation for the API response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          title: Error Type
          type: string
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    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
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    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:
          title: Build Id
          description: The build_id of the cloud build that produced the deployed image.
          type: string
        namespace:
          type: string
          title: Namespace
          description: Kubernetes namespace where the deployment is deployed.
        helm_release_name:
          title: Helm Release Name
          description: Helm release name after successful deployment.
          type: string
        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:
          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.
          type: string
          format: date-time
        preview_label:
          title: Preview Label
          description: Non-unique grouping label for preview deployments. Filter `?preview_label=X&limit=1` returns the latest deploy for the label. Sanitized (lowercase alphanumeric + hyphens) and capped at 30 characters.
          type: string
        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
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
x-assembled-from: Per-operation OpenAPI fragments embedded verbatim in docs.gp.scale.com reference pages; source spec https://api.sgp.scale.com/openapi-versions/v5/openapi.json (404 when assembled)