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

# Create a direct upload session

> Create a signed object-storage upload URL and optional TUS resumable upload configuration. After uploading bytes to storage, call `POST /api/uploads/complete` with the returned `complete.body` payload.



## OpenAPI

````yaml /openapi.json post /api/uploads
openapi: 3.1.0
info:
  title: Convertly API
  version: 1.0.0
  description: >-
    Convertly provides production API endpoints for media conversion,
    compression, Image CDN delivery, Forma AI, HLS/DASH video streaming, media
    tools, async jobs, workflows, webhooks, and Convertly Storage.
  license:
    name: Proprietary
    url: https://convertly.sh/terms
servers:
  - url: https://convertly.sh
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /api/uploads:
    post:
      tags:
        - Files
      summary: Create a direct upload session
      description: >-
        Create a signed object-storage upload URL and optional TUS resumable
        upload configuration. After uploading bytes to storage, call `POST
        /api/uploads/complete` with the returned `complete.body` payload.
      operationId: createUploadSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadSessionRequest'
      responses:
        '201':
          description: Upload session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSessionResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    CreateUploadSessionRequest:
      type: object
      properties:
        filename:
          type: string
          minLength: 1
          maxLength: 180
        contentType:
          type: string
          default: application/octet-stream
        sizeBytes:
          type: integer
          minimum: 1
        folderId:
          type:
            - string
            - 'null'
          format: uuid
        resumable:
          type: boolean
          default: true
      required:
        - filename
        - sizeBytes
    UploadSessionResponse:
      type: object
      properties:
        upload:
          type: object
          properties:
            bucket:
              type: string
            path:
              type: string
            signedUrl:
              type: string
              format: uri
            token:
              type: string
            method:
              type: string
              enum:
                - PUT
            expiresInSeconds:
              type: integer
          required:
            - bucket
            - path
            - signedUrl
            - token
            - method
            - expiresInSeconds
        resumable:
          type:
            - object
            - 'null'
          properties:
            protocol:
              type: string
              enum:
                - tus
            endpoint:
              type: string
              format: uri
            chunkSize:
              type: integer
            headers:
              type: object
              additionalProperties:
                type: string
            metadata:
              type: object
              additionalProperties:
                type: string
        complete:
          type: object
          properties:
            url:
              type: string
              format: uri
            body:
              $ref: '#/components/schemas/CompleteUploadRequest'
          required:
            - url
            - body
      required:
        - upload
        - complete
    CompleteUploadRequest:
      type: object
      properties:
        path:
          type: string
          minLength: 1
        filename:
          type: string
          minLength: 1
          maxLength: 180
        contentType:
          type: string
          default: application/octet-stream
        sizeBytes:
          type: integer
          minimum: 1
        folderId:
          type:
            - string
            - 'null'
          format: uuid
      required:
        - path
        - filename
        - sizeBytes
    Error:
      type: object
      properties:
        error:
          type: string
        upgradeUrl:
          type: string
      required:
        - error
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Dashboard-generated Convertly API key. Keys currently begin with
        `cvly_`.
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative API key header for server-side clients.

````