Documentation / API Reference / Create a new upload
Create a new upload Create an Upload session for a direct transfer to storage. Multipart creation returns every signed part URL. Retry parts with their original URLs and complete before expiry. Customer storage requires long-lived credentials and an incomplete-multipart lifecycle rule. Start a new Upload after abandoning a session.
Authorization Authorization
header
string
required
Enter the project access token with the Bearer prefix, e.g. "Bearer project_access_token"
Body application/json
Upload creation parameters
create_asset
default: false
boolean
CreateAsset specifies whether to create an Asset after Upload completion. Defaults to false.
Snapshots the Project output settings, including the path template. Referenced metadata must be non-empty in this request. Asset processing is billed separately.
FileSizeBytes specifies the exact file size in bytes. Required when UploadMode is omitted, auto, or multipart. Optional for explicit single mode. Must fit the team's Source size limit. Single PUT supports up to 5 GiB, subject to the provider's limit; multipart supports up to 5 TiB.
Required range: 1 <= x <= 5.49755813888e+12
Metadata allows for additional information to be attached to the upload, with a maximum size of 2048 bytes.
Examples:
map[key:value key2:value2]
Optional Storage override. Omit id to use the Project default. Customer-connected Storage requires path; Chunkify Storage generates its own path.
Show storage properties
Storage belonging to this Project. Omit to use the Project default.
Exact object key including filename, required for customer Storage and forbidden for Chunkify Storage. The output base_prefix is not added. Existing keys may be overwritten.
upload_mode
default: "auto"
string
UploadMode specifies the transfer method. Defaults to auto. Auto chooses multipart above 100 MiB and single PUT at or below 100 MiB for every Storage provider. Multipart requires a provider that supports the required multipart operations and signed part URLs. Provider failures return an error without falling back to single PUT.
Available options:
singlemultipartauto
ValidityTimeout specifies the session and signed URL lifetime in seconds. Single PUT defaults to 7200 and allows 300–36000. Multipart defaults to twice the transfer time at 5 Mbps plus 1800 seconds, bounded to 7200–172800; an explicit value allows 300–172800. Complete before expiry. Storage credentials and policies can shorten URL validity. Expired URLs cannot be refreshed.
Required range: 300 <= x <= 172800
WorkflowId specifies the Workflow to select. Omit to use the Project default. Set null to disable automatic actions. The current revision is pinned when creation is accepted.
Responses 201 400 401 403 429
application/json Data contains the response object
Show data properties
create_asset
boolean
required
Whether this Upload creates an Asset on completion.
created_at
string
date-time
required
Timestamp when the upload was created
Examples:
2025-01-01T12:00:00Z
expires_at
string
date-time
required
Timestamp when the upload will expire
Examples:
2025-01-01T12:00:00Z
Unique identifier of the upload
Examples:
upl_2G6MJiNz71bHQGNzGwKx5cJwPFS
Current status of the upload
Available options:
waitingcompletedfailedexpired
updated_at
string
date-time
required
Timestamp when the upload was updated
Examples:
2025-01-01T12:00:00Z
upload_mode
string
required
Resolved transfer mode for this Upload.
Available options:
singlemultipart
workflow_id
object
required
Selected Workflow ID, or null.
workflow_revision
object
required
Pinned Workflow revision, or null.
Automatically created Asset. May be absent before completion or after record deletion.
Completion capability, returned only on creation. POST after a successful single PUT or with all multipart ETags before expires_at. Requires no API key. Repeated valid calls are idempotent.
created_by_token_id
string
CreatedByTokenId specifies the Project token used to create the resource. It remains set after the token is revoked.
Omitted for dashboard requests, MCP OAuth connections, Workflow actions, and unknown creators.
Examples:
tok_2G6MJiNz71bHQGNzGwKx5cJwPFS
CreatedByUserId specifies the team member who created the resource.
Omitted for Workflow actions, unknown creators, and deleted accounts.
Examples:
u_2G6MJiNz71bHQGNzGwKx5cJwPFS
CreatedVia specifies how the resource was created: api for API requests, dashboard for the Chunkify dashboard, mcp for MCP clients, and workflow for Workflow actions.
Omitted when the creator is unknown.
Available options:
apidashboardmcpworkflow
Error message of the upload
Show error properties
Additional error details or output
Available options:
setupffmpegsourceuploaddownloadingestjobunexpectedpermissiontimeoutcancelled
Declared file size in bytes, when supplied at creation.
Required range: x >= 1
Additional metadata for the upload
Examples:
map[key1:value1 key2:value2]
Multipart transfer details, returned only on creation for multipart Uploads.
Show multipart properties
expires_at
string
date-time
required
ExpiresAt specifies when the signed part URLs expire. URLs cannot be refreshed; create a new Upload after expiry.
part_size_bytes
integer
required
PartSizeBytes specifies the size of each part except the final part, in bytes.
Required range: x >= 5.24288e+06
Parts contains every signed upload URL in ascending part_number order. Upload file slices directly to these URLs.
Show parts properties
part_number
integer
required
PartNumber specifies the one-based part number for this URL.
Required range: 1 <= x <= 10000
UploadUrl specifies the signed PUT URL for this part. Retry the same file slice with this URL before multipart.expires_at.
SourceId is the id of the source that was created from the upload
Examples:
src_2G6MJiNz71bHQGNzGwKx5cJwPFS
Resolved Storage selected when the Upload was created. Absent for historical uploads.
Presigned PUT URL, returned only when creating a single-PUT Upload session. Call completion_url after the PUT succeeds.
Examples:
https://s3.amazonaws.com/bucket/key
status
"success"
string
required
Status indicates the response status "success"
The upload was created successfully
application/json Show error properties
Code is the HTTP status code
Message is a human-readable error description
Examples:
Invalid request parameters
type
"ValidationError"
string
required
Type indicates the error category
Available options:
ValidationError
status
"error"
string
required
Status indicates the response status "error"
Invalid request parameters
application/json Error response details
Show error properties
Code is the HTTP status code
Message is a human-readable error description
Examples:
Authentication error: invalid token or subscription inactive
type
"AuthenticationError"
string
required
Type indicates the error category
Available options:
AuthenticationError
status
"error"
string
required
Status indicates the response status "error"
Authentication error: invalid token or subscription inactive
application/json Error response details
Show error properties
Code is the HTTP status code
Message is a human-readable error description
Examples:
Unauthorized to perform this action
type
"ForbiddenError"
string
required
Type indicates the error category
Available options:
ForbiddenError
status
"error"
string
required
Status indicates the response status "error"
Unauthorized to perform this action: insufficient funds
application/json Error response details
Show error properties
Code is the HTTP status code
Message is a human-readable error description
Examples:
Rate limit exceeded
type
"TooManyRequestsError"
string
required
Type indicates the error category
Available options:
TooManyRequestsError
status
"error"
string
required
Status indicates the response status "error"
Rate limit exceeded
# Create a new upload
> Create an Upload session for a direct transfer to storage. Multipart creation returns every signed part URL. Retry parts with their original URLs and complete before expiry. Customer storage requires long-lived credentials and an incomplete-multipart lifecycle rule. Start a new Upload after abandoning a session.
```json
{
"path": "/uploads",
"method": "post",
"schema": {
"description": "Create an Upload session for a direct transfer to storage. Multipart creation returns every signed part URL. Retry parts with their original URLs and complete before expiry. Customer storage requires long-lived credentials and an incomplete-multipart lifecycle rule. Start a new Upload after abandoning a session.",
"operationId": "createUpload",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadCreateParams"
}
}
},
"description": "Upload creation parameters",
"required": true,
"x-originalParamName": "request"
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"multipart": {
"summary": "Explicit multipart session",
"value": {
"data": {
"completion_url": "https://api.chunkify.dev/v1/uploads/completion/EXAMPLE_TOKEN",
"create_asset": false,
"created_at": "2026-01-01T12:00:00Z",
"expires_at": "2026-01-01T14:00:00Z",
"file_size_bytes": 40000000,
"id": "upl_2G6MJiNz71bHQGNzGwKx5cJwPFS",
"multipart": {
"expires_at": "2026-01-01T14:00:00Z",
"part_size_bytes": 33554432,
"parts": [
{
"part_number": 1,
"upload_url": "https://bucket.s3.us-east-1.amazonaws.com/uploads/file.bin?partNumber=1\u0026uploadId=EXAMPLE\u0026SIGNED_PART_QUERY"
},
{
"part_number": 2,
"upload_url": "https://bucket.s3.us-east-1.amazonaws.com/uploads/file.bin?partNumber=2\u0026uploadId=EXAMPLE\u0026SIGNED_PART_QUERY"
}
]
},
"status": "waiting",
"updated_at": "2026-01-01T12:00:00Z",
"upload_mode": "multipart",
"workflow_id": null,
"workflow_revision": null
},
"status": "success"
}
},
"single": {
"summary": "Single PUT session",
"value": {
"data": {
"completion_url": "https://api.chunkify.dev/v1/uploads/completion/EXAMPLE_TOKEN",
"create_asset": false,
"created_at": "2026-01-01T12:00:00Z",
"expires_at": "2026-01-01T14:00:00Z",
"id": "upl_2G6MJiNz71bHQGNzGwKx5cJwPFS",
"status": "waiting",
"updated_at": "2026-01-01T12:00:00Z",
"upload_mode": "single",
"upload_url": "https://bucket.s3.us-east-1.amazonaws.com/uploads/file.bin?SIGNED_PUT_QUERY",
"workflow_id": null,
"workflow_revision": null
},
"status": "success"
}
}
},
"schema": {
"$ref": "#/components/schemas/UploadResponse"
}
}
},
"description": "The upload was created successfully"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseErrorValidation"
}
}
},
"description": "Invalid request parameters"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseErrorAuthentication"
}
}
},
"description": "Authentication error: invalid token or subscription inactive"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseErrorForbidden"
}
}
},
"description": "Unauthorized to perform this action: insufficient funds"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseErrorTooManyRequests"
}
}
},
"description": "Rate limit exceeded"
}
},
"security": [
{
"ProjectAccessToken": []
}
],
"summary": "Create a new upload",
"tags": [
"Uploads"
],
"x-codeSamples": [
{
"lang": "JavaScript",
"source": "import Chunkify from '@chunkify/chunkify';\n\nconst client = new Chunkify({\n projectAccessToken: 'My Project Access Token',\n});\n\nconst upload = await client.uploads.create({\n file_size_bytes: 104857600,\n});\n\nconsole.log(upload);"
},
{
"lang": "Python",
"source": "from chunkify import Chunkify\n\nclient = Chunkify(\n project_access_token=\"My Project Access Token\",\n)\nupload = client.uploads.create(\n file_size_bytes=104857600,\n)\nprint(upload)"
},
{
"lang": "php",
"source": "\u003c?php\n\nuse Chunkify\\Client;\n\n$client = new Client(\n projectAccessToken: 'My Project Access Token',\n);\n\n$upload = $client-\u003euploads-\u003ecreate(\n fileSizeBytes: 104857600,\n);\n\nvar_dump($upload);"
},
{
"lang": "Go",
"source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/chunkifydev/chunkify-go\"\n\t\"github.com/chunkifydev/chunkify-go/option\"\n)\n\nfunc main() {\n\tclient := chunkify.NewClient(\n\t\toption.WithProjectAccessToken(\"My Project Access Token\"),\n\t)\n\tupload, err := client.Uploads.New(context.TODO(), chunkify.UploadNewParams{\n\t\tFileSizeBytes: chunkify.Int(104857600),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", upload)\n}\n"
}
]
}
}
```
```json #/components/schemas/ResponseErrorValidation
{
"properties": {
"error": {
"properties": {
"code": {
"const": 400,
"description": "Code is the HTTP status code",
"examples": [
400
],
"type": "integer"
},
"message": {
"description": "Message is a human-readable error description",
"examples": [
"Invalid request parameters"
],
"type": "string"
},
"type": {
"const": "ValidationError",
"description": "Type indicates the error category",
"enum": [
"ValidationError"
],
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
},
"status": {
"const": "error",
"description": "Status indicates the response status \"error\"",
"type": "string"
}
},
"required": [
"status",
"error"
]
}
```
```json #/components/schemas/ResponseErrorAuthentication
{
"description": "Error response",
"properties": {
"error": {
"description": "Error response details",
"properties": {
"code": {
"const": 401,
"description": "Code is the HTTP status code",
"examples": [
401
],
"type": "integer"
},
"message": {
"description": "Message is a human-readable error description",
"examples": [
"Authentication error: invalid token or subscription inactive"
],
"type": "string"
},
"type": {
"const": "AuthenticationError",
"description": "Type indicates the error category",
"enum": [
"AuthenticationError"
],
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
},
"status": {
"const": "error",
"description": "Status indicates the response status \"error\"",
"type": "string"
}
},
"required": [
"status",
"error"
],
"type": "object"
}
```
```json #/components/schemas/ResponseErrorForbidden
{
"properties": {
"error": {
"description": "Error response details",
"properties": {
"code": {
"const": 403,
"description": "Code is the HTTP status code",
"examples": [
403
],
"type": "integer"
},
"message": {
"description": "Message is a human-readable error description",
"examples": [
"Unauthorized to perform this action"
],
"type": "string"
},
"type": {
"const": "ForbiddenError",
"description": "Type indicates the error category",
"enum": [
"ForbiddenError"
],
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
},
"status": {
"const": "error",
"description": "Status indicates the response status \"error\"",
"type": "string"
}
},
"required": [
"status",
"error"
]
}
```
```json #/components/schemas/ResponseErrorTooManyRequests
{
"description": "Error response",
"properties": {
"error": {
"description": "Error response details",
"properties": {
"code": {
"const": 429,
"description": "Code is the HTTP status code",
"examples": [
429
],
"type": "integer"
},
"message": {
"description": "Message is a human-readable error description",
"examples": [
"Rate limit exceeded"
],
"type": "string"
},
"type": {
"const": "TooManyRequestsError",
"description": "Type indicates the error category",
"enum": [
"TooManyRequestsError"
],
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
},
"status": {
"const": "error",
"description": "Status indicates the response status \"error\"",
"type": "string"
}
},
"required": [
"status",
"error"
],
"type": "object"
}
```
```json #/components/schemas/UploadCreateParams
{
"properties": {
"create_asset": {
"default": false,
"description": "CreateAsset specifies whether to create an Asset after Upload completion. Defaults to false.\nSnapshots the Project output settings, including the path template. Referenced metadata must be non-empty in this request. Asset processing is billed separately.",
"type": "boolean"
},
"file_size_bytes": {
"description": "FileSizeBytes specifies the exact file size in bytes. Required when UploadMode is omitted, auto, or multipart. Optional for explicit single mode. Must fit the team's Source size limit. Single PUT supports up to 5 GiB, subject to the provider's limit; multipart supports up to 5 TiB.",
"maximum": 5497558138880,
"minimum": 1,
"type": "integer"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"description": "Metadata allows for additional information to be attached to the upload, with a maximum size of 2048 bytes.",
"examples": [
{
"key": "value",
"key2": "value2"
}
],
"type": "object"
},
"storage": {
"$ref": "#/components/schemas/UploadCreateStorageParams",
"description": "Optional Storage override. Omit id to use the Project default. Customer-connected Storage requires path; Chunkify Storage generates its own path."
},
"upload_mode": {
"default": "auto",
"description": "UploadMode specifies the transfer method. Defaults to auto. Auto chooses multipart above 100 MiB and single PUT at or below 100 MiB for every Storage provider. Multipart requires a provider that supports the required multipart operations and signed part URLs. Provider failures return an error without falling back to single PUT.",
"enum": [
"single",
"multipart",
"auto"
],
"type": "string"
},
"validity_timeout": {
"description": "ValidityTimeout specifies the session and signed URL lifetime in seconds. Single PUT defaults to 7200 and allows 300–36000. Multipart defaults to twice the transfer time at 5 Mbps plus 1800 seconds, bounded to 7200–172800; an explicit value allows 300–172800. Complete before expiry. Storage credentials and policies can shorten URL validity. Expired URLs cannot be refreshed.",
"examples": [
7200
],
"maximum": 172800,
"minimum": 300,
"type": "integer"
},
"workflow_id": {
"description": "WorkflowId specifies the Workflow to select. Omit to use the Project default. Set null to disable automatic actions. The current revision is pinned when creation is accepted.",
"maxLength": 64,
"minLength": 1,
"type": [
"string",
"null"
]
}
},
"type": "object",
"x-reject-null-fields": [
"create_asset"
]
}
```
```json #/components/schemas/UploadCreateStorageParams
{
"additionalProperties": false,
"properties": {
"id": {
"description": "Storage belonging to this Project. Omit to use the Project default.",
"minLength": 1,
"type": "string"
},
"path": {
"description": "Exact object key including filename, required for customer Storage and forbidden for Chunkify Storage. The output base_prefix is not added. Existing keys may be overwritten.",
"maxLength": 1024,
"minLength": 1,
"type": "string",
"x-maxBytes": 1024
}
},
"type": "object"
}
```
```json #/components/schemas/UploadResponse
{
"properties": {
"data": {
"$ref": "#/components/schemas/Upload",
"description": "Data contains the response object"
},
"status": {
"const": "success",
"description": "Status indicates the response status \"success\"",
"type": "string"
}
},
"required": [
"status",
"data"
],
"type": "object"
}
```
```json #/components/schemas/Upload
{
"properties": {
"asset_id": {
"description": "Automatically created Asset. May be absent before completion or after record deletion.",
"type": "string"
},
"completion_url": {
"description": "Completion capability, returned only on creation. POST after a successful single PUT or with all multipart ETags before expires_at. Requires no API key. Repeated valid calls are idempotent.",
"type": "string"
},
"create_asset": {
"description": "Whether this Upload creates an Asset on completion.",
"type": "boolean"
},
"created_at": {
"description": "Timestamp when the upload was created",
"examples": [
"2025-01-01T12:00:00Z"
],
"format": "date-time",
"type": "string"
},
"created_by_token_id": {
"description": "CreatedByTokenId specifies the Project token used to create the resource. It remains set after the token is revoked.\nOmitted for dashboard requests, MCP OAuth connections, Workflow actions, and unknown creators.",
"examples": [
"tok_2G6MJiNz71bHQGNzGwKx5cJwPFS"
],
"type": "string"
},
"created_by_user_id": {
"description": "CreatedByUserId specifies the team member who created the resource.\nOmitted for Workflow actions, unknown creators, and deleted accounts.",
"examples": [
"u_2G6MJiNz71bHQGNzGwKx5cJwPFS"
],
"type": "string"
},
"created_via": {
"$ref": "#/components/schemas/CreatedVia"
},
"error": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkifyError"
}
],
"description": "Error message of the upload"
},
"expires_at": {
"description": "Timestamp when the upload will expire",
"examples": [
"2025-01-01T12:00:00Z"
],
"format": "date-time",
"type": "string"
},
"file_size_bytes": {
"description": "Declared file size in bytes, when supplied at creation.",
"minimum": 1,
"type": "integer"
},
"id": {
"description": "Unique identifier of the upload",
"examples": [
"upl_2G6MJiNz71bHQGNzGwKx5cJwPFS"
],
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"description": "Additional metadata for the upload",
"examples": [
{
"key1": "value1",
"key2": "value2"
}
],
"type": "object"
},
"multipart": {
"$ref": "#/components/schemas/UploadMultipartSession",
"description": "Multipart transfer details, returned only on creation for multipart Uploads."
},
"source_id": {
"description": "SourceId is the id of the source that was created from the upload",
"examples": [
"src_2G6MJiNz71bHQGNzGwKx5cJwPFS"
],
"type": "string"
},
"status": {
"description": "Current status of the upload",
"enum": [
"waiting",
"completed",
"failed",
"expired"
],
"examples": [
"waiting"
],
"type": "string"
},
"storage_id": {
"description": "Resolved Storage selected when the Upload was created. Absent for historical uploads.",
"type": "string"
},
"updated_at": {
"description": "Timestamp when the upload was updated",
"examples": [
"2025-01-01T12:00:00Z"
],
"format": "date-time",
"type": "string"
},
"upload_mode": {
"description": "Resolved transfer mode for this Upload.",
"enum": [
"single",
"multipart"
],
"type": "string"
},
"upload_url": {
"description": "Presigned PUT URL, returned only when creating a single-PUT Upload session. Call completion_url after the PUT succeeds.",
"examples": [
"https://s3.amazonaws.com/bucket/key"
],
"type": "string"
},
"workflow_id": {
"description": "Selected Workflow ID, or null.",
"type": [
"string",
"null"
]
},
"workflow_revision": {
"description": "Pinned Workflow revision, or null.",
"type": [
"integer",
"null"
]
}
},
"required": [
"created_at",
"expires_at",
"id",
"status",
"updated_at",
"create_asset",
"workflow_id",
"workflow_revision",
"upload_mode"
],
"type": "object"
}
```
```json #/components/schemas/CreatedVia
{
"description": "CreatedVia specifies how the resource was created: api for API requests, dashboard for the Chunkify dashboard, mcp for MCP clients, and workflow for Workflow actions.\nOmitted when the creator is unknown.",
"enum": [
"api",
"dashboard",
"mcp",
"workflow"
],
"examples": [
"api"
],
"type": "string"
}
```
```json #/components/schemas/ChunkifyError
{
"properties": {
"detail": {
"description": "Additional error details or output",
"type": "string"
},
"message": {
"description": "Main error message",
"type": "string"
},
"type": {
"description": "Type of error",
"enum": [
"setup",
"ffmpeg",
"source",
"upload",
"download",
"ingest",
"job",
"unexpected",
"permission",
"timeout",
"cancelled"
],
"type": "string"
}
},
"required": [
"type",
"message",
"detail"
],
"type": "object"
}
```
```json #/components/schemas/UploadMultipartSession
{
"properties": {
"expires_at": {
"description": "ExpiresAt specifies when the signed part URLs expire. URLs cannot be refreshed; create a new Upload after expiry.",
"format": "date-time",
"type": "string"
},
"part_size_bytes": {
"description": "PartSizeBytes specifies the size of each part except the final part, in bytes.",
"minimum": 5242880,
"type": "integer"
},
"parts": {
"description": "Parts contains every signed upload URL in ascending part_number order. Upload file slices directly to these URLs.",
"items": {
"$ref": "#/components/schemas/UploadMultipartSignedPart"
},
"maxItems": 10000,
"minItems": 1,
"type": "array"
}
},
"required": [
"part_size_bytes",
"parts",
"expires_at"
],
"type": "object"
}
```
```json #/components/schemas/UploadMultipartSignedPart
{
"properties": {
"part_number": {
"description": "PartNumber specifies the one-based part number for this URL.",
"maximum": 10000,
"minimum": 1,
"type": "integer"
},
"upload_url": {
"description": "UploadUrl specifies the signed PUT URL for this part. Retry the same file slice with this URL before multipart.expires_at.",
"type": "string"
}
},
"required": [
"part_number",
"upload_url"
],
"type": "object"
}
```