# Create a new upload entry

Creates a new upload record and returns an upload URL where the file content should be PUT. This is the first step of the two-step upload flow. Requires authentication.

Endpoint: POST /api/v1/uploads
Version: 1.0
Security: 

## Request fields (application/json):

  - `extension` (string, required)

  - `isGzipped` (boolean)

  - `meta` (object,null)
    User meta attached to upload. Can contain information like name etc.
    Example: {"name":"value"}

  - `meta.blurhash` (string,null)

  - `meta.name` (string,null)
    Example: "value"

  - `meta.altText` (string,null)

  - `tags` (array)
    Tags attached to the upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `privacy` (string,null)
    Privacy of the upload. Possible values: PUBLIC, PRIVATE, DIRECT.
    Enum: "Public", "Private", "Direct"

  - `allowedUsers` (array,null)
    Can contain a list of users who are allowed to access the upload.
        Works only for uploads with privacy set to DIRECT.

  - `ownerId` (string,null)
    Optional owner entity for this upload. When not provided, defaults to the uploading user. Can be a channel, category, or event TypeID. The uploader must have permission to upload for this owner.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

## Response 200 fields (application/json):

  - `uri` (string, required)

  - `upload` (object, required)
    Uploaded file

  - `upload.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `upload.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `upload.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `upload.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `upload.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `upload.meta` (object)
    Meta data

  - `upload.meta.blurhash` (string,null)

  - `upload.meta.name` (string,null)

  - `upload.meta.altText` (string,null)

  - `upload.size` (integer, required)
    Size in bytes of all the files in this upload

  - `upload.files` (array, required)
    List of all the files this upload has

  - `upload.files.uri` (string,null, required)
    Full url of the file

  - `upload.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `upload.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `upload.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `upload.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `upload.files.meta.duration` (number,null)
    Video duration in seconds

  - `upload.files.meta.width` (integer,null)
    Media width

  - `upload.files.meta.height` (integer,null)
    Media height

  - `upload.files.meta.codec` (string,null)
    Video codec

  - `upload.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `upload.files.size` (integer, required)
    File size in bytes

  - `upload.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `upload.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `upload.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `upload.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `upload.error` (string,null)
    Upload processing error

  - `upload.cached` (boolean)
    true if cached

  - `upload.logs` (string,null)
    Logs

  - `upload.remote` (boolean)
    true if this upload is remote

  - `upload.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `upload.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

## Response 400 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 401 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 403 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation