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

# Start a video upload



## OpenAPI

````yaml /openapi.yaml post /v1/videos
openapi: 3.1.0
info:
  title: VTurb API
  version: v1
  description: |
    Public REST API for VTurb. Dev-first and agents-first: every documented
    response is recorded from the API's real behavior.
  contact:
    name: VTurb API
    url: https://vturb.com
servers:
  - url: https://api.vturb.com
security:
  - bearerAuth: []
paths:
  /v1/videos:
    post:
      tags:
        - Videos
      summary: Start a video upload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Display name for the video.
                  maxLength: 255
                  example: Landing hero
                filename:
                  type: string
                  description: >-
                    Original filename; only its extension is kept for the stored
                    object.
                  maxLength: 255
                  example: hero.mp4
                type:
                  type: string
                  description: Video MIME type (allowlist); set on the stored object.
                  enum:
                    - video/mp4
                    - video/quicktime
                    - video/webm
                  example: video/mp4
                size:
                  type: integer
                  description: >-
                    Declared size of the file in bytes (max 15GB). The upload is
                    split into `part_size` slices — one presigned URL per part
                    in `upload.parts`.
                  format: int64
                  minimum: 1
                  maximum: 16106127360
                  example: 12582912
                folder_id:
                  type: string
                  description: Optional folder to place the video in.
                part_size:
                  type: integer
                  description: >-
                    Optional slice size in bytes (default 1GB). Each part URL
                    only accepts exactly this many bytes (the last part takes
                    the remainder). Browser clients usually want smaller slices.
                  format: int64
                  minimum: 10485760
                  maximum: 5368709120
                  example: 104857600
              required:
                - name
                - filename
                - type
                - size
            example:
              name: Landing hero
              filename: hero.mp4
              type: video/mp4
              size: 12582912
              folder_id: 6890000000000000000000a1
              part_size: 104857600
      responses:
        '201':
          description: accepts an optional part_size and slices the upload with it
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - awaiting_upload
                      - processing
                      - ready
                      - expired
                  upload:
                    type: object
                    properties:
                      expires_at:
                        type: string
                      part_size:
                        type: integer
                      parts:
                        type: array
                        items:
                          type: object
                          properties:
                            part_number:
                              type: integer
                            url:
                              type: string
                          required:
                            - part_number
                            - url
                    required:
                      - expires_at
                      - part_size
                      - parts
                  complete_url:
                    type: string
                required:
                  - id
                  - status
                  - upload
                  - complete_url
              example:
                id: 652f2b1e8f1b2c3d4e5f6a7b
                status: awaiting_upload
                upload:
                  expires_at: '2026-07-30T12:15:00Z'
                  part_size: 1073741824
                  parts:
                    - part_number: 1
                      url: >-
                        https://s3.amazonaws.com/vturb-uploads/org_123/x/original.mp4?partNumber=1&uploadId=mpu1&X-Amz-Signature=abc
                complete_url: /v1/videos/652f2b1e8f1b2c3d4e5f6a7b/upload/completion
        '400':
          description: An unrecognized field 400s instead of being silently dropped.
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
                  field:
                    type: string
                  request_id:
                    type: string
                required:
                  - type
                  - code
                  - message
                  - field
                  - request_id
              example:
                type: https://docs.vturb.com/errors/bad_request
                code: bad_request
                message: The request includes fields this endpoint does not accept.
                field: nope
                request_id: 00000000-0000-0000-0000-000000000000
        '401':
          description: Missing API credential.
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
                  request_id:
                    type: string
                required:
                  - type
                  - code
                  - message
                  - request_id
              example:
                type: https://docs.vturb.com/errors/unauthorized
                code: unauthorized
                message: >-
                  Missing or invalid API credential. Send a vt_ token in the
                  Authorization header.
                request_id: 00000000-0000-0000-0000-000000000000
        '403':
          description: The credential is missing the videos:upload scope.
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
                  request_id:
                    type: string
                required:
                  - type
                  - code
                  - message
                  - request_id
              example:
                type: https://docs.vturb.com/errors/forbidden
                code: forbidden
                message: The credential is missing the scope this action requires.
                request_id: 00000000-0000-0000-0000-000000000000
        '422':
          description: Validation failed — every rejected field is named at once.
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
                  request_id:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - message
                required:
                  - type
                  - code
                  - message
                  - request_id
                  - errors
              example:
                type: https://docs.vturb.com/errors/unprocessable_content
                code: unprocessable_content
                message: The request is invalid. See errors for the fields that failed.
                request_id: 00000000-0000-0000-0000-000000000000
                errors:
                  - field: type
                    message: is not a supported video type
                  - field: size
                    message: must be an integer number of bytes
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Paste your VTurb API token (vt_...). Sent as `Authorization: Bearer
        <token>`.

````