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

# Create an upload job

> Upload a rendered quiz video to YouTube. Requires a completed render job and connected YouTube channel. Returns 202 Accepted.



## OpenAPI

````yaml api-reference/openapi.json post /api/v1/youtube/uploads
openapi: 3.1.0
info:
  title: Quiz Quail API
  version: 1.0.0
  description: >-
    The Quiz Quail API lets you create, manage, and render quiz videos
    programmatically. Build quizzes with multiple rounds and question types,
    apply custom themes, render to video, upload to YouTube, and use AI to
    generate quizzes from topics.


    ## Authentication


    All endpoints require a Bearer token (API key). Include it in the
    `Authorization` header:


    ```

    Authorization: Bearer qq_your_api_key_here

    ```


    API keys can be scoped to specific permissions. See the security schemes
    below for available scopes.


    ## Rate Limiting


    Requests are rate-limited per user:

    - **Read** endpoints: 300 requests/minute

    - **Write** endpoints: 30 requests/minute

    - **AI** endpoints: 5 requests/minute

    - **Render** endpoints: 10 requests/hour


    Rate limit headers are included in every response.


    ## Pagination


    List endpoints use cursor-based pagination. Pass the `cursor` from the
    previous response to get the next page. The `hasMore` field indicates
    whether more items exist.


    ## Errors


    Errors follow [RFC 9457 Problem
    Details](https://www.rfc-editor.org/rfc/rfc9457). Every error response
    includes `type`, `title`, `status`, and `detail` fields.
  contact:
    name: Quiz Quail
    url: https://quizquail.com
servers:
  - url: https://quizquail.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Quizzes
    description: Create and manage quizzes, rounds, and questions
  - name: Themes
    description: Create and manage visual themes for quizzes
  - name: Media
    description: Upload, manage, and search media files
  - name: Renders
    description: Render quizzes to video and download results
  - name: Thumbnails
    description: Generate video thumbnails
  - name: YouTube
    description: Upload videos to YouTube and manage uploads
  - name: Webhooks
    description: Register webhooks for event notifications
  - name: AI
    description: AI-powered quiz generation and promotion suggestions
  - name: Trends
    description: Trending topics for quiz inspiration
paths:
  /api/v1/youtube/uploads:
    post:
      tags:
        - YouTube
      summary: Create an upload job
      description: >-
        Upload a rendered quiz video to YouTube. Requires a completed render job
        and connected YouTube channel. Returns 202 Accepted.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadInput'
      responses:
        '202':
          description: Upload job accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/YouTubeUpload'
                required:
                  - data
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Render job or channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Upload already in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth:
            - youtube:write
components:
  schemas:
    CreateUploadInput:
      type: object
      properties:
        quizId:
          type: string
          minLength: 1
        renderJobId:
          type: string
          minLength: 1
        channelId:
          type: string
          minLength: 1
        metadata:
          type: object
          properties:
            title:
              type: string
              minLength: 1
              maxLength: 100
            description:
              type: string
              maxLength: 5000
              default: ''
            tags:
              type: array
              items:
                type: string
              default: []
            categoryId:
              type: string
              default: '27'
            visibility:
              type: string
              enum:
                - public
                - unlisted
                - private
              default: unlisted
            madeForKids:
              type: boolean
              default: false
            scheduledFor:
              type: string
              format: date-time
          required:
            - title
      required:
        - quizId
        - renderJobId
        - channelId
        - metadata
    YouTubeUpload:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
        progress:
          type:
            - number
            - 'null'
        title:
          type: string
        description:
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        category_id:
          type:
            - string
            - 'null'
        visibility:
          type:
            - string
            - 'null'
          enum:
            - public
            - unlisted
            - private
            - null
        made_for_kids:
          type:
            - boolean
            - 'null'
        youtube_video_id:
          type:
            - string
            - 'null'
        youtube_video_url:
          type:
            - string
            - 'null'
        error_message:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        scheduled_for:
          type:
            - string
            - 'null'
          format: date-time
        retry_count:
          type:
            - integer
            - 'null'
        next_retry_at:
          type:
            - string
            - 'null'
          format: date-time
        quiz_id:
          type: string
          format: uuid
        render_job_id:
          type: string
          format: uuid
        youtube_channel_id:
          type: string
          format: uuid
      required:
        - id
        - status
        - progress
        - title
        - description
        - tags
        - category_id
        - visibility
        - made_for_kids
        - youtube_video_id
        - youtube_video_url
        - error_message
        - created_at
        - completed_at
        - scheduled_for
        - retry_count
        - next_retry_at
        - quiz_id
        - render_job_id
        - youtube_channel_id
    Error:
      type: object
      properties:
        type:
          type: string
          example: https://quizquail.com/problems/validation-error
        title:
          type: string
          example: Validation Error
        status:
          type: integer
          example: 400
        detail:
          type: string
          example: Request validation failed
        instance:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
      required:
        - type
        - title
        - status
    FieldError:
      type: object
      properties:
        field:
          type: string
          example: title
        message:
          type: string
          example: Title is required
        code:
          type: string
          example: too_small
      required:
        - field
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key authentication. Prefix your key with `Bearer ` in the
        Authorization header.


        Keys follow the format `qq_...` and can be scoped to specific
        permissions.

````