{
  "openapi": "3.0.0",
  "paths": {
    "/api/video": {
      "post": {
        "operationId": "VideoController_create",
        "summary": "Create a video upload",
        "description": "Creates a video record and returns a presigned PUT URL plus a server-chosen `contentType` (from the filename extension). Upload the original file with HTTP PUT to `uploadUrl`, using **exactly** the returned `Content-Type` header value. Then call `POST /api/video/{id}/complete-upload` to verify the object and queue transcoding. Output resolutions are MP4. `isPublic` controls whether playback URLs are public or time-limited signed URLs. Requires the `X-API-KEY` header; see https://docs.hyperserve.io/guides/getting-started.",
        "parameters": [
          {
            "name": "X-API-KEY",
            "in": "header",
            "description": "Hyperserve api key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateVideoDto"
              },
              "examples": {
                "standard": {
                  "description": "Standard create video request with required values only",
                  "value": {
                    "filename": "my-video.mp4",
                    "resolutions": [
                      "240p",
                      "480p",
                      "1080p"
                    ],
                    "isPublic": true
                  }
                },
                "withThumbnails": {
                  "description": "Request with optional thumbnails and metadata",
                  "value": {
                    "filename": "my-video.mp4",
                    "resolutions": [
                      "240p",
                      "1080p"
                    ],
                    "isPublic": false,
                    "thumbnailTimestampsSeconds": [
                      1,
                      5,
                      7
                    ],
                    "customMetadata": {
                      "projectId": "abc123"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Video record created. Upload the file to the provided URL, then call complete-upload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateVideoResponseDto"
                }
              }
            }
          }
        },
        "tags": [
          "video"
        ],
        "security": [
          {
            "api-key": []
          }
        ]
      }
    },
    "/api/video/{id}/complete-upload": {
      "post": {
        "operationId": "VideoController_completeUpload",
        "summary": "Complete a video upload",
        "description": "Call after the presigned PUT succeeds. The server checks the object exists in storage, enforces size limits, reads the beginning of the file to confirm it looks like a video, then sets status to processing and queues transcoding. On verification failure the upload may be removed and the video marked failed. Requires the `X-API-KEY` header; see https://docs.hyperserve.io/guides/getting-started.",
        "parameters": [
          {
            "name": "X-API-KEY",
            "in": "header",
            "description": "Hyperserve api key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The video ID returned from POST /api/video",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "description": "Optional. Send `{}` or omit when unused. `checksum` is reserved for future client-side verification.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteUploadDto"
              },
              "examples": {
                "empty": {
                  "summary": "No optional fields",
                  "value": {}
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upload verified; video is processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompleteUploadResponseDto"
                }
              }
            }
          }
        },
        "tags": [
          "video"
        ],
        "security": [
          {
            "api-key": []
          }
        ]
      }
    },
    "/api/video/{id}/public": {
      "get": {
        "operationId": "VideoController_getPublicVideo",
        "summary": "Get a public video",
        "description": "Retrieves all the resolution urls for a public video, anyone can access the urls indefinitely so long as they have the url and the underlying file exists. Requires the `X-API-KEY` header; see https://docs.hyperserve.io/guides/getting-started.",
        "parameters": [
          {
            "name": "X-API-KEY",
            "in": "header",
            "description": "Hyperserve api key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The id of the video",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public video found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetVideoResponseDto"
                }
              }
            }
          }
        },
        "tags": [
          "video"
        ],
        "security": [
          {
            "api-key": []
          }
        ]
      }
    },
    "/api/video/{id}/private/{expirationSeconds}": {
      "get": {
        "operationId": "VideoController_getPrivateVideo",
        "summary": "Get a private video",
        "description": "Retrieves signed urls for all the resolutions of a private video, these can only be accessed for a set amount of time (expirationSeconds). Requires the `X-API-KEY` header; see https://docs.hyperserve.io/guides/getting-started.",
        "parameters": [
          {
            "name": "X-API-KEY",
            "in": "header",
            "description": "Hyperserve api key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The id of the video",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "name": "expirationSeconds",
            "required": true,
            "in": "path",
            "description": "The number of seconds the url will be valid for",
            "schema": {
              "minLength": 1,
              "maxLength": 31536000,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Private video found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetVideoResponseDto"
                }
              }
            }
          }
        },
        "tags": [
          "video"
        ],
        "security": [
          {
            "api-key": []
          }
        ]
      }
    },
    "/api/video/{id}": {
      "delete": {
        "operationId": "VideoController_delete",
        "summary": "Delete video",
        "description": "Deletes a video and all its associated resolutions and thumbnails. Requires the `X-API-KEY` header; see https://docs.hyperserve.io/guides/getting-started.",
        "parameters": [
          {
            "name": "X-API-KEY",
            "in": "header",
            "description": "Hyperserve api key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The id of the video",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Video deleted successfully"
          }
        },
        "tags": [
          "video"
        ],
        "security": [
          {
            "api-key": []
          }
        ]
      }
    },
    "/api/video/resolution/{id}": {
      "delete": {
        "operationId": "VideoController_deleteVideoResolution",
        "summary": "Delete video resolution",
        "description": "Deletes a video resolution (a specific resolution of the video) and its associated thumbnails. Requires the `X-API-KEY` header; see https://docs.hyperserve.io/guides/getting-started.",
        "parameters": [
          {
            "name": "X-API-KEY",
            "in": "header",
            "description": "Hyperserve api key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The id of the video resolution",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Video resolution deleted successfully"
          }
        },
        "tags": [
          "video"
        ],
        "security": [
          {
            "api-key": []
          }
        ]
      }
    }
  },
  "info": {
    "title": "",
    "description": "",
    "version": "1.0",
    "contact": {}
  },
  "tags": [
    {
      "name": "hyperserve",
      "description": ""
    }
  ],
  "servers": [
    {
      "url": "https://api.hyperserve.io",
      "description": "Hyperserve API Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "api-key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    },
    "schemas": {
      "CreateVideoDto": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "resolutions": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": [
                "144p",
                "240p",
                "360p",
                "480p",
                "720p",
                "1080p",
                "1440p",
                "4k",
                "8k"
              ]
            }
          },
          "isPublic": {
            "type": "boolean"
          },
          "thumbnailTimestampsSeconds": {
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 0,
              "exclusiveMinimum": false
            }
          },
          "customMetadata": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "filename",
          "resolutions",
          "isPublic"
        ]
      },
      "CreateVideoResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Video id; use in complete-upload and subsequent API calls",
            "type": "string",
            "format": "uuid"
          },
          "uploadUrl": {
            "description": "Presigned PUT URL for the original file (expires after a short time)",
            "type": "string",
            "format": "uri"
          },
          "contentType": {
            "description": "Exact value to send as the `Content-Type` header on the presigned PUT (derived from filename extension)",
            "type": "string"
          },
          "isPublic": {
            "type": "boolean"
          },
          "resolutions": {
            "description": "Per-resolution status; all start as pending_upload until processing completes",
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending_upload",
                    "processing",
                    "ready",
                    "fail"
                  ]
                }
              },
              "required": [
                "status"
              ]
            }
          }
        },
        "required": [
          "id",
          "uploadUrl",
          "contentType",
          "isPublic",
          "resolutions"
        ]
      },
      "CompleteUploadDto": {
        "type": "object",
        "properties": {
          "checksum": {
            "description": "Reserved for future client-side integrity verification; omit unless documented otherwise",
            "type": "string"
          }
        }
      },
      "CompleteUploadResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Video id",
            "type": "string",
            "format": "uuid"
          },
          "isPublic": {
            "type": "boolean"
          },
          "resolutions": {
            "description": "Per-resolution status; all start as processing immediately after complete-upload",
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending_upload",
                    "processing",
                    "ready",
                    "fail"
                  ]
                }
              },
              "required": [
                "status"
              ]
            }
          }
        },
        "required": [
          "id",
          "isPublic",
          "resolutions"
        ]
      },
      "GetVideoResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending_upload",
              "processing",
              "ready",
              "fail"
            ]
          },
          "isPublic": {
            "type": "boolean"
          },
          "customMetadata": {
            "type": "object",
            "additionalProperties": {},
            "nullable": true
          },
          "resolutions": {
            "type": "object",
            "properties": {
              "144p": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "240p": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "360p": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "480p": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "720p": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "1080p": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "1440p": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "4k": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              },
              "8k": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending_upload",
                      "processing",
                      "ready",
                      "fail"
                    ]
                  },
                  "videoUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "thumbnailImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "required": [
                  "id",
                  "status",
                  "videoUrl",
                  "thumbnailImageUrls"
                ]
              }
            }
          }
        },
        "required": [
          "id",
          "status",
          "isPublic",
          "resolutions"
        ]
      }
    }
  }
}