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

# Create Upload Request

> Creates a new upload request to process a media file from a URL. The file will be processed asynchronously.

Creates a new upload request to process a media file from a URL. The file will be processed asynchronously.


## OpenAPI

````yaml POST /upload
openapi: 3.0.3
info:
  title: Nivo public API
  version: 1.0.0
  description: >-
    Public API for Nivo: upload requests from URLs, and searching videos within
    a collection.
servers:
  - url: https://app.nivo.video/api/v1
    description: Production server
security: []
paths:
  /upload:
    post:
      summary: Create Upload Request
      description: >-
        Creates a new upload request to process a media file from a URL. The
        file will be processed asynchronously.
      operationId: createUploadRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequest'
            examples:
              basic_upload:
                summary: Basic upload request
                value:
                  url: https://example.com/video.mp4
                  collection_id: 123e4567-e89b-12d3-a456-426614174000
                  title: Sample Video
                  description: A sample video for processing
              full_upload:
                summary: Complete upload request with all fields
                value:
                  url: https://example.com/presentation.mp4
                  collection_id: 123e4567-e89b-12d3-a456-426614174000
                  folder_id: 987fcdeb-51a2-43d7-8f9e-123456789abc
                  title: Company Presentation
                  description: Q4 2024 company presentation video
                  tags:
                    - presentation
                    - q4
                    - '2024'
                  metadata:
                    department: marketing
                    quarter: Q4
                    year: '2024'
      responses:
        '201':
          description: Upload request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
              examples:
                success:
                  summary: Successful upload request creation
                  value:
                    uploadRequestId: 550e8400-e29b-41d4-a716-446655440000
        '400':
          description: Bad request - validation failed or file too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Validation failed
                  value:
                    message: Validation failed
                    errors:
                      url:
                        - Invalid url
                      collection_id:
                        - Invalid uuid
                file_too_large:
                  summary: File size exceeds limit
                  value:
                    message: Input size is too large.
                upload_failed:
                  summary: Upload processing failed
                  value:
                    message: Failed to upload source video URL.
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Missing or invalid API key
                  value:
                    message: Unauthorized.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    UploadRequest:
      type: object
      required:
        - url
        - collection_id
      properties:
        url:
          type: string
          format: uri
          description: >-
            URL of the media file to be processed. Must be a valid HTTP/HTTPS
            URL.
          example: https://example.com/video.mp4
        collection_id:
          type: string
          format: uuid
          description: UUID of the collection where the processed file will be stored.
          example: 123e4567-e89b-12d3-a456-426614174000
        folder_id:
          type: string
          format: uuid
          nullable: true
          description: Optional UUID of the folder within the collection.
          example: 987fcdeb-51a2-43d7-8f9e-123456789abc
        title:
          type: string
          nullable: true
          description: Optional title for the upload.
          example: Sample Video Title
        description:
          type: string
          nullable: true
          description: Optional description for the upload.
          example: This is a sample video for processing
        tags:
          type: array
          items:
            type: string
          nullable: true
          description: Optional array of tags to categorize the upload.
          example:
            - video
            - presentation
            - '2024'
        metadata:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Optional key-value pairs for additional metadata.
          example:
            department: marketing
            project: Q4-campaign
    UploadResponse:
      type: object
      required:
        - uploadRequestId
      properties:
        uploadRequestId:
          type: string
          format: uuid
          description: Unique identifier for the created upload request.
          example: 550e8400-e29b-41d4-a716-446655440000
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Error message describing what went wrong.
          example: Validation failed
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Detailed validation errors by field (only present for validation
            failures).
          example:
            url:
              - Invalid url
            collection_id:
              - Invalid uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key for authentication. Include your company's API key in the
        Authorization header.

````