openapi: 3.0.1
info:
  title: ByteArk API
  description: >-
    Representative OpenAPI description of ByteArk's public developer surfaces:
    the Stream Video-on-Demand API (create / upload / list / get videos) and the
    Fleet Live Streaming (live transcode) API. S3-compatible Storage and CDN
    delivery are documented separately by ByteArk; the Storage service is
    accessed via standard S3 clients and is not fully re-specified here.
  termsOfService: https://www.byteark.com/en/terms
  contact:
    name: ByteArk Support
    url: https://www.byteark.com/en/contact
  version: '1.0'
servers:
  - url: https://stream.byteark.com/api/v1
    description: ByteArk Stream (Video on Demand)
  - url: https://fleet.byteark.com/api
    description: ByteArk Fleet (Live Streaming / CDN)
security:
  - bearerAuth: []
tags:
  - name: Videos
    description: Video-on-demand records and playback in ByteArk Stream.
  - name: Uploads
    description: Uploading source video files to a Stream video record.
  - name: Live
    description: Fleet live transcode channels.
paths:
  /videos:
    get:
      operationId: listVideos
      tags:
        - Videos
      summary: List videos
      description: >-
        Returns a paginated list of videos in the account, optionally filtered
        by project and tags. Use `includes` to expand related resources.
      parameters:
        - name: projectKey
          in: query
          required: false
          schema:
            type: string
          description: Filter videos by project key.
        - name: tagIds
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Filter videos by tag IDs.
        - name: includes
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum: [project, player, tags, creator, vod.source]
          description: Expand the response with related resources.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
          description: Page index (starts at 1).
        - name: size
          in: query
          required: false
          schema:
            type: integer
          description: Number of results per page.
      responses:
        '200':
          description: A paginated list of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoList'
    post:
      operationId: createVideos
      tags:
        - Videos
      summary: Create video(s)
      description: >-
        Creates one or more video records within a project. The response
        includes each video's key and primary HLS playback URL. A source file is
        then uploaded to the returned video key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVideosRequest'
      responses:
        '200':
          description: The created video records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Video'
  /videos/{videoKey}:
    get:
      operationId: getVideo
      tags:
        - Videos
      summary: Get a video
      description: Retrieves information about a single video by its key.
      parameters:
        - name: videoKey
          in: path
          required: true
          schema:
            type: string
          description: The unique key of the video.
      responses:
        '200':
          description: The video information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
  /upload/v1/form-data/videos/{videoKey}:
    post:
      operationId: uploadVideoFile
      tags:
        - Uploads
      summary: Upload a video file
      description: >-
        Uploads a source video file to a previously created video record using
        multipart form-data. For large files, ByteArk also supports resumable
        uploads via the Video Upload SDK.
      parameters:
        - name: videoKey
          in: path
          required: true
          schema:
            type: string
          description: The key of the video to upload the file to.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The source video file to upload.
              required:
                - file
      responses:
        '200':
          description: Upload accepted; the video enters transcoding.
  /{serviceId}/{apiKey}/createchannel:
    servers:
      - url: https://fleet.byteark.com/api
    post:
      operationId: createLiveChannel
      tags:
        - Live
      summary: Create a live channel
      description: >-
        Creates a Fleet live transcode channel and returns the RTMP publish
        endpoint, stream key, and HLS viewing URL. Enable per-resolution
        transcode profiles (1080p / 720p / 576p / 480p / 360p / 240p).
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
          description: Fleet service identifier.
        - name: apiKey
          in: path
          required: true
          schema:
            type: string
          description: Fleet API key.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                streamname:
                  type: string
                  description: Channel identifier / stream name.
                'transcode[720p]':
                  type: integer
                  description: Set to 1 to enable the 720p transcode profile.
              required:
                - streamname
      responses:
        '200':
          description: The created live channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveChannel'
  /{serviceId}/{apiKey}/listchannels:
    servers:
      - url: https://fleet.byteark.com/api
    post:
      operationId: listLiveChannels
      tags:
        - Live
      summary: List live channels
      description: Returns all active live channels with their endpoints and status.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
        - name: apiKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The list of live channels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiveChannel'
  /{serviceId}/{apiKey}/deletechannel:
    servers:
      - url: https://fleet.byteark.com/api
    post:
      operationId: deleteLiveChannel
      tags:
        - Live
      summary: Delete a live channel
      description: Deletes a live channel and halts publishing and transcoding.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
        - name: apiKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                streamname:
                  type: string
              required:
                - streamname
      responses:
        '200':
          description: The channel was deleted.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token passed as `Authorization: Bearer <token>`.
        Tokens are generated in the ByteArk Personal Access Token settings.
        Fleet live channel endpoints instead authenticate with a serviceId /
        apiKey path pair.
  schemas:
    CreateVideosRequest:
      type: object
      required:
        - projectKey
        - videos
      properties:
        projectKey:
          type: string
          description: The project the videos belong to.
        videos:
          type: array
          items:
            type: object
            required:
              - title
            properties:
              title:
                type: string
              tags:
                type: array
                items:
                  type: string
    Video:
      type: object
      properties:
        id:
          type: string
        key:
          type: string
          description: Unique video key used for uploads and playback references.
        title:
          type: string
        coverImage:
          type: object
          properties:
            sizes:
              type: object
              additionalProperties:
                type: string
        primaryPlaybackUrl:
          type: object
          properties:
            hls:
              type: object
              properties:
                url:
                  type: string
                  format: uri
    VideoList:
      type: object
      properties:
        total:
          type: integer
        from:
          type: integer
        to:
          type: integer
        currentPage:
          type: integer
        lastPage:
          type: integer
        perPage:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/Video'
    LiveChannel:
      type: object
      properties:
        streamid:
          type: string
        streamkey:
          type: string
          description: RTMP authentication key.
        streamendpoint:
          type: string
          description: RTMP publish address (e.g. rtmp://publish.fleet.byteark.com/fleet).
        streamurl:
          type: string
          description: HLS viewing URL ending in index.m3u8.
        transcodelimit:
          type: integer
        transcodeusage:
          type: integer