Scale AI Model Endpoints API

openapi: 3.2.0
info:
  title: launch Model Endpoints API
  version: 1.0.0
tags:
- name: Model Endpoints
paths:
  /v1/model-endpoints:
    post:
      summary: Create Model Endpoint
      description: Creates a Model for the current user.
      operationId: create_model_endpoint_v1_model_endpoints_post
      security:
      - HTTPBasic: []
      - OAuth2PasswordBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelEndpointV1Request'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateModelEndpointV1Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Model Endpoints
    get:
      summary: List Model Endpoints
      description: Lists the Models owned by the current owner.
      operationId: list_model_endpoints_v1_model_endpoints_get
      security:
      - HTTPBasic: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      - name: order_by
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ModelEndpointOrderBy'
          - type: 'null'
          title: Order By
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelEndpointsV1Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Model Endpoints
  /v1/model-endpoints/{model_endpoint_id}:
    get:
      summary: Get Model Endpoint
      description: Describe the Model endpoint with given ID.
      operationId: get_model_endpoint_v1_model_endpoints__model_endpoint_id__get
      security:
      - HTTPBasic: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: model_endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Model Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetModelEndpointV1Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Model Endpoints
    put:
      summary: Update Model Endpoint
      description: Updates the Model endpoint.
      operationId: update_model_endpoint_v1_model_endpoints__model_endpoint_id__put
      security:
      - HTTPBasic: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: model_endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Model Endpoint Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateModelEndpointV1Request'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateModelEndpointV1Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Model Endpoints
    delete:
      summary: Delete Model Endpoint
      description: Lists the Models owned by the current owner.
      operationId: delete_model_endpoint_v1_model_endpoints__model_endpoint_id__delete
      security:
      - HTTPBasic: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: model_endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Model Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteModelEndpointV1Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Model Endpoints
  /v1/model-endpoints/{model_endpoint_id}/restart:
    post:
      summary: Restart Model Endpoint
      description: Restarts the Model endpoint.
      operationId: restart_model_endpoint_v1_model_endpoints__model_endpoint_id__restart_post
      security:
      - HTTPBasic: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: model_endpoint_id
        in: path
        required: true
        schema:
          type: string
          title: Model Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestartModelEndpointV1Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Model Endpoints
components:
  schemas:
    CallbackBasicAuth:
      properties:
        kind:
          type: string
          const: basic
          title: Kind
        username:
          type: string
          title: Username
        password:
          type: string
          title: Password
      type: object
      required:
      - kind
      - username
      - password
      title: CallbackBasicAuth
    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
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ModelEndpointDeploymentState:
      properties:
        min_workers:
          type: integer
          minimum: 0.0
          title: Min Workers
        max_workers:
          type: integer
          minimum: 0.0
          title: Max Workers
        per_worker:
          type: integer
          exclusiveMinimum: 0.0
          title: Per Worker
        concurrent_requests_per_worker:
          type: integer
          exclusiveMinimum: 0.0
          title: Concurrent Requests Per Worker
        forwarder_max_concurrency:
          anyOf:
          - type: integer
            maximum: 20.0
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Forwarder Max Concurrency
        available_workers:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Available Workers
        unavailable_workers:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Unavailable Workers
      type: object
      required:
      - min_workers
      - max_workers
      - per_worker
      - concurrent_requests_per_worker
      title: ModelEndpointDeploymentState
      description: This is the entity-layer class for the deployment settings related to a Model Endpoint.
    ModelEndpointStatus:
      type: string
      enum:
      - READY
      - UPDATE_PENDING
      - UPDATE_IN_PROGRESS
      - UPDATE_FAILED
      - DELETE_IN_PROGRESS
      title: ModelEndpointStatus
    ModelEndpointType:
      type: string
      enum:
      - async
      - sync
      - streaming
      title: ModelEndpointType
    GetModelEndpointV1Response:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        endpoint_type:
          $ref: '#/components/schemas/ModelEndpointType'
        destination:
          type: string
          title: Destination
        deployment_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Deployment Name
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
        bundle_name:
          type: string
          title: Bundle Name
        status:
          $ref: '#/components/schemas/ModelEndpointStatus'
        post_inference_hooks:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Post Inference Hooks
        default_callback_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Callback Url
        default_callback_auth:
          anyOf:
          - $ref: '#/components/schemas/CallbackAuth'
          - type: 'null'
        labels:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Labels
        aws_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Aws Role
        results_s3_bucket:
          anyOf:
          - type: string
          - type: 'null'
          title: Results S3 Bucket
        created_by:
          type: string
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        last_updated_at:
          type: string
          format: date-time
          title: Last Updated At
        deployment_state:
          anyOf:
          - $ref: '#/components/schemas/ModelEndpointDeploymentState'
          - type: 'null'
        resource_state:
          anyOf:
          - $ref: '#/components/schemas/ModelEndpointResourceState'
          - type: 'null'
        num_queued_items:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Queued Items
        public_inference:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Public Inference
        task_expires_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Task Expires Seconds
        queue_message_timeout_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Queue Message Timeout Seconds
      type: object
      required:
      - id
      - name
      - endpoint_type
      - destination
      - bundle_name
      - status
      - created_by
      - created_at
      - last_updated_at
      title: GetModelEndpointV1Response
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateModelEndpointV1Response:
      properties:
        endpoint_creation_task_id:
          type: string
          title: Endpoint Creation Task Id
      type: object
      required:
      - endpoint_creation_task_id
      title: CreateModelEndpointV1Response
    CallbackAuth:
      oneOf:
      - $ref: '#/components/schemas/CallbackBasicAuth'
      - $ref: '#/components/schemas/CallbackmTLSAuth'
      title: CallbackAuth
      discriminator:
        propertyName: kind
        mapping:
          basic: '#/components/schemas/CallbackBasicAuth'
          mtls: '#/components/schemas/CallbackmTLSAuth'
    GpuType:
      type: string
      enum:
      - nvidia-tesla-t4
      - nvidia-ampere-a10
      - nvidia-ampere-a100
      - nvidia-ampere-a100e
      - nvidia-hopper-h100
      - nvidia-hopper-h100-1g20gb
      - nvidia-hopper-h100-3g40gb
      title: GpuType
      description: Lists allowed GPU types for Launch.
    DeleteModelEndpointV1Response:
      properties:
        deleted:
          type: boolean
          title: Deleted
      type: object
      required:
      - deleted
      title: DeleteModelEndpointV1Response
    UpdateModelEndpointV1Request:
      properties:
        model_bundle_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Bundle Id
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
        post_inference_hooks:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Post Inference Hooks
        cpus:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Cpus
        gpus:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Gpus
        memory:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Memory
        gpu_type:
          anyOf:
          - $ref: '#/components/schemas/GpuType'
          - type: 'null'
        storage:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Storage
        optimize_costs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Optimize Costs
        min_workers:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Min Workers
        max_workers:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Max Workers
        per_worker:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Per Worker
        concurrent_requests_per_worker:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Concurrent Requests Per Worker
        forwarder_max_concurrency:
          anyOf:
          - type: integer
            maximum: 20.0
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Forwarder Max Concurrency
          description: Max in-flight requests admitted by the HTTP forwarder container, independent of `per_worker` / autoscaling. When None (default), the forwarder inherits its `--concurrency` flag from `per_worker` (current behavior). Upper bound matches LIRA's FORWARDER_MAX_CONCURRENCY_LIMIT.
        labels:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Labels
        prewarm:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Prewarm
        high_priority:
          anyOf:
          - type: boolean
          - type: 'null'
          title: High Priority
        billing_tags:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Billing Tags
        default_callback_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Callback Url
        default_callback_auth:
          anyOf:
          - $ref: '#/components/schemas/CallbackAuth'
          - type: 'null'
        public_inference:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Public Inference
        queue_message_timeout_seconds:
          anyOf:
          - type: integer
            maximum: 43200.0
            minimum: 1.0
          - type: 'null'
          title: Queue Message Timeout Seconds
          description: 'For async endpoints, the queue message visibility/lock timeout in seconds. Controls how long a worker has to process a message before it becomes visible again (SQS VisibilityTimeout / ASB lock_duration). Note: Azure Service Bus has a maximum of 300 seconds; values above this will be clamped.'
        task_expires_seconds:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Task Expires Seconds
          description: 'For async endpoints, how long a task can wait in queue before expiring (in seconds). Default: 86400 (24 hours).'
      type: object
      title: UpdateModelEndpointV1Request
    UpdateModelEndpointV1Response:
      properties:
        endpoint_creation_task_id:
          type: string
          title: Endpoint Creation Task Id
      type: object
      required:
      - endpoint_creation_task_id
      title: UpdateModelEndpointV1Response
    ModelEndpointOrderBy:
      type: string
      enum:
      - newest
      - oldest
      - alphabetical
      title: ModelEndpointOrderBy
      description: The canonical list of possible orderings of Model Bundles.
    CreateModelEndpointV1Request:
      properties:
        name:
          type: string
          maxLength: 63
          title: Name
        model_bundle_id:
          type: string
          title: Model Bundle Id
        endpoint_type:
          $ref: '#/components/schemas/ModelEndpointType'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        post_inference_hooks:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Post Inference Hooks
        cpus:
          anyOf:
          - type: string
          - type: integer
          - type: number
          title: Cpus
        gpus:
          type: integer
          minimum: 0.0
          title: Gpus
        memory:
          anyOf:
          - type: string
          - type: integer
          - type: number
          title: Memory
        gpu_type:
          anyOf:
          - $ref: '#/components/schemas/GpuType'
          - type: 'null'
        storage:
          anyOf:
          - type: string
          - type: integer
          - type: number
          title: Storage
        nodes_per_worker:
          type: integer
          exclusiveMinimum: 0.0
          title: Nodes Per Worker
          default: 1
        optimize_costs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Optimize Costs
        min_workers:
          type: integer
          minimum: 0.0
          title: Min Workers
        max_workers:
          type: integer
          minimum: 0.0
          title: Max Workers
        per_worker:
          type: integer
          exclusiveMinimum: 0.0
          title: Per Worker
        concurrent_requests_per_worker:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Concurrent Requests Per Worker
        forwarder_max_concurrency:
          anyOf:
          - type: integer
            maximum: 20.0
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Forwarder Max Concurrency
          description: Max in-flight requests admitted by the HTTP forwarder container, independent of `per_worker` / autoscaling. When None (default), the forwarder inherits its `--concurrency` flag from `per_worker` (current behavior). Upper bound matches LIRA's FORWARDER_MAX_CONCURRENCY_LIMIT.
        labels:
          additionalProperties:
            type: string
          type: object
          title: Labels
        prewarm:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Prewarm
        high_priority:
          anyOf:
          - type: boolean
          - type: 'null'
          title: High Priority
        billing_tags:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Billing Tags
        default_callback_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Callback Url
        default_callback_auth:
          anyOf:
          - $ref: '#/components/schemas/CallbackAuth'
          - type: 'null'
        public_inference:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Public Inference
          default: false
        queue_message_timeout_seconds:
          anyOf:
          - type: integer
            maximum: 43200.0
            minimum: 1.0
          - type: 'null'
          title: Queue Message Timeout Seconds
          description: 'For async endpoints, the queue message visibility/lock timeout in seconds. Controls how long a worker has to process a message before it becomes visible again (SQS VisibilityTimeout / ASB lock_duration). Note: Azure Service Bus has a maximum of 300 seconds; values above this will be clamped.'
        task_expires_seconds:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Task Expires Seconds
          description: 'For async endpoints, how long a task can wait in queue before expiring (in seconds). Default: 86400 (24 hours).'
      type: object
      required:
      - name
      - model_bundle_id
      - endpoint_type
      - metadata
      - cpus
      - gpus
      - memory
      - storage
      - min_workers
      - max_workers
      - per_worker
      - labels
      title: CreateModelEndpointV1Request
    ListModelEndpointsV1Response:
      properties:
        model_endpoints:
          items:
            $ref: '#/components/schemas/GetModelEndpointV1Response'
          type: array
          title: Model Endpoints
      type: object
      required:
      - model_endpoints
      title: ListModelEndpointsV1Response
    CallbackmTLSAuth:
      properties:
        kind:
          type: string
          const: mtls
          title: Kind
        cert:
          type: string
          title: Cert
        key:
          type: string
          title: Key
      type: object
      required:
      - kind
      - cert
      - key
      title: CallbackmTLSAuth
    RestartModelEndpointV1Response:
      properties:
        restarted:
          type: boolean
          title: Restarted
      type: object
      required:
      - restarted
      title: RestartModelEndpointV1Response
    ModelEndpointResourceState:
      properties:
        cpus:
          anyOf:
          - type: string
          - type: integer
          - type: number
          title: Cpus
        gpus:
          type: integer
          minimum: 0.0
          title: Gpus
        memory:
          anyOf:
          - type: string
          - type: integer
          - type: number
          title: Memory
        gpu_type:
          anyOf:
          - $ref: '#/components/schemas/GpuType'
          - type: 'null'
        storage:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Storage
        nodes_per_worker:
          type: integer
          minimum: 1.0
          title: Nodes Per Worker
        optimize_costs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Optimize Costs
      type: object
      required:
      - cpus
      - gpus
      - memory
      - nodes_per_worker
      title: ModelEndpointResourceState
      description: 'This is the entity-layer class for the resource settings per worker of a Model Endpoint.

        Note: in the multinode case, there are multiple "nodes" per "worker".

        "Nodes" is analogous to a single k8s pod that may take up all the GPUs on a single machine.

        "Workers" is the smallest unit that a request can be made to, and consists of one leader "node" and

        multiple follower "nodes" (named "worker" in the k8s LeaderWorkerSet definition).

        cpus/gpus/memory/storage are per-node, thus the total consumption by a "worker"

        is cpus/gpus/etc. multiplied by nodes_per_worker.'
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: token