Platform Integration API Reference CLI Benchmarks

Uploads

Create a new upload

Create a new upload with the specified name.

POST

/api/uploads

Authorization

Authorization

header

string

required

Enter the project access token with the Bearer prefix, e.g. "Bearer project_access_token"

Bodyapplication/json

Upload creation parameters

metadata

object

Metadata allows for additional information to be attached to the upload, with a maximum size of 2048 bytes.

Examples:

map[key:value key2:value2]

storage

object

Optional Storage override. Omit id to use the Project default. Customer-connected Storage requires path; Chunkify Storage generates its own path.

validity_timeout

default: 7200

integer

Both the file PUT and completion POST must finish within this timeout in seconds

Required range: 300 <= x <= 36000

Examples:

7200

Responses

application/json

data

object

required

Data contains the response object

status

"success"

string

required

Status indicates the response status "success"

The upload was created successfully

application/json

error

object

required

status

"error"

string

required

Status indicates the response status "error"

Invalid request parameters

application/json

error

object

required

Error response details

status

"error"

string

required

Status indicates the response status "error"

Authentication error: invalid token or subscription inactive

application/json

error

object

required

Error response details

status

"error"

string

required

Status indicates the response status "error"

Unauthorized to perform this action: insufficient funds

application/json

error

object

required

Error response details

status

"error"

string

required

Status indicates the response status "error"

Rate limit exceeded

import Chunkify from '@chunkify/chunkify';

const client = new Chunkify({
  projectAccessToken: 'My Project Access Token',
});

const upload = await client.uploads.create();

console.log(upload);
from chunkify import Chunkify

client = Chunkify(
    project_access_token="My Project Access Token",
)
upload = client.uploads.create()
print(upload)
<?php

use Chunkify\Client;

$client = new Client(
    projectAccessToken: 'My Project Access Token',
);

$upload = $client->uploads->create();

var_dump($upload);
package main

import (
  "context"
  "fmt"

  "github.com/chunkifydev/chunkify-go"
  "github.com/chunkifydev/chunkify-go/option"
)

func main() {
  client := chunkify.NewClient(
    option.WithProjectAccessToken("My Project Access Token"),
  )
  upload, err := client.Uploads.New(context.TODO(), chunkify.UploadNewParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", upload)
}

{
  "data": {
    "created_at": "2025-01-01T12:00:00Z",
    "expires_at": "2025-01-01T12:00:00Z",
    "id": "upl_2G6MJiNz71bHQGNzGwKx5cJwPFS",
    "status": "waiting",
    "updated_at": "2025-01-01T12:00:00Z"
  },
  "status": "success"
}
{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "ValidationError"
  },
  "status": "error"
}
{
  "error": {
    "code": 401,
    "message": "Authentication error: invalid token or subscription inactive",
    "type": "AuthenticationError"
  },
  "status": "error"
}
{
  "error": {
    "code": 403,
    "message": "Unauthorized to perform this action",
    "type": "ForbiddenError"
  },
  "status": "error"
}
{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "type": "TooManyRequestsError"
  },
  "status": "error"
}

# Create a new upload > Create a new upload with the specified name. ```json { "path": "/api/uploads", "method": "post", "schema": { "description": "Create a new upload with the specified name.", "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": { "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\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()\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\nvar_dump($upload);" }, { "lang": "Go", "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n \"github.com/chunkifydev/chunkify-go\"\n \"github.com/chunkifydev/chunkify-go/option\"\n)\n\nfunc main() {\n client := chunkify.NewClient(\n option.WithProjectAccessToken(\"My Project Access Token\"),\n )\n upload, err := client.Uploads.New(context.TODO(), chunkify.UploadNewParams{\n\n })\n if err != nil {\n panic(err.Error())\n }\n fmt.Printf(\"%+v\\n\", upload)\n}\n" } ] } } ``` ```json #/components/schemas/UploadCreateParams { "properties": { "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." }, "validity_timeout": { "default": 7200, "description": "Both the file PUT and completion POST must finish within this timeout in seconds", "examples": [ 7200 ], "maximum": 36000, "minimum": 300, "type": "integer" } }, "type": "object" } ``` ```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": { "completion_url": { "description": "Short-lived completion capability, returned only on creation. POST after a successful PUT before expires_at. Requires no API key. Repeated valid calls are idempotent.", "type": "string" }, "created_at": { "description": "Timestamp when the upload was created", "examples": [ "2025-01-01T12:00:00Z" ], "format": "date-time", "type": "string" }, "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" }, "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" }, "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_url": { "description": "Presigned PUT URL, returned only when creating an Upload session. Call completion_url after the PUT succeeds.", "examples": [ "https://s3.amazonaws.com/bucket/key" ], "type": "string" } }, "required": [ "created_at", "expires_at", "id", "status", "updated_at" ], "type": "object" } ``` ```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/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" } ```