> ## Documentation Index
> Fetch the complete documentation index at: https://inference-docs.cerebras.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload model version
This feature is in [Private Preview](/support/preview-releases). For access or more information, [contact us](https://www.cerebras.ai/contact) or reach out to your account representative.
Upload a new finetuned model version to Cerebras. Model versions are custom variants of Cerebras-supported model architectures.
Before using this endpoint, you must configure an S3 bucket with cross-account access to Cerebras. See [S3 Bucket Setup](/dedicated/management-api#s3-bucket-setup) for instructions.
## OpenAPI
````yaml post /management/v1/orgs/{org_name}/models:upload
openapi: 3.1.0
info:
title: Endpoint Management Orchestrator API
version: 1.0.0
servers:
- url: https://api.cerebras.ai
security:
- BearerAuth: []
paths:
/management/v1/orgs/{org_name}/models:upload:
post:
summary: Upload model version
operationId: >-
upload_new_model_version_route_management_v1_orgs__org_name__models_upload_post
parameters:
- name: org_name
in: path
required: true
schema:
type: string
description: >-
Cerebras customer management organization name found under
`Management API keys` on the `API keys` page at
https://cloud.cerebras.ai.
Note: This is not to be confused with `org_id`.
title: Org Name
description: >-
Cerebras customer management organization name found under
`Management API keys` on the `API keys` page at
https://cloud.cerebras.ai.
Note: This is not to be confused with `org_id`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelVersionUploadRequest'
examples:
upload_model:
summary: Upload a new model version
value:
model_arch_id: gpt-oss-120b
model:
weight_uri: s3://my-bucket/model-weights
version_aliases:
- production
- v1-stable
system_fingerprint_suffix: my-custom-suffix
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ModelVersionUploadResponse'
example:
name: orgs/my-org/models/gpt-oss-120b/versions/1
done: false
response:
customer_s3_uri: s3://my-bucket/model-weights
version_aliases:
- production
- v1-stable
sync_status: queued
components:
schemas:
ModelVersionUploadRequest:
properties:
model_arch_id:
type: string
title: Model Arch Id
description: Name of the model architecture (e.g. `llama3.1-8b`, `gpt-oss-120b`).
model:
$ref: '#/components/schemas/ModelVersionUploadRequestModel'
additionalProperties: false
type: object
required:
- model_arch_id
- model
title: ModelVersionUploadRequest
ModelVersionUploadResponse:
properties:
name:
type: string
title: Name
description: >-
Model version name in the format of
`orgs//models//versions/`.
`` is an auto-incrementing integer assigned by the
system upon successful upload. This full model version name can be
used for model deployment.
done:
type: boolean
title: Done
description: Whether the operation is complete.
response:
anyOf:
- $ref: '#/components/schemas/ModelVersionUploadResponseData'
- type: 'null'
description: Response data with model version information.
additionalProperties: false
type: object
required:
- name
- done
title: ModelVersionUploadResponse
ModelVersionUploadRequestModel:
properties:
version_aliases:
anyOf:
- items:
type: string
pattern: ^[a-z][a-zA-Z0-9-]{0,126}[a-z0-9]$
type: array
- type: 'null'
title: Version Aliases
description: >-
Optional list of aliases that can be used to refer to this new
version instead of the autogenerated integer number. Must match
pattern: `^[a-z][a-zA-Z0-9-]{0,126}[a-z0-9]$`.
weight_uri:
type: string
pattern: ^s3://[a-zA-Z0-9.\-_/~]+$
title: Weight Uri
description: >-
S3 URI to customer-provided weights. Must match pattern:
`^s3://[a-zA-Z0-9.\-_/~]+$`.
system_fingerprint_suffix:
anyOf:
- type: string
pattern: ^[a-zA-Z0-9-]{1,64}$
- type: 'null'
title: System Fingerprint Suffix
description: >-
Optional custom suffix appended after the auto-generated fingerprint
pattern.
The final fingerprint will be
`fp_{backend_hash}_{model_arch_id}_v{version_id}_{custom_suffix}` if
provided, or just `fp_{backend_hash}_{model_arch_id}_v{version_id}`
if not.
Must match pattern: `^[a-zA-Z0-9-]{1,64}$`.
This suffix appears in the `system_fingerprint` field of inference
responses, allowing you to identify which model version served a
request.
Example response:
```
curl -X POST "https://api.cerebras.ai/v1/chat/completions" \
-H "Authorization: Bearer $CEREBRAS_API_KEY" \
-d '{"model": "my-org-gpt-oss-120b", "messages": [{"content": "Hello!", "role": "user"}]}'
# Response includes:
{"system_fingerprint":
"fp_70185065a4_gpt-oss-120b_v123_super-cool-version", ...}
```
In this example:
- `fp_70185065a4` - Cerebras backend configuration used to serve the
request
- `gpt-oss-120b` - Model architecture ID
- `123` - Model version ID
- `super-cool-version` - Custom suffix set during upload
additionalProperties: false
type: object
required:
- weight_uri
title: ModelVersionUploadRequestModel
ModelVersionUploadResponseData:
properties:
customer_s3_uri:
type: string
title: Customer S3 Uri
description: S3 URI provided by the customer.
version_aliases:
items:
type: string
type: array
title: Version Aliases
description: List of aliases that can be used to refer to this version.
sync_status:
$ref: '#/components/schemas/WeightSyncStatusEnum'
title: Sync Status
description: Status of the weight sync operation.
additionalProperties: false
type: object
required:
- customer_s3_uri
- version_aliases
- sync_status
title: ModelVersionUploadResponseData
WeightSyncStatusEnum:
type: string
enum:
- not_started
- queued
- in_progress
- done
- error
- skipped
title: WeightSyncStatusEnum
description: Enum representing the status of a weight sync operation.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Management API key generated from the `Management API keys` section on
the `API keys` page at https://cloud.cerebras.ai. Use the format:
`Bearer `
````