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

# Stage artifact version

> Stage an artifact version for upload, returning storage location and version ID.



## OpenAPI

````yaml /openapi.json post /api/ml/v1/artifact-versions/stage
openapi: 3.1.0
info:
  title: TrueFoundry API
  description: API for TrueFoundry
  version: 0.1.0
  contact: {}
servers:
  - url: https://{controlPlaneURL}
    variables:
      controlPlaneURL:
        default: app.truefoundry.com
        description: Control Plane URL
security: []
tags:
  - name: Agent
  - name: Agent Skills
  - name: Applications
  - name: Metrics
  - name: Apply
  - name: Artifacts
  - name: Audit Logs
  - name: Clusters
  - name: Jobs
  - name: Logs
  - name: MCP Servers V2
  - name: MLRepos
  - name: Model Deployments
  - name: Models
  - name: Personal Access Tokens
  - name: Prompts
  - name: Provider Integrations
  - name: SCIM v2
  - name: Secret Groups
  - name: Secrets
  - name: Teams
  - name: Traces
  - name: Users
  - name: Virtual Accounts
  - name: Role Bindings
  - name: Workspaces
paths:
  /api/ml/v1/artifact-versions/stage:
    post:
      tags:
        - Artifacts
      summary: Stage artifact version
      description: >-
        Stage an artifact version for upload, returning storage location and
        version ID.
      operationId: stage_artifact_version_v1_artifact_versions_stage_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StageArtifactRequest'
        required: true
      responses:
        '200':
          description: >-
            Staging information including version ID, storage root, and artifact
            ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StageArtifactResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - jwt: []
components:
  schemas:
    StageArtifactRequest:
      properties:
        manifest:
          oneOf:
            - $ref: '#/components/schemas/ModelManifest'
            - $ref: '#/components/schemas/ArtifactManifest'
            - $ref: '#/components/schemas/AgentSkillManifest'
          title: Manifest
          description: >-
            Manifest containing metadata for the artifact to be staged (model or
            generic artifact)
          discriminator:
            propertyName: type
            mapping:
              model-version:
                $ref: '#/components/schemas/ModelManifest'
              artifact-version:
                $ref: '#/components/schemas/ArtifactManifest'
              agent-skill:
                $ref: '#/components/schemas/AgentSkillManifest'
      type: object
      required:
        - manifest
      title: StageArtifactRequest
      x-fern-type-name: StageArtifactRequest
    StageArtifactResponse:
      properties:
        id:
          type: string
          title: Id
          description: ID of the staged artifact version
        storage_root:
          type: string
          title: Storage Root
          description: >-
            Root storage path where the artifact version files should be
            uploaded
        artifact_id:
          type: string
          title: Artifact Id
          description: ID of the artifact that the staged version belongs to
      type: object
      required:
        - id
        - storage_root
        - artifact_id
      title: StageArtifactResponse
      x-fern-type-name: StageArtifactResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      x-fern-type-name: HTTPValidationError
    ModelManifest:
      properties:
        name:
          type: string
          maxLength: 256
          pattern: ^[A-Za-z0-9_\-]+$
          title: Name
          description: >-
            Name of the model (alphanumeric characters, hyphens, and underscores
            only, max 256 characters)
        metadata:
          type: object
          title: Metadata
          description: >-
            Key value metadata. Should be valid JSON. For e.g.
            `{"business-unit": "sales", "quality": "good", "rating": 4.5}`
        ml_repo:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9\-]{1,98}[a-zA-Z0-9]$
          title: Ml Repo
          description: >-
            Name of the ML Repo that this model belongs to (must start and end
            with alphanumeric, 2-100 characters)
        version:
          type: integer
          minimum: 1
          title: Version
          description: Version of the entity
        type:
          type: string
          enum:
            - model-version
          title: Type
          default: model-version
        description:
          type: string
          maxLength: 512
          title: Description
        version_alias:
          type: string
          maxLength: 128
          pattern: ^v[a-zA-Z0-9.-]*([a-zA-Z0-9]+)$
          title: Version Alias
          description: >-
            Version alias is alternate, ideally human readable, version string
            to reference an artifact version. It should start with `v` followed
            by alphanumeric and it can include `.` and `-` in between (e.g.
            `v1.0.0`, `v1-prod`, `v3-dev`, etc)
        source:
          oneOf:
            - $ref: '#/components/schemas/TrueFoundryManagedSource'
            - $ref: '#/components/schemas/ExternalBlobStorageSource'
            - $ref: '#/components/schemas/LocalModelSource'
          title: Source
          discriminator:
            propertyName: type
            mapping:
              truefoundry:
                $ref: '#/components/schemas/TrueFoundryManagedSource'
              external:
                $ref: '#/components/schemas/ExternalBlobStorageSource'
              local:
                $ref: '#/components/schemas/LocalModelSource'
        framework:
          oneOf:
            - $ref: '#/components/schemas/TransformersFramework'
            - $ref: '#/components/schemas/TensorFlowFramework'
            - $ref: '#/components/schemas/SklearnFramework'
            - $ref: '#/components/schemas/PyTorchFramework'
            - $ref: '#/components/schemas/KerasFramework'
            - $ref: '#/components/schemas/XGBoostFramework'
            - $ref: '#/components/schemas/LightGBMFramework'
            - $ref: '#/components/schemas/FastAIFramework'
            - $ref: '#/components/schemas/H2OFramework'
            - $ref: '#/components/schemas/ONNXFramework'
            - $ref: '#/components/schemas/SpaCyFramework'
            - $ref: '#/components/schemas/StatsModelsFramework'
            - $ref: '#/components/schemas/GluonFramework'
            - $ref: '#/components/schemas/PaddleFramework'
          title: Framework
          description: >-
            Framework for the model version like Transformers, PyTorch, Sklearn,
            Xgboost etc with framework specific metadata. This will be used to
            infer model deployment configuration
          discriminator:
            propertyName: type
            mapping:
              transformers:
                $ref: '#/components/schemas/TransformersFramework'
              tensorflow:
                $ref: '#/components/schemas/TensorFlowFramework'
              sklearn:
                $ref: '#/components/schemas/SklearnFramework'
              pytorch:
                $ref: '#/components/schemas/PyTorchFramework'
              keras:
                $ref: '#/components/schemas/KerasFramework'
              xgboost:
                $ref: '#/components/schemas/XGBoostFramework'
              lightgbm:
                $ref: '#/components/schemas/LightGBMFramework'
              fastai:
                $ref: '#/components/schemas/FastAIFramework'
              h2o:
                $ref: '#/components/schemas/H2OFramework'
              onnx:
                $ref: '#/components/schemas/ONNXFramework'
              spacy:
                $ref: '#/components/schemas/SpaCyFramework'
              statsmodels:
                $ref: '#/components/schemas/StatsModelsFramework'
              gluon:
                $ref: '#/components/schemas/GluonFramework'
              paddle:
                $ref: '#/components/schemas/PaddleFramework'
        environment:
          $ref: '#/components/schemas/ModelVersionEnvironment'
        step:
          type: integer
          minimum: 0
          title: Step
          description: >-
            Step/Epoch number in an iterative training loop the model version
            was created. Generally useful when logging a model version from a
            MLRepo Run
          default: 0
        run_id:
          type: string
          title: Run Id
          description: ID of the MLRepo Run that generated the model version
      type: object
      required:
        - name
        - metadata
        - ml_repo
        - source
      title: ModelManifest
      description: Model Version artifact.
      x-fern-type-name: ModelManifest
    ArtifactManifest:
      properties:
        name:
          type: string
          maxLength: 256
          pattern: ^[A-Za-z0-9_\-]+$
          title: Name
          description: >-
            Name of the artifact (alphanumeric characters, hyphens, and
            underscores only, max 256 characters)
        metadata:
          type: object
          title: Metadata
          description: >-
            Key value metadata. Should be valid JSON. For e.g.
            `{"business-unit": "sales", "quality": "good", "rating": 4.5}`
        ml_repo:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9\-]{1,98}[a-zA-Z0-9]$
          title: Ml Repo
          description: >-
            Name of the ML Repo that this artifact belongs to (must start and
            end with alphanumeric, 2-100 characters)
        version:
          type: integer
          minimum: 1
          title: Version
          description: Version of the entity
        type:
          type: string
          enum:
            - artifact-version
          title: Type
          default: artifact-version
        description:
          type: string
          maxLength: 512
          title: Description
        version_alias:
          type: string
          maxLength: 128
          pattern: ^v[a-zA-Z0-9.-]*([a-zA-Z0-9]+)$
          title: Version Alias
          description: >-
            Version alias is alternate, ideally human readable, version string
            to reference an artifact version. It should start with `v` followed
            by alphanumeric and it can include `.` and `-` in between (e.g.
            `v1.0.0`, `v1-prod`, `v3-dev`, etc)
        source:
          oneOf:
            - $ref: '#/components/schemas/TrueFoundryManagedSource'
            - $ref: '#/components/schemas/ExternalBlobStorageSource'
            - $ref: '#/components/schemas/LocalArtifactSource'
          title: Source
          discriminator:
            propertyName: type
            mapping:
              truefoundry:
                $ref: '#/components/schemas/TrueFoundryManagedSource'
              external:
                $ref: '#/components/schemas/ExternalBlobStorageSource'
              local:
                $ref: '#/components/schemas/LocalArtifactSource'
        step:
          type: integer
          minimum: 0
          title: Step
          description: >-
            Step/Epoch number in an iterative training loop the artifact version
            was created. Generally useful when logging a model version from a
            MLRepo Run
          default: 0
        run_id:
          type: string
          title: Run Id
          description: ID of the MLRepo Run that generated the artifact version
      type: object
      required:
        - name
        - metadata
        - ml_repo
        - source
      title: ArtifactManifest
      description: Artifact Version manifest.
      x-fern-type-name: ArtifactManifest
    AgentSkillManifest:
      properties:
        name:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^(?!.*anthropic)(?!.*claude)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$
          title: Name
          description: Name of the skill.
        metadata:
          type: object
          title: Metadata
          description: >-
            Key value metadata. Should be valid JSON. For e.g.
            `{"business-unit": "sales", "quality": "good", "rating": 4.5}`
        ml_repo:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9\-]{1,98}[a-zA-Z0-9]$
          title: Ml Repo
          description: Name of the ML Repo
        version:
          type: integer
          minimum: 1
          title: Version
          description: Version of the entity
        type:
          type: string
          enum:
            - agent-skill
          title: Type
          default: agent-skill
        source:
          oneOf:
            - $ref: '#/components/schemas/AgentSkillSourceInline'
            - $ref: '#/components/schemas/AgentSkillSourceBlobStorage'
            - $ref: '#/components/schemas/AgentSkillSourceLocal'
          title: Source
          discriminator:
            propertyName: type
            mapping:
              inline:
                $ref: '#/components/schemas/AgentSkillSourceInline'
              blob-storage:
                $ref: '#/components/schemas/AgentSkillSourceBlobStorage'
              local:
                $ref: '#/components/schemas/AgentSkillSourceLocal'
      type: object
      required:
        - name
        - metadata
        - ml_repo
        - source
      title: AgentSkillManifest
      description: >-
        Apply/API agent-skill manifest; ``source`` is inline (apply) or
        blob-storage (stored).
      x-fern-type-name: AgentSkillManifest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
      x-fern-type-name: ValidationError
    TrueFoundryManagedSource:
      properties:
        type:
          type: string
          enum:
            - truefoundry
          title: Type
          description: Type of the source
        uri:
          type: string
          pattern: ^(s3|gs|wasbs)://.*
          title: Uri
      type: object
      required:
        - type
      title: TrueFoundryManagedSource
      x-fern-type-name: TrueFoundryManagedSource
    ExternalBlobStorageSource:
      properties:
        type:
          type: string
          enum:
            - external
          title: Type
          description: Type of the source
        uri:
          type: string
          pattern: ^(s3|gs|wasbs)://.*
          title: Uri
          description: >-
            URI referencing a path in the blob storage bucket linked to the
            MLRepo
      type: object
      required:
        - type
        - uri
      title: ExternalBlobStorageSource
      x-fern-type-name: ExternalBlobStorageSource
    LocalModelSource:
      properties:
        type:
          type: string
          enum:
            - local
          title: Type
          description: Type of the source
        file_or_folder:
          type: string
          title: File Or Folder
          description: Path to the model file or folder
      type: object
      required:
        - type
        - file_or_folder
      title: LocalModelSource
      x-fern-type-name: LocalModelSource
    TransformersFramework:
      properties:
        type:
          type: string
          enum:
            - transformers
          title: Type
          description: Type of the framework
        library_name:
          allOf:
            - $ref: '#/components/schemas/LibraryName'
          description: Name of the library for the framework
          default: transformers
        pipeline_tag:
          type: string
          title: Pipeline Tag
          description: >-
            The `pipeline()` task this model can be used with e.g.
            `text-generation`. See [huggingface
            docs](https://huggingface.co/docs/transformers/main/en/main_classes/pipelines#transformers.pipeline.task)
            for all possible values
        base_model:
          type: string
          title: Base Model
          description: >-
            Base model Id from HuggingFace Hub. If this is a finetuned model,
            this points to the base model id used for finetuning.
      type: object
      required:
        - type
      title: TransformersFramework
      x-fern-type-name: TransformersFramework
    TensorFlowFramework:
      properties:
        type:
          type: string
          enum:
            - tensorflow
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: TensorFlowFramework
      x-fern-type-name: TensorFlowFramework
    SklearnFramework:
      properties:
        type:
          type: string
          enum:
            - sklearn
          title: Type
          description: Type of the framework
        model_filepath:
          type: string
          title: Model Filepath
          description: Relative path to the model file in the model version contents
        serialization_format:
          $ref: '#/components/schemas/SklearnSerializationFormat'
        model_schema:
          $ref: '#/components/schemas/SklearnModelSchema'
      type: object
      required:
        - type
      title: SklearnFramework
      x-fern-type-name: SklearnFramework
    PyTorchFramework:
      properties:
        type:
          type: string
          enum:
            - pytorch
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: PyTorchFramework
      x-fern-type-name: PyTorchFramework
    KerasFramework:
      properties:
        type:
          type: string
          enum:
            - keras
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: KerasFramework
      x-fern-type-name: KerasFramework
    XGBoostFramework:
      properties:
        type:
          type: string
          enum:
            - xgboost
          title: Type
          description: Type of the framework
        serialization_format:
          $ref: '#/components/schemas/XGBoostSerializationFormat'
        model_filepath:
          type: string
          title: Model Filepath
          description: Relative path to the model file in the model version contents
        model_schema:
          $ref: '#/components/schemas/XGBoostModelSchema'
      type: object
      required:
        - type
      title: XGBoostFramework
      x-fern-type-name: XGBoostFramework
    LightGBMFramework:
      properties:
        type:
          type: string
          enum:
            - lightgbm
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: LightGBMFramework
      x-fern-type-name: LightGBMFramework
    FastAIFramework:
      properties:
        type:
          type: string
          enum:
            - fastai
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: FastAIFramework
      x-fern-type-name: FastAIFramework
    H2OFramework:
      properties:
        type:
          type: string
          enum:
            - h2o
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: H2OFramework
      x-fern-type-name: H2OFramework
    ONNXFramework:
      properties:
        type:
          type: string
          enum:
            - onnx
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: ONNXFramework
      x-fern-type-name: ONNXFramework
    SpaCyFramework:
      properties:
        type:
          type: string
          enum:
            - spacy
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: SpaCyFramework
      x-fern-type-name: SpaCyFramework
    StatsModelsFramework:
      properties:
        type:
          type: string
          enum:
            - statsmodels
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: StatsModelsFramework
      x-fern-type-name: StatsModelsFramework
    GluonFramework:
      properties:
        type:
          type: string
          enum:
            - gluon
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: GluonFramework
      x-fern-type-name: GluonFramework
    PaddleFramework:
      properties:
        type:
          type: string
          enum:
            - paddle
          title: Type
          description: Type of the framework
      type: object
      required:
        - type
      title: PaddleFramework
      x-fern-type-name: PaddleFramework
    ModelVersionEnvironment:
      properties:
        python_version:
          type: string
          pattern: ^\d+(\.\d+){1,2}([\-\.a-z0-9]+)?$
          title: Python Version
          description: Python version to use when running the model
        pip_packages:
          items:
            type: string
          type: array
          title: Pip Packages
          description: pip dependencies needed for running the model
      type: object
      title: ModelVersionEnvironment
      description: >-
        Runtime environment describing python version and dependencies for
        running the model
      x-fern-type-name: ModelVersionEnvironment
    LocalArtifactSource:
      properties:
        type:
          type: string
          enum:
            - local
          title: Type
          description: Type of the source
        paths:
          items:
            $ref: '#/components/schemas/ArtifactPath'
          type: array
          title: Paths
          description: >-
            Array of ArtifactPath objects representing the source and
            destination paths
      type: object
      required:
        - type
        - paths
      title: LocalArtifactSource
      x-fern-type-name: LocalArtifactSource
    AgentSkillSourceInline:
      properties:
        type:
          type: string
          enum:
            - inline
          title: Type
        skill_md:
          type: string
          maxLength: 20000
          minLength: 1
          title: Skill Md
          description: Main body of SKILL.md file.
      type: object
      required:
        - type
        - skill_md
      title: AgentSkillSourceInline
      description: SKILL.md for this version when using inline source.
      x-fern-type-name: AgentSkillSourceInline
    AgentSkillSourceBlobStorage:
      properties:
        type:
          type: string
          enum:
            - blob-storage
          title: Type
        description:
          type: string
          maxLength: 1024
          minLength: 1
          title: Description
          description: 1–1024 chars.
        uri:
          type: string
          minLength: 1
          title: Uri
          description: Storage URI of the blob storage object where the skill is stored.
      type: object
      required:
        - type
        - description
        - uri
      title: AgentSkillSourceBlobStorage
      description: SKILL.md content stored on blob
      x-fern-type-name: AgentSkillSourceBlobStorage
    AgentSkillSourceLocal:
      properties:
        type:
          type: string
          enum:
            - local
          title: Type
        skill_dir:
          type: string
          minLength: 1
          title: Skill Dir
          description: >-
            Path to the skill root directory, including SKILL.md and related
            assets.
      type: object
      required:
        - type
        - skill_dir
      title: AgentSkillSourceLocal
      description: >-
        Load the skill from a local directory. The directory must include
        SKILL.md with valid YAML front matter.
      x-fern-type-name: AgentSkillSourceLocal
    LibraryName:
      type: string
      enum:
        - transformers
        - sentence-transformers
        - diffusers
      title: LibraryName
      description: Name of the library for the framework
      x-fern-type-name: LibraryName
    SklearnSerializationFormat:
      type: string
      enum:
        - cloudpickle
        - joblib
        - pickle
      title: SklearnSerializationFormat
      description: Serialization format used to save the sklearn model
      x-fern-type-name: SklearnSerializationFormat
    SklearnModelSchema:
      properties:
        infer_method_name:
          allOf:
            - $ref: '#/components/schemas/InferMethodName'
          description: Name of the method used for inference
        inputs:
          items:
            type: object
          type: array
          title: Inputs
          description: Schema of the input
        outputs:
          items:
            type: object
          type: array
          title: Outputs
          description: Schema of the output
      type: object
      required:
        - infer_method_name
        - inputs
        - outputs
      title: SklearnModelSchema
      x-fern-type-name: SklearnModelSchema
    XGBoostSerializationFormat:
      type: string
      enum:
        - cloudpickle
        - joblib
        - pickle
        - json
      title: XGBoostSerializationFormat
      description: Serialization format used to save the xgboost model
      x-fern-type-name: XGBoostSerializationFormat
    XGBoostModelSchema:
      properties:
        infer_method_name:
          type: string
          enum:
            - predict
          title: Infer Method Name
          description: Name of the method used for inference
        inputs:
          items:
            type: object
          type: array
          title: Inputs
          description: Schema of the input
        outputs:
          items:
            type: object
          type: array
          title: Outputs
          description: Schema of the output
      type: object
      required:
        - infer_method_name
        - inputs
        - outputs
      title: XGBoostModelSchema
      description: Schema of the XGBoost model
      x-fern-type-name: XGBoostModelSchema
    ArtifactPath:
      properties:
        src:
          type: string
          title: Src
          description: Local file or folder path
        dest:
          type: string
          title: Dest
          description: >-
            Relative path where the file or folder will be uploaded to in the
            artifact
      type: object
      required:
        - src
      title: ArtifactPath
      x-fern-type-name: ArtifactPath
    InferMethodName:
      type: string
      enum:
        - predict
        - predict_proba
      title: InferMethodName
      description: Name of the method used for inference
      x-fern-type-name: InferMethodName
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT

````