> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Deployment



## OpenAPI

````yaml /api-reference/openapi.json post /api/model-deployments
openapi: 3.1.0
info:
  title: StarForge Console
  description: >-
    The StarForge control plane. Everything the `sf` CLI and the web console do
    goes through this API, and so can your own tooling.


    Authenticate with a bearer token from `POST /api/auth/login` or a CLI device
    flow; see the Authentication page for how to get one and how long it lasts.
  version: 0.3.15
servers:
  - url: https://{host}
    description: Your StarForge deployment
    variables:
      host:
        default: starforge.your-company.com
        description: >-
          The domain your administrator gave you, without a scheme or trailing
          slash.
security: []
tags:
  - name: auth
    description: >-
      Log in, exchange a CLI device code, and inspect the current identity.
      Everything else on this API needs a bearer token from here.
  - name: profile
    description: >-
      The signed-in user's own account: quota, tokens, preferences, and
      notification settings.
  - name: projects
    description: >-
      Projects group runs the way `starforge.yaml` names them. A run belongs to
      exactly one.
  - name: experiments
    description: >-
      Read the experiment definitions the console found in the configured
      repository.
  - name: submit
    description: >-
      Admit a JobSpec. This is what `sf submit` calls: the catalog handshake,
      quota check, and preflight all happen here, and a rejection names the gate
      that refused it.
  - name: jobs
    description: >-
      Everything about a job after it is admitted: status, logs, metrics,
      samples, artifacts, and the pause/resume/stop controls.
  - name: runs
    description: >-
      Finished work, addressed by run id. A run outlives the job that produced
      it.
  - name: ingest
    description: >-
      The endpoints training code reports to. `starforge.report` speaks this;
      you only call it directly when writing an adapter for a framework the
      catalog does not cover.
  - name: datasets
    description: >-
      Versioned dataset upload, listing, and metadata. Protected datasets expose
      identity and schema here but never their records.
  - name: volumes
    description: Governed directories of files a job may mount read-only.
  - name: environments
    description: >-
      Agent RL environments: their manifests, versions, and upload URLs. A
      taskset is never returned.
  - name: benchmarks
    description: >-
      The benchmark catalog, the score matrix across runs, and externally scored
      evaluations.
  - name: rubrics
    description: >-
      Written scoring standards, their revisions, and which runs cited which
      version.
  - name: judge
    description: >-
      The LLM-judge endpoint a training job calls to score a rollout.
      OpenAI-compatible.
  - name: models
    description: >-
      The model registry: register a version, promote it, archive it, read its
      card.
  - name: model-deployments
    description: >-
      Managed model versions serving application traffic: revisions, promotion,
      rollback, suspension, and deployment tokens.
  - name: inference
    description: >-
      OpenAI-compatible inference against a promoted deployment revision. This
      is the endpoint applications call.
  - name: playground
    description: >-
      Short-lived serving sessions for human evaluation. Distinct from a
      deployment: a session expires, a deployment does not.
  - name: reflow
    description: >-
      The governed path from a deployment's production traffic back to the
      training data of its next version.
  - name: annotate
    description: 'Preference annotation: pull a batch, push judgements, read progress.'
  - name: plugins
    description: Installed plugins and the extension shelf the console renders.
  - name: diagnosis
    description: >-
      Automated analysis of a finished or failed run, and the accumulated
      project memory it draws on.
  - name: approvals
    description: 'Approval requests: an escalation path, one level deep, with a record.'
  - name: billing
    description: >-
      What the GPU-hours cost. One price on top of the hours the usage page
      already shows.
  - name: teams
    description: 'Teams: the unit capacity is budgeted to. A department, not a tenant.'
  - name: agent
    description: >-
      Submit plans: a proposed submission a human approves or rejects before it
      becomes a job.
  - name: share
    description: >-
      Public, revocable read-only links to a job or a comparison. The
      `/api/share/{token}` routes need no bearer token, which is the point.
  - name: notifications
    description: The signed-in user's notification feed.
  - name: search
    description: Cross-surface search over jobs, runs, datasets, and models.
  - name: sandbox
    description: >-
      Execute model-generated code in a throwaway container with no GPU and no
      network.
  - name: uploads
    description: >-
      Resumable upload sessions used by dataset, environment, and plugin
      publishing.
  - name: integrations-hf
    description: Hugging Face account linking and repository push.
  - name: mcp
    description: Model Context Protocol access information and per-user tool settings.
  - name: mcp-oauth
    description: >-
      OAuth metadata, authorization, token exchange, and dynamic client
      registration for MCP clients.
  - name: cluster
    description: Live capacity and node state across the fleets.
  - name: fleets
    description: >-
      Registered execution backends and the machines in them. Reading is open to
      every user; creating a fleet, minting a join token and draining a node are
      admin-only. Joining is authorized by the join token alone.
  - name: admin
    description: >-
      User, role, quota, hardware, schedule, integration, and settings
      administration. Admin role required.
  - name: tasks
    description: >-
      Scheduled platform maintenance tasks: what they are, when they last ran,
      and running one now.
  - name: report
    description: The rendered daily report page.
  - name: health
    description: Liveness and version. Unauthenticated.
paths:
  /api/model-deployments:
    post:
      tags:
        - model-deployments
      summary: Create Deployment
      operationId: create_deployment_api_model_deployments_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentCreateIn'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentCreatedOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    DeploymentCreateIn:
      properties:
        name:
          type: string
          maxLength: 128
          minLength: 2
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
          title: Name
        model_source:
          oneOf:
            - $ref: '#/components/schemas/ArtifactModelSource'
            - $ref: '#/components/schemas/HuggingFaceModelSource'
            - $ref: '#/components/schemas/SharedPathModelSource'
            - $ref: '#/components/schemas/RegistryModelSource'
          title: Model Source
          discriminator:
            propertyName: kind
            mapping:
              artifact:
                $ref: '#/components/schemas/ArtifactModelSource'
              huggingface:
                $ref: '#/components/schemas/HuggingFaceModelSource'
              model:
                $ref: '#/components/schemas/RegistryModelSource'
              shared_path:
                $ref: '#/components/schemas/SharedPathModelSource'
        config:
          $ref: '#/components/schemas/ServingConfigIn'
        fleet_id:
          type: string
          title: Fleet Id
          default: ''
        serve_mode:
          type: string
          enum:
            - proxied
            - direct
          title: Serve Mode
          default: proxied
      type: object
      required:
        - name
        - model_source
        - config
      title: DeploymentCreateIn
    DeploymentCreatedOut:
      properties:
        deployment:
          $ref: '#/components/schemas/ModelDeploymentOut'
        initial_token:
          anyOf:
            - $ref: '#/components/schemas/DeploymentTokenCreatedOut'
            - type: 'null'
      type: object
      required:
        - deployment
      title: DeploymentCreatedOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ArtifactModelSource:
      properties:
        kind:
          type: string
          const: artifact
          title: Kind
        run_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Run Id
      type: object
      required:
        - kind
        - run_id
      title: ArtifactModelSource
    HuggingFaceModelSource:
      properties:
        kind:
          type: string
          const: huggingface
          title: Kind
        repository:
          type: string
          maxLength: 256
          minLength: 3
          title: Repository
        revision:
          anyOf:
            - type: string
              maxLength: 128
            - type: 'null'
          title: Revision
        use_linked_credential:
          type: boolean
          title: Use Linked Credential
          default: false
      type: object
      required:
        - kind
        - repository
      title: HuggingFaceModelSource
    SharedPathModelSource:
      properties:
        kind:
          type: string
          const: shared_path
          title: Kind
        path:
          type: string
          maxLength: 1024
          minLength: 1
          title: Path
      type: object
      required:
        - kind
        - path
      title: SharedPathModelSource
    RegistryModelSource:
      properties:
        kind:
          type: string
          const: model
          title: Kind
        model:
          type: string
          maxLength: 256
          minLength: 3
          title: Model
          description: <owner>/<name>
        version:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Version
          description: 留空 = 当前 production
      type: object
      required:
        - kind
        - model
      title: RegistryModelSource
      description: |-
        部署模型注册表里的一个版本。

        与 artifact 的区别是**指向什么**：artifact 指一次训练，registry 指一条命名
        版本线。写 `version: null` 就是「当前 production 那一版」—— 部署跟着注册表
        的提升走，而不是跟着某个人记住的 run id 走。
    ServingConfigIn:
      properties:
        engine:
          type: string
          enum:
            - vllm
            - sglang
          title: Engine
          default: vllm
        gpus:
          type: integer
          maximum: 64
          minimum: 1
          title: Gpus
          default: 1
        dtype:
          type: string
          enum:
            - auto
            - float16
            - bfloat16
          title: Dtype
          default: auto
        quantization:
          type: string
          enum:
            - none
            - awq
            - gptq
            - bitsandbytes
            - fp8
          title: Quantization
          default: none
        max_model_len:
          anyOf:
            - type: integer
              maximum: 4194304
              minimum: 128
            - type: 'null'
          title: Max Model Len
        gpu_memory_utilization:
          type: number
          maximum: 0.99
          minimum: 0.1
          title: Gpu Memory Utilization
          default: 0.9
        max_concurrency:
          anyOf:
            - type: integer
              maximum: 65536
              minimum: 1
            - type: 'null'
          title: Max Concurrency
        trust_remote_code:
          type: boolean
          title: Trust Remote Code
          default: false
        served_model_name:
          type: string
          maxLength: 128
          minLength: 1
          title: Served Model Name
          default: model
        tensor_parallel_size:
          anyOf:
            - type: integer
              maximum: 64
              minimum: 1
            - type: 'null'
          title: Tensor Parallel Size
        pipeline_parallel_size:
          anyOf:
            - type: integer
              maximum: 64
              minimum: 1
            - type: 'null'
          title: Pipeline Parallel Size
        data_parallel_size:
          anyOf:
            - type: integer
              maximum: 64
              minimum: 1
            - type: 'null'
          title: Data Parallel Size
        extra_args:
          items:
            type: string
          type: array
          maxItems: 64
          title: Extra Args
        env:
          additionalProperties:
            type: string
          type: object
          maxProperties: 64
          title: Env
        vllm:
          anyOf:
            - $ref: '#/components/schemas/VllmAdvancedConfig'
            - type: 'null'
        sglang:
          anyOf:
            - $ref: '#/components/schemas/SglangAdvancedConfig'
            - type: 'null'
      additionalProperties: false
      type: object
      title: ServingConfigIn
    ModelDeploymentOut:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        owner_user_id:
          type: integer
          title: Owner User Id
        owner_username:
          type: string
          title: Owner Username
        fleet_id:
          type: string
          title: Fleet Id
          default: ''
        serve_mode:
          type: string
          title: Serve Mode
          default: proxied
        desired_state:
          type: string
          title: Desired State
        status:
          type: string
          title: Status
        current_revision_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Revision Id
        candidate_revision_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Candidate Revision Id
        endpoint_path:
          type: string
          title: Endpoint Path
        last_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Error
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        current_revision:
          anyOf:
            - $ref: '#/components/schemas/DeploymentRevisionOut'
            - type: 'null'
        candidate_revision:
          anyOf:
            - $ref: '#/components/schemas/DeploymentRevisionOut'
            - type: 'null'
        revisions:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeploymentRevisionOut'
              type: array
            - type: 'null'
          title: Revisions
        tokens:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeploymentTokenOut'
              type: array
            - type: 'null'
          title: Tokens
        reflow_sample_rate:
          type: number
          title: Reflow Sample Rate
          default: 0
        reflow_retention_days:
          type: integer
          title: Reflow Retention Days
          default: 30
        reflow_capture_system_prompt:
          type: boolean
          title: Reflow Capture System Prompt
          default: true
        reflow_dropped_total:
          type: integer
          title: Reflow Dropped Total
          default: 0
        reflow_trimmed_total:
          type: integer
          title: Reflow Trimmed Total
          default: 0
      type: object
      required:
        - id
        - name
        - owner_user_id
        - owner_username
        - desired_state
        - status
        - endpoint_path
        - created_at
        - updated_at
      title: ModelDeploymentOut
    DeploymentTokenCreatedOut:
      properties:
        id:
          type: string
          title: Id
        deployment_id:
          type: string
          title: Deployment Id
        name:
          type: string
          title: Name
        prefix:
          type: string
          title: Prefix
        created_by:
          type: string
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        last_used_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Used At
        revoked_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Revoked At
        token:
          type: string
          title: Token
      type: object
      required:
        - id
        - deployment_id
        - name
        - prefix
        - created_by
        - created_at
        - token
      title: DeploymentTokenCreatedOut
    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
    VllmAdvancedConfig:
      properties:
        cpu_offload_gib:
          type: number
          maximum: 512
          minimum: 0
          title: Cpu Offload Gib
          default: 0
        kv_cache_dtype:
          type: string
          enum:
            - auto
            - fp8
            - fp8_e4m3
            - fp8_e5m2
          title: Kv Cache Dtype
          default: auto
        enforce_eager:
          type: boolean
          title: Enforce Eager
          default: false
        max_num_batched_tokens:
          anyOf:
            - type: integer
              maximum: 1048576
              minimum: 64
            - type: 'null'
          title: Max Num Batched Tokens
        enable_prefix_caching:
          type: boolean
          title: Enable Prefix Caching
          default: false
        enable_chunked_prefill:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enable Chunked Prefill
        tool_call_parser:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Tool Call Parser
        reasoning_parser:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Reasoning Parser
        chat_template:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
          title: Chat Template
      type: object
      title: VllmAdvancedConfig
    SglangAdvancedConfig:
      properties:
        mem_fraction_static:
          type: number
          maximum: 0.99
          minimum: 0.1
          title: Mem Fraction Static
          default: 0.88
        chunked_prefill_size:
          anyOf:
            - type: integer
              maximum: 1048576
              minimum: 128
            - type: 'null'
          title: Chunked Prefill Size
        schedule_policy:
          type: string
          enum:
            - lpm
            - random
            - fcfs
            - dfs-weight
          title: Schedule Policy
          default: lpm
        max_running_requests:
          anyOf:
            - type: integer
              maximum: 65536
              minimum: 1
            - type: 'null'
          title: Max Running Requests
        disable_radix_cache:
          type: boolean
          title: Disable Radix Cache
          default: false
        tool_call_parser:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Tool Call Parser
        reasoning_parser:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Reasoning Parser
        chat_template:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
          title: Chat Template
      type: object
      title: SglangAdvancedConfig
    DeploymentRevisionOut:
      properties:
        id:
          type: string
          title: Id
        deployment_id:
          type: string
          title: Deployment Id
        sequence:
          type: integer
          title: Sequence
        engine:
          type: string
          title: Engine
        model_source:
          additionalProperties: true
          type: object
          title: Model Source
        config:
          additionalProperties: true
          type: object
          title: Config
        status:
          type: string
          title: Status
        runtime_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Runtime Ref
        runtime_meta:
          additionalProperties: true
          type: object
          title: Runtime Meta
        internal_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Internal Endpoint
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        created_by:
          type: string
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        ready_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ready At
        retired_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Retired At
      type: object
      required:
        - id
        - deployment_id
        - sequence
        - engine
        - model_source
        - config
        - status
        - created_by
        - created_at
      title: DeploymentRevisionOut
    DeploymentTokenOut:
      properties:
        id:
          type: string
          title: Id
        deployment_id:
          type: string
          title: Deployment Id
        name:
          type: string
          title: Name
        prefix:
          type: string
          title: Prefix
        created_by:
          type: string
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        last_used_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Used At
        revoked_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Revoked At
      type: object
      required:
        - id
        - deployment_id
        - name
        - prefix
        - created_by
        - created_at
      title: DeploymentTokenOut
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````