{
  "type": "object",
  "title": "VideoCreationPayload",
  "example": {
    "tags": [
      "maths",
      "string theory",
      "video"
    ],
    "title": "Maths video",
    "public": false,
    "metadata": [
      {
        "key": "Author",
        "value": "John Doe"
      },
      {
        "key": "Format",
        "value": "Tutorial"
      }
    ],
    "playerId": "pl45KFKdlddgk654dspkze",
    "panoramic": false,
    "watermark": {
      "id": "watermark_1BWr2L5MTQwxGkuxKjzh6i",
      "right": "10px",
      "width": "50%",
      "bottom": "10px",
      "opacity": "70%"
    },
    "mp4Support": true,
    "description": "An amazing video explaining string theory."
  },
  "required": [
    "title"
  ],
  "properties": {
    "clip": {
      "$ref": "#/components/schemas/video-clip"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": "[\"maths\", \"string theory\", \"video\"]",
      "description": "A list of tags you want to use to describe your video."
    },
    "title": {
      "type": "string",
      "example": "Maths video",
      "description": "The title of your new video."
    },
    "public": {
      "type": "boolean",
      "default": true,
      "example": true,
      "description": "Default: True. If set to `false` the video will become private. More information on private videos can be found [here](https://docs.api.video/delivery-analytics/video-privacy-access-management)"
    },
    "source": {
      "type": "string",
      "example": "https://www.myvideo.url.com/video.mp4 OR vi4k0jvEUuaTdRAEjQ4JfOyl",
      "description": "You can either add a video already on the web, by entering the URL of the video, or you can also enter the `videoId` of one of the videos you already have on your api.video acccount, and this will generate a copy of your video. Creating a copy of a video can be especially useful if you want to keep your original video and trim or apply a watermark onto the copy you would create."
    },
    "metadata": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/metadata"
      },
      "example": "[{\"key\": \"Author\", \"value\": \"John Doe\"}]",
      "description": "A list of key value pairs that you use to provide metadata for your video. These pairs can be made dynamic, allowing you to segment your audience. Read more on [dynamic metadata](https://api.video/blog/endpoints/dynamic-metadata/)."
    },
    "playerId": {
      "type": "string",
      "example": "pl45KFKdlddgk654dspkze",
      "description": "The unique identification number for your video player."
    },
    "panoramic": {
      "type": "boolean",
      "default": false,
      "example": false,
      "description": "Indicates if your video is a 360/immersive video."
    },
    "watermark": {
      "$ref": "#/components/schemas/video-watermark"
    },
    "mp4Support": {
      "type": "boolean",
      "default": true,
      "example": true,
      "description": "Enables mp4 version in addition to streamed version."
    },
    "description": {
      "type": "string",
      "example": "A video about string theory.",
      "description": "A brief description of your video."
    }
  }
}

{
  "type": "object",
  "title": "VideoSession",
  "example": {
    "os": {
      "name": "Microsoft Windows",
      "version": "Windows10",
      "shortname": "W10"
    },
    "client": {
      "name": "Firefox",
      "type": "browser",
      "version": "67.0"
    },
    "device": {
      "type": "desktop",
      "model": "unknown",
      "vendor": "Dell"
    },
    "session": {
      "endedAt": "2019-06-24T11:49:19.243Z",
      "loadedAt": "2019-06-24T11:45:01.109Z",
      "sessionId": "psEmFwGQUAXR2lFHj5nDOpy"
    },
    "location": {
      "city": "Paris",
      "country": "France"
    },
    "referrer": {
      "url": "https://api.video",
      "medium": "organic",
      "source": "https://google.com",
      "searchTerm": "video encoding hosting and delivery"
    }
  },
  "properties": {
    "os": {
      "$ref": "#/components/schemas/video-session-os"
    },
    "client": {
      "$ref": "#/components/schemas/video-session-client"
    },
    "device": {
      "$ref": "#/components/schemas/video-session-device"
    },
    "session": {
      "$ref": "#/components/schemas/video-session-session"
    },
    "location": {
      "$ref": "#/components/schemas/video-session-location"
    },
    "referrer": {
      "$ref": "#/components/schemas/video-session-referrer"
    }
  }
}

{
  "type": "object",
  "title": "VideoSessionClient",
  "properties": {
    "name": {
      "type": "string",
      "example": "Firefox",
      "description": "The name of the browser used to view the video session."
    },
    "type": {
      "type": "string",
      "example": "browser",
      "description": "The type of client used to view the video session."
    },
    "version": {
      "type": "string",
      "example": "67.0",
      "description": "The version of the browser used to view the video session."
    }
  },
  "description": "What kind of browser the viewer is using for the video session."
}

{
  "type": "object",
  "title": "VideoSessionDevice",
  "properties": {
    "type": {
      "type": "string",
      "example": "desktop",
      "description": "What the type is like desktop, laptop, mobile."
    },
    "model": {
      "type": "string",
      "example": "unknown",
      "description": "The specific model of the device, if known."
    },
    "vendor": {
      "type": "string",
      "example": "Dell",
      "description": "If known, what the brand of the device is, like Apple, Dell, etc."
    }
  },
  "description": "What type of device the user is on when in the video session."
}

{
  "type": "object",
  "title": "VideoSessionLocation",
  "properties": {
    "city": {
      "type": "string",
      "example": "Paris",
      "nullable": true,
      "description": "The city of the viewer."
    },
    "country": {
      "type": "string",
      "example": "France",
      "description": "The country of the viewer."
    }
  },
  "description": "The location of the viewer."
}

{
  "type": "object",
  "title": "VideoSessionOs",
  "properties": {
    "name": {
      "type": "string",
      "example": "Microsoft Windows",
      "description": "The name of the operating system."
    },
    "version": {
      "type": "string",
      "example": "Windows 10",
      "description": "The version of the operating system."
    },
    "shortname": {
      "type": "string",
      "example": "W10",
      "description": "The nickname for the operating system, often representing the version."
    }
  },
  "description": "The operating system the viewer is on."
}

{
  "type": "object",
  "title": "VideoSessionReferrer",
  "properties": {
    "url": {
      "type": "string",
      "example": "https://api.video",
      "nullable": true,
      "description": "The link the viewer used to reach the video session."
    },
    "medium": {
      "type": "string",
      "example": "organic",
      "description": "How they arrived at the site, for example organic or paid. Organic meaning they found it themselves and paid meaning they followed a link from an advertisement."
    },
    "source": {
      "type": "string",
      "example": "https://google.com",
      "description": "The source the referrer came from to the video session. For example if they searched through google to find the stream."
    },
    "searchTerm": {
      "type": "string",
      "description": "The search term they typed to arrive at the video session."
    }
  }
}

{
  "type": "object",
  "title": "VideoSessionSession",
  "properties": {
    "endedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T12:45:01.109Z",
      "description": "When the video session ended, presented in ISO-8601 format."
    },
    "loadedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T11:45:01.109Z",
      "description": "When the video session started, presented in ISO-8601 format."
    },
    "metadata": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/metadata"
      },
      "example": "[{\"key\": \"Author\", \"value\": \"John Doe\"}]",
      "description": "A list of key value pairs that you use to provide metadata for your video. These pairs can be made dynamic, allowing you to segment your audience. You can also just use the pairs as another way to tag and categorize your videos."
    },
    "sessionId": {
      "type": "string",
      "example": "psEmFwGQUAXR2lFHj5nDOpy",
      "description": "The unique identifier for the session that you can use to track what happens during it."
    }
  }
}

{
  "type": "object",
  "title": "VideoSource",
  "properties": {
    "uri": {
      "type": "string",
      "example": "/videos/vi4k0jvEUuaTdRAEjQ4Prklg/source",
      "description": "The URL where the video is stored."
    },
    "type": {
      "type": "string"
    },
    "liveStream": {
      "$ref": "#/components/schemas/video-source-live-stream"
    }
  },
  "description": "Source information about the video."
}

{
  "type": "object",
  "properties": {
    "links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/video-source-live-stream-link"
      }
    },
    "liveStreamId": {
      "type": "string",
      "example": "li400mYKSgQ6xs7taUeSaEKr",
      "description": "The unique identifier for the live stream."
    }
  },
  "description": "This appears if the video is from a Live Record."
}

{
  "type": "object",
  "properties": {
    "rel": {
      "type": "string"
    },
    "uri": {
      "type": "string"
    }
  }
}

{
  "type": "object",
  "title": "VideoStatus",
  "example": {
    "ingest": {
      "status": "uploaded",
      "filesize": 273579401,
      "receivedBytes": [
        {
          "to": 134217727,
          "from": 0,
          "total": 273579401
        },
        {
          "to": 268435455,
          "from": 134217728,
          "total": 273579401
        },
        {
          "to": 273579400,
          "from": 268435456,
          "total": 273579401
        }
      ]
    },
    "encoding": {
      "metadata": {
        "width": 424,
        "height": 240,
        "bitrate": 411.218,
        "duration": 4176,
        "framerate": 24,
        "audioCodec": "aac",
        "samplerate": 48000,
        "videoCodec": "h264",
        "aspectRatio": "16/9"
      },
      "playable": true,
      "qualities": [
        {
          "status": "encoded",
          "quality": "240p"
        },
        {
          "status": "encoded",
          "quality": "360p"
        },
        {
          "status": "encoded",
          "quality": "480p"
        },
        {
          "status": "encoded",
          "quality": "720p"
        },
        {
          "status": "encoding",
          "quality": "1080p"
        },
        {
          "status": "waiting",
          "quality": "2160p"
        }
      ]
    }
  },
  "properties": {
    "ingest": {
      "$ref": "#/components/schemas/video-status-ingest"
    },
    "encoding": {
      "$ref": "#/components/schemas/video-status-encoding"
    }
  }
}

{
  "type": "object",
  "title": "VideoStatusEncoding",
  "properties": {
    "metadata": {
      "$ref": "#/components/schemas/video-status-encoding-metadata"
    },
    "playable": {
      "type": "boolean",
      "example": true,
      "description": "Whether the video is playable or not."
    },
    "qualities": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/quality"
      },
      "description": "Available qualities the video can be viewed in."
    }
  }
}

{
  "type": "object",
  "title": "VideoStatusEncodingMetadata",
  "properties": {
    "width": {
      "type": "integer",
      "nullable": true,
      "description": "The width of the video in pixels."
    },
    "height": {
      "type": "integer",
      "nullable": true,
      "description": "The height of the video in pixels."
    },
    "bitrate": {
      "type": "number",
      "nullable": true,
      "description": "The number of bits processed per second."
    },
    "duration": {
      "type": "integer",
      "nullable": true,
      "description": "The length of the video."
    },
    "framerate": {
      "type": "integer",
      "example": 60,
      "nullable": true,
      "description": "The frequency with which consecutive images or frames appear on a display. Shown in this API as frames per second (fps)."
    },
    "audioCodec": {
      "type": "string",
      "nullable": true,
      "description": "The method used to compress and decompress digital audio for your video."
    },
    "samplerate": {
      "type": "integer",
      "example": 48000,
      "nullable": true,
      "description": "How many samples per second a digital audio system uses to record an audio signal. The higher the rate, the higher the frequencies that can be recorded. They are presented in this API using hertz."
    },
    "videoCodec": {
      "type": "string",
      "nullable": true,
      "description": "The method used to compress and decompress digital video. API Video supports all codecs in the libavcodec library. "
    },
    "aspectRatio": {
      "type": "string",
      "nullable": true
    }
  }
}

{
  "type": "object",
  "title": "VideoStatusIngest",
  "properties": {
    "status": {
      "enum": [
        "uploading",
        "uploaded",
        "ingesting",
        "ingested"
      ],
      "type": "string",
      "example": "uploaded",
      "description": "There are four possible statuses depending on how you provide a video file:\n- `uploading` - the API is gathering the video source file from an upload.\n- `uploaded` - the video file is fully uploaded.\n- `ingesting` - the API is gathering the video source file from either a URL, or from cloning.\n- `ingested` - the video file is fully stored.\n"
    },
    "filesize": {
      "type": "integer",
      "example": 200000,
      "nullable": true,
      "description": "The size of your file in bytes."
    },
    "receivedBytes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/bytes-range"
      },
      "description": "The total number of bytes received, listed for each chunk of the upload."
    },
    "receivedParts": {
      "type": "object",
      "properties": {
        "parts": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "example": "[1, 2, 3]",
          "description": "The parts that have been uploaded, ordered. For example, if part 2 was sent before part 1, and both have been uploaded, the output will be [1, 2]."
        },
        "total": {
          "type": "integer",
          "example": 3,
          "nullable": true,
          "description": "Contains the number of expected parts. The total will be listed as \"null\" until the total number of parts is known."
        }
      }
    }
  },
  "description": "Details about the capturing, transferring, and storing of your video for use immediately or in the future."
}

{
  "type": "object",
  "title": "ThumbnailPickPayload",
  "example": {
    "timecode": "00:00:00.000"
  },
  "required": [
    "timecode"
  ],
  "properties": {
    "timecode": {
      "type": "string",
      "pattern": "\\d{2}:\\d{2}:\\d{2}(\\.\\d{2})?",
      "description": "Frame in video to be used as a placeholder before the video plays. \nExample: '\"00:01:00.000\" for 1 minute into the video.'\nValid Patterns: \n\"hh:mm:ss.ms\"\n\"hh:mm:ss:frameNumber\"\n\"124\" (integer value is reported as seconds) \nIf selection is out of range, \"00:00:00.00\" will be chosen."
    }
  }
}

{
  "type": "object",
  "title": "VideoThumbnailUploadPayload",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "The image to be added as a thumbnail. The mime type should be image/jpeg, image/png or image/webp. The max allowed size is 8 MiB."
    }
  }
}

{
  "type": "object",
  "title": "VideoUpdatePayload",
  "example": {
    "tags": [
      "maths",
      "string theory",
      "video"
    ],
    "title": "String theory",
    "public": false,
    "metadata": [
      {
        "key": "Author",
        "value": "John Doe"
      },
      {
        "key": "Format",
        "value": "Tutorial"
      }
    ],
    "playerId": "pl45KFKdlddgk654dspkze",
    "panoramic": false,
    "mp4Support": true,
    "description": "An amazing video explaining the string theory"
  },
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": "[\"maths\", \"string theory\", \"video\"]",
      "description": "A list of terms or words you want to tag the video with. Make sure the list includes all the tags you want as whatever you send in this list will overwrite the existing list for the video."
    },
    "title": {
      "type": "string",
      "description": "The title you want to use for your video."
    },
    "public": {
      "type": "boolean",
      "example": true,
      "description": "Whether the video is publicly available or not. False means it is set to private. Default is true. Tutorials on [private videos](https://api.video/blog/endpoints/private-videos/)."
    },
    "metadata": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/metadata"
      },
      "description": "A list (array) of dictionaries where each dictionary contains a key value pair that describes the video. As with tags, you must send the complete list of metadata you want as whatever you send here will overwrite the existing metadata for the video. [Dynamic Metadata](https://api.video/blog/endpoints/dynamic-metadata/) allows you to define a key that allows any value pair."
    },
    "playerId": {
      "type": "string",
      "example": "pl4k0jvEUuaTdRAEjQ4Jfrgz",
      "description": "The unique ID for the player you want to associate with your video.",
      "x-optional-nullable": true
    },
    "panoramic": {
      "type": "boolean",
      "example": false,
      "description": "Whether the video is a 360 degree or immersive video."
    },
    "mp4Support": {
      "type": "boolean",
      "example": true,
      "description": "Whether the player supports the mp4 format."
    },
    "description": {
      "type": "string",
      "example": "A film about good books.",
      "description": "A brief description of the video."
    }
  }
}

{
  "type": "object",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "example": "@/path/to/video.mp4",
      "description": "The path to the video you would like to upload. The path must be local. If you want to use a video from an online source, you must use the \"/videos\" endpoint and add the \"source\" parameter when you create a new video.",
      "x-client-chunk-upload": "true"
    }
  }
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "watermark_1BWr2L5MTQwxGkuxKjzh6i",
      "description": "id of the watermark"
    },
    "top": {
      "type": "string",
      "example": "10px",
      "description": "Distance expressed in px or % between the top-border of the video and the watermark-image."
    },
    "left": {
      "type": "string",
      "example": "10px",
      "description": "Distance expressed in px or % between the left-border of the video and the watermark-image."
    },
    "right": {
      "type": "string",
      "example": "10px",
      "description": "Distance expressed in px or % between the right-border of the video and the watermark-image."
    },
    "width": {
      "type": "string",
      "example": "initial",
      "description": "Width of the watermark-image relative to the video if expressed in %. Otherwise a fixed width. NOTE: To keep intrinsic watermark-image width use `initial`."
    },
    "bottom": {
      "type": "string",
      "example": "10px",
      "description": "Distance expressed in px or % between the bottom-border of the video and the watermark-image."
    },
    "height": {
      "type": "string",
      "example": "initial",
      "description": "Height of the watermark-image relative to the video if expressed in %. Otherwise a fixed height. NOTE: To keep intrinsic watermark-image height use `initial`."
    },
    "opacity": {
      "type": "string",
      "example": "70%",
      "description": "Opacity expressed in % only to specify the degree of the watermark-image transparency with the video."
    }
  }
}

{
  "type": "object",
  "title": "Videos",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/video"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}

{
  "type": "object",
  "title": "Watermark",
  "properties": {
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T11:45:01.109+00",
      "description": "When the watermark was created, presented in ISO-8601 format."
    },
    "watermarkId": {
      "type": "string",
      "example": "watermark_1BWr2L5MTQwxGkuxKjzh6i",
      "description": "The unique identifier of the watermark."
    }
  }
}

{
  "type": "object",
  "title": "WatermarkUploadPayload",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "The `.jpg` or `.png` image to be added as a watermark."
    }
  }
}

{
  "type": "object",
  "title": "Watermarks",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/watermark"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}

{
  "type": "object",
  "title": "Webhook",
  "properties": {
    "url": {
      "type": "string",
      "example": "http://clientnotificationserver.com/notif?myquery=query",
      "description": "URL of the webhook"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": "[\"video.encoding.quality.completed\"]",
      "description": "A list of events that will trigger the webhook."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-06-24T11:45:01.109Z",
      "description": "When an webhook was created, presented in ISO-8601 format."
    },
    "webhookId": {
      "type": "string",
      "example": "webhook_XXXXXXXXXXXXXXX",
      "description": "Unique identifier of the webhook"
    }
  }
}

{
  "type": "object",
  "title": "WebhooksCreationPayload",
  "example": {
    "url": "http://clientnotificationserver.com/notif?myquery=query",
    "events": [
      "video.encoding.quality.completed"
    ]
  },
  "required": [
    "events",
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "example": "https://example.com/webhooks",
      "description": "The the url to which HTTP notifications are sent. It could be any http or https URL."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "video.encoding.quality.completed"
      ],
      "description": "A list of the webhooks that you are subscribing to. There are Currently four webhook options:\n* ```video.encoding.quality.completed```  Occurs when a new video is uploaded into your account, it will be encoded into several different HLS and mp4 qualities. When each version is encoded, your webhook will get a notification.  It will look like ```{ \\\"type\\\": \\\"video.encoding.quality.completed\\\", \\\"emittedAt\\\": \\\"2021-01-29T16:46:25.217+01:00\\\", \\\"videoId\\\": \\\"viXXXXXXXX\\\", \\\"encoding\\\": \\\"hls\\\", \\\"quality\\\": \\\"720p\\\"} ```. This request says that the 720p HLS encoding was completed.\n* ```live-stream.broadcast.started```  When a live stream begins broadcasting, the broadcasting parameter changes from false to true, and this webhook fires.\n* ```live-stream.broadcast.ended```  This event fires when a live stream has finished broadcasting.\n* ```video.source.recorded```  Occurs when a live stream is recorded and submitted for encoding."
    }
  }
}

{
  "type": "object",
  "title": "Webhooks",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/webhook"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/pagination"
    }
  }
}