{
"openapi": "3.1.0",
"info": {
"title": "TodayFiles API",
"version": "2026-11-01",
"description": "Upload videos, publish a player, and build around events. Your API key connects your library to your application. Start with the [quickstart](/docs/quickstart)."
},
"servers": [
{
"url": "https://api.todayfiles.com/v1"
}
],
"security": [
{
"bearer": []
}
],
"tags": [
{
"name": "Videos",
"description": "Create, organise and publish your video library."
},
{
"name": "Uploads",
"description": "Send bytes directly with resumable tus uploads."
},
{
"name": "Folders",
"description": "Keep related videos together."
},
{
"name": "Clone jobs",
"description": "Copy videos whose owners allow cloning."
},
{
"name": "Analytics",
"description": "Read views, downloads and current viewers."
},
{
"name": "Account",
"description": "Read your account and upload allowance."
},
{
"name": "Webhooks",
"description": "Receive signed events and inspect delivery attempts."
},
{
"name": "Events",
"description": "Recover events from the last 30 days."
}
],
"paths": {
"/videos": {
"get": {
"tags": [
"Videos"
],
"operationId": "listVideos",
"summary": "List videos",
"description": "Return your videos, newest first. Follow next_cursor with the same filters. An insertion between pages can shift a result. Restart from the first page after a cursor expires.",
"x-rate-class": "read",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"description": "Filter by status.",
"schema": {
"type": "string",
"description": "",
"enum": [
"waiting_for_upload",
"processing",
"ready",
"failed"
]
},
"example": "ready"
},
{
"name": "folder_id",
"in": "query",
"required": false,
"description": "Filter by folder.",
"schema": {
"type": "string",
"description": ""
},
"example": "fld_3"
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Search your video titles.",
"schema": {
"type": "string",
"description": "",
"maxLength": 100
},
"example": "trailer"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Results per page.",
"schema": {
"type": "integer",
"description": "",
"minimum": 1,
"maximum": 100,
"default": 20
},
"example": 20
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor from the previous response.",
"schema": {
"type": "string",
"description": ""
},
"example": ""
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"list"
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Video"
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false
},
"example": {
"object": "list",
"data": [
{
"object": "video",
"id": "h87x",
"title": "Launch trailer",
"status": "ready",
"processing": null,
"failure": null,
"source": "upload",
"folder_id": "fld_3",
"enabled": true,
"disabled_by_moderation": false,
"duration": 184,
"size": 119248005,
"max_height": 1080,
"playback": {
"player_url": "https://todayfiles-play.site/h87x",
"embed_html": "",
"thumbnail_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/thumb.jpg",
"poster_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/poster.jpg"
},
"created_at": "2026-10-30T23:41:52Z",
"updated_at": "2026-10-30T23:42:23Z"
}
],
"has_more": false,
"next_cursor": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"post": {
"tags": [
"Videos"
],
"operationId": "createVideo",
"summary": "Create a video",
"description": "Create a video from an upload, an HTTP or HTTPS URL, or a video whose owner allows cloning. For uploads, send bytes to the returned tus endpoint. URL ingest has a separate service ceiling; read the upload guide. Upload creation also spends one upload request.",
"x-rate-class": "write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 200
},
"folder_id": {
"type": [
"string",
"null"
],
"description": ""
},
"source": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "",
"enum": [
"upload",
"url",
"clone"
]
},
"url": {
"type": "string",
"description": "",
"format": "uri",
"maxLength": 2000
},
"video_id": {
"type": "string",
"description": ""
}
},
"required": [
"type"
],
"additionalProperties": false
}
},
"required": [
"source"
],
"additionalProperties": false
},
"example": {
"title": "Launch trailer",
"source": {
"type": "upload"
}
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"video": {
"$ref": "#/components/schemas/Video"
},
"upload": {
"type": [
"object",
"null"
],
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"upload"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"video_id": {
"type": "string",
"description": ""
},
"status": {
"type": "string",
"description": "",
"enum": [
"waiting",
"expired",
"processing",
"completed"
]
},
"protocol": {
"type": "string",
"description": "",
"enum": [
"tus"
]
},
"tus": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "",
"enum": [
"1.0.0"
]
},
"endpoint": {
"type": "string",
"description": "Full tus endpoint. Use it without adding a path."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Pass the complete returned map to your tus client. The example omits its temporary values."
},
"chunk_size": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"description": ""
},
"recommended": {
"type": "integer",
"description": ""
},
"max": {
"type": [
"integer",
"null"
],
"description": ""
}
},
"required": [
"min",
"recommended",
"max"
],
"additionalProperties": false
}
},
"required": [
"version",
"endpoint",
"metadata",
"chunk_size"
],
"additionalProperties": false
},
"max_bytes": {
"type": "integer",
"description": "The byte ceiling signed for this upload target. Read this value before uploading."
},
"expires_at": {
"type": "string",
"description": "Creation deadline for this target.",
"format": "date-time"
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
}
},
"required": [
"object",
"id",
"video_id",
"status",
"protocol",
"tus",
"max_bytes",
"expires_at",
"created_at"
],
"additionalProperties": false,
"example": {
"object": "upload",
"id": "up_01jbqz5m3e6k8r9t2v4w6x8y0a",
"video_id": "h87x",
"status": "waiting",
"protocol": "tus",
"tus": {
"version": "1.0.0",
"endpoint": "https://upload.todayfiles.com/files/",
"metadata": {},
"chunk_size": {
"min": 5242880,
"recommended": 16777216,
"max": 67108864
}
},
"max_bytes": 53687091200,
"expires_at": "2026-11-01T10:15:30Z",
"created_at": "2026-11-01T08:15:30Z"
}
}
},
"required": [
"video",
"upload"
],
"additionalProperties": false
},
"example": {
"video": {
"object": "video",
"id": "h87x",
"title": "Launch trailer",
"status": "waiting_for_upload",
"processing": null,
"failure": null,
"source": "upload",
"folder_id": "fld_3",
"enabled": true,
"disabled_by_moderation": false,
"duration": null,
"size": null,
"max_height": null,
"playback": null,
"created_at": "2026-10-30T23:41:52Z",
"updated_at": "2026-10-30T23:42:23Z"
},
"upload": {
"object": "upload",
"id": "up_01jbqz5m3e6k8r9t2v4w6x8y0a",
"video_id": "h87x",
"status": "waiting",
"protocol": "tus",
"tus": {
"version": "1.0.0",
"endpoint": "https://upload.todayfiles.com/files/",
"metadata": {},
"chunk_size": {
"min": 5242880,
"recommended": 16777216,
"max": 67108864
}
},
"max_bytes": 53687091200,
"expires_at": "2026-11-01T10:15:30Z",
"created_at": "2026-11-01T08:15:30Z"
}
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
}
},
"/videos/{id}": {
"get": {
"tags": [
"Videos"
],
"operationId": "getVideo",
"summary": "Retrieve a video",
"description": "Retrieve a video. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "h87x"
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Video"
},
"example": {
"object": "video",
"id": "h87x",
"title": "Launch trailer",
"status": "ready",
"processing": null,
"failure": null,
"source": "upload",
"folder_id": "fld_3",
"enabled": true,
"disabled_by_moderation": false,
"duration": 184,
"size": 119248005,
"max_height": 1080,
"playback": {
"player_url": "https://todayfiles-play.site/h87x",
"embed_html": "",
"thumbnail_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/thumb.jpg",
"poster_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/poster.jpg"
},
"created_at": "2026-10-30T23:41:52Z",
"updated_at": "2026-10-30T23:42:23Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"patch": {
"tags": [
"Videos"
],
"operationId": "updateVideo",
"summary": "Update a video",
"description": "Update a video. Only resources belonging to your account are returned or changed.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "h87x"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 200
},
"enabled": {
"type": "boolean"
},
"folder_id": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [],
"additionalProperties": false
},
"example": {
"title": "Launch trailer",
"enabled": true
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Video"
},
"example": {
"object": "video",
"id": "h87x",
"title": "Launch trailer",
"status": "ready",
"processing": null,
"failure": null,
"source": "upload",
"folder_id": "fld_3",
"enabled": true,
"disabled_by_moderation": false,
"duration": 184,
"size": 119248005,
"max_height": 1080,
"playback": {
"player_url": "https://todayfiles-play.site/h87x",
"embed_html": "",
"thumbnail_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/thumb.jpg",
"poster_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/poster.jpg"
},
"created_at": "2026-10-30T23:41:52Z",
"updated_at": "2026-10-30T23:42:23Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"tags": [
"Videos"
],
"operationId": "deleteVideo",
"summary": "Delete a video",
"description": "Soft-delete your video. It becomes unavailable through this API immediately.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "h87x"
}
],
"responses": {
"204": {
"description": "No content.",
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/videos/{id}/upload": {
"post": {
"tags": [
"Uploads"
],
"operationId": "createUpload",
"summary": "Create an upload target",
"description": "Create a fresh target for a video waiting for bytes. Pass the complete metadata map to your tus client. Use 16 MiB chunks and read max_bytes for this target’s signed ceiling.",
"x-rate-class": "upload",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "h87x"
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
},
"example": {
"object": "upload",
"id": "up_01jbqz5m3e6k8r9t2v4w6x8y0a",
"video_id": "h87x",
"status": "waiting",
"protocol": "tus",
"tus": {
"version": "1.0.0",
"endpoint": "https://upload.todayfiles.com/files/",
"metadata": {},
"chunk_size": {
"min": 5242880,
"recommended": 16777216,
"max": 67108864
}
},
"max_bytes": 53687091200,
"expires_at": "2026-11-01T10:15:30Z",
"created_at": "2026-11-01T08:15:30Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
},
"get": {
"tags": [
"Uploads"
],
"operationId": "getUpload",
"summary": "Retrieve the latest upload",
"description": "Return the latest target. The status follows video processing; your tus client tracks transferred bytes.",
"x-rate-class": "read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "h87x"
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
},
"example": {
"object": "upload",
"id": "up_01jbqz5m3e6k8r9t2v4w6x8y0a",
"video_id": "h87x",
"status": "waiting",
"protocol": "tus",
"tus": {
"version": "1.0.0",
"endpoint": "https://upload.todayfiles.com/files/",
"metadata": {},
"chunk_size": {
"min": 5242880,
"recommended": 16777216,
"max": 67108864
}
},
"max_bytes": 53687091200,
"expires_at": "2026-11-01T10:15:30Z",
"created_at": "2026-11-01T08:15:30Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/folders": {
"get": {
"tags": [
"Folders"
],
"operationId": "listFolders",
"summary": "List folders",
"description": "List folders. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"list"
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Folder"
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false
},
"example": {
"object": "list",
"data": [
{
"object": "folder",
"id": "fld_3",
"name": "Trailers",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z"
}
],
"has_more": false,
"next_cursor": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"post": {
"tags": [
"Folders"
],
"operationId": "createFolder",
"summary": "Create a folder",
"description": "Create a folder. Only resources belonging to your account are returned or changed.",
"x-rate-class": "write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 64
}
},
"required": [
"name"
],
"additionalProperties": false
},
"example": {
"name": "Trailers"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Folder"
},
"example": {
"object": "folder",
"id": "fld_3",
"name": "Trailers",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
}
},
"/folders/{id}": {
"patch": {
"tags": [
"Folders"
],
"operationId": "updateFolder",
"summary": "Rename a folder",
"description": "Rename a folder. Only resources belonging to your account are returned or changed.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "fld_3"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 64
}
},
"required": [
"name"
],
"additionalProperties": false
},
"example": {
"name": "Trailers"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Folder"
},
"example": {
"object": "folder",
"id": "fld_3",
"name": "Trailers",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"tags": [
"Folders"
],
"operationId": "deleteFolder",
"summary": "Delete a folder",
"description": "Delete your folder. Its videos become uncategorised.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "fld_3"
}
],
"responses": {
"204": {
"description": "No content.",
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/folders/{id}/videos": {
"post": {
"tags": [
"Folders"
],
"operationId": "addVideosToFolder",
"summary": "Add videos to a folder",
"description": "Add videos to a folder. Only resources belonging to your account are returned or changed.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "fld_3"
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"video_ids": {
"type": "array",
"items": {
"type": "string",
"description": ""
}
}
},
"required": [
"video_ids"
],
"additionalProperties": false
},
"example": {
"video_ids": [
"h87x",
"q2m8"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"result"
]
},
"moved": {
"type": "integer",
"description": "",
"minimum": 0
}
},
"required": [
"object",
"moved"
],
"additionalProperties": false
},
"example": {
"object": "result",
"moved": 1
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
}
},
"/folders/remove-videos": {
"post": {
"tags": [
"Folders"
],
"operationId": "removeVideosFromFolders",
"summary": "Remove videos from folders",
"description": "Remove videos from folders. Only resources belonging to your account are returned or changed.",
"x-rate-class": "write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"video_ids": {
"type": "array",
"items": {
"type": "string",
"description": ""
}
}
},
"required": [
"video_ids"
],
"additionalProperties": false
},
"example": {
"video_ids": [
"h87x"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"result"
]
},
"removed": {
"type": "integer",
"description": "",
"minimum": 0
}
},
"required": [
"object",
"removed"
],
"additionalProperties": false
},
"example": {
"object": "result",
"removed": 1
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
}
},
"/clone-jobs": {
"post": {
"tags": [
"Clone jobs"
],
"operationId": "createCloneJob",
"summary": "Create a clone job",
"description": "Queue up to 200 video ids or player URLs. You can have up to 3 jobs in progress and clone up to 200 videos per rolling hour.",
"x-rate-class": "write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"inputs": {
"type": "array",
"items": {
"type": "string",
"description": ""
},
"minItems": 1,
"maxItems": 200
}
},
"required": [
"inputs"
],
"additionalProperties": false
},
"example": {
"inputs": [
"h87x",
"https://todayfiles-play.site/q2m8"
]
}
}
}
},
"responses": {
"202": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CloneJob"
},
"example": {
"object": "clone_job",
"id": "cj_1z",
"status": "completed",
"counts": {
"total": 1,
"succeeded": 1,
"failed": 0,
"pending": 0
},
"items": [
{
"input": "h87x",
"status": "succeeded",
"video_id": "q2m8",
"error": null
}
],
"created_at": "2026-11-01T08:15:30Z",
"completed_at": "2026-11-01T08:15:30Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
},
"get": {
"tags": [
"Clone jobs"
],
"operationId": "listCloneJobs",
"summary": "List clone jobs",
"description": "List clone jobs. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"list"
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CloneJob"
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false
},
"example": {
"object": "list",
"data": [
{
"object": "clone_job",
"id": "cj_1z",
"status": "completed",
"counts": {
"total": 1,
"succeeded": 1,
"failed": 0,
"pending": 0
},
"created_at": "2026-11-01T08:15:30Z",
"completed_at": "2026-11-01T08:15:30Z"
}
],
"has_more": false,
"next_cursor": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/clone-jobs/{id}": {
"get": {
"tags": [
"Clone jobs"
],
"operationId": "getCloneJob",
"summary": "Retrieve a clone job",
"description": "Retrieve a clone job. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "cj_1z"
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CloneJob"
},
"example": {
"object": "clone_job",
"id": "cj_1z",
"status": "completed",
"counts": {
"total": 1,
"succeeded": 1,
"failed": 0,
"pending": 0
},
"items": [
{
"input": "h87x",
"status": "succeeded",
"video_id": "q2m8",
"error": null
}
],
"created_at": "2026-11-01T08:15:30Z",
"completed_at": "2026-11-01T08:15:30Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/analytics/views": {
"get": {
"tags": [
"Analytics"
],
"operationId": "getViewsAnalytics",
"summary": "Query video views",
"description": "Query your views. Unique counts are exact per daily dimension and can count the same viewer again when summed across days.",
"x-rate-class": "analytics",
"parameters": [
{
"name": "from",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": "",
"format": "date"
},
"example": "2026-10-30"
},
{
"name": "to",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": "",
"format": "date"
},
"example": "2026-11-01"
},
{
"name": "group_by",
"in": "query",
"required": false,
"description": "Comma-separated date, video, country, device, referrer or player; downloads also accept quality.",
"schema": {
"type": "string",
"description": ""
},
"example": "date,video"
},
{
"name": "video_id",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": ""
},
"example": "h87x"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "integer",
"description": "",
"minimum": 1,
"maximum": 100
},
"example": 20
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"analytics"
]
},
"from": {
"type": "string",
"description": ""
},
"to": {
"type": "string",
"description": ""
},
"group_by": {
"type": "array",
"items": {
"type": "string",
"description": ""
}
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": ""
},
"video_id": {
"type": "string",
"description": ""
},
"country": {
"type": "string",
"description": ""
},
"device": {
"type": "string",
"description": ""
},
"referrer": {
"type": "string",
"description": ""
},
"player_id": {
"type": "integer",
"description": ""
},
"quality": {
"type": "string",
"description": ""
},
"views": {
"type": "integer",
"description": ""
},
"completed_views": {
"type": "integer",
"description": ""
},
"unique_viewers": {
"type": "integer",
"description": ""
}
},
"required": [
"views",
"completed_views",
"unique_viewers"
],
"additionalProperties": false
}
}
},
"required": [
"object",
"from",
"to",
"group_by",
"rows"
],
"additionalProperties": false
},
"example": {
"object": "analytics",
"from": "2026-10-30",
"to": "2026-11-01",
"group_by": [
"date",
"video"
],
"rows": [
{
"date": "2026-10-30",
"video_id": "h87x",
"views": 12,
"completed_views": 12,
"unique_viewers": 12
}
]
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/analytics/downloads": {
"get": {
"tags": [
"Analytics"
],
"operationId": "getDownloadsAnalytics",
"summary": "Query video downloads",
"description": "Query your downloads. Unique counts can count the same downloader again across daily groups.",
"x-rate-class": "analytics",
"parameters": [
{
"name": "from",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": "",
"format": "date"
},
"example": "2026-10-30"
},
{
"name": "to",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": "",
"format": "date"
},
"example": "2026-11-01"
},
{
"name": "group_by",
"in": "query",
"required": false,
"description": "Comma-separated date, video, country, device, referrer or player; downloads also accept quality.",
"schema": {
"type": "string",
"description": ""
},
"example": "date,video"
},
{
"name": "video_id",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": ""
},
"example": "h87x"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "integer",
"description": "",
"minimum": 1,
"maximum": 100
},
"example": 20
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"analytics"
]
},
"from": {
"type": "string",
"description": ""
},
"to": {
"type": "string",
"description": ""
},
"group_by": {
"type": "array",
"items": {
"type": "string",
"description": ""
}
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": ""
},
"video_id": {
"type": "string",
"description": ""
},
"country": {
"type": "string",
"description": ""
},
"device": {
"type": "string",
"description": ""
},
"referrer": {
"type": "string",
"description": ""
},
"player_id": {
"type": "integer",
"description": ""
},
"quality": {
"type": "string",
"description": ""
},
"downloads": {
"type": "integer",
"description": ""
},
"unique_downloaders": {
"type": "integer",
"description": ""
}
},
"required": [
"downloads",
"unique_downloaders"
],
"additionalProperties": false
}
}
},
"required": [
"object",
"from",
"to",
"group_by",
"rows"
],
"additionalProperties": false
},
"example": {
"object": "analytics",
"from": "2026-10-30",
"to": "2026-11-01",
"group_by": [
"date",
"video"
],
"rows": [
{
"date": "2026-10-30",
"video_id": "h87x",
"downloads": 12,
"unique_downloaders": 12
}
]
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/analytics/realtime": {
"get": {
"tags": [
"Analytics"
],
"operationId": "getRealtime",
"summary": "Retrieve current viewers",
"description": "Retrieve current viewers. Only resources belonging to your account are returned or changed.",
"x-rate-class": "analytics",
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"realtime"
]
},
"viewers": {
"type": "integer",
"description": ""
},
"window_seconds": {
"type": "integer",
"description": ""
}
},
"required": [
"object",
"viewers",
"window_seconds"
],
"additionalProperties": false
},
"example": {
"object": "realtime",
"viewers": 2,
"window_seconds": 300
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/account": {
"get": {
"tags": [
"Account"
],
"operationId": "getAccount",
"summary": "Retrieve your account",
"description": "Retrieve your account. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"example": {
"object": "account",
"id": "acct_7",
"email": "you@example.com",
"username": "demo",
"clone_allowed": true,
"uploads": {
"max_bytes_per_file": 53687091200,
"daily_limit": 100,
"used_today": 3,
"remaining_today": 97,
"resets_at": "2026-11-02T00:00:00Z"
}
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/webhooks": {
"post": {
"tags": [
"Webhooks"
],
"operationId": "createWebhook",
"summary": "Create a webhook",
"description": "Use HTTPS on port 443 or 8443. The host must resolve only to public addresses at creation and every delivery. Save the signing secret: it is shown once.",
"x-rate-class": "write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string",
"description": "",
"enum": [
"video.ready",
"video.failed",
"clone_job.completed"
]
},
"minItems": 1
},
"description": {
"type": "string",
"description": "",
"maxLength": 200
}
},
"required": [
"url",
"events"
],
"additionalProperties": false
},
"example": {
"url": "https://example.com/hooks/todayfiles",
"events": [
"video.ready"
],
"description": "Production"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
},
"example": {
"object": "webhook",
"id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"url": "https://example.com/hooks/todayfiles",
"events": [
"video.ready",
"video.failed"
],
"description": "Production",
"enabled": true,
"status": "active",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z",
"last_delivery": null,
"secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
},
"get": {
"tags": [
"Webhooks"
],
"operationId": "listWebhooks",
"summary": "List webhooks",
"description": "List webhooks. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"list"
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Webhook"
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false
},
"example": {
"object": "list",
"data": [
{
"object": "webhook",
"id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"url": "https://example.com/hooks/todayfiles",
"events": [
"video.ready",
"video.failed"
],
"description": "Production",
"enabled": true,
"status": "active",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z",
"last_delivery": null
}
],
"has_more": false,
"next_cursor": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/webhooks/{id}": {
"get": {
"tags": [
"Webhooks"
],
"operationId": "getWebhook",
"summary": "Retrieve a webhook",
"description": "Retrieve a webhook. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a"
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
},
"example": {
"object": "webhook",
"id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"url": "https://example.com/hooks/todayfiles",
"events": [
"video.ready",
"video.failed"
],
"description": "Production",
"enabled": true,
"status": "active",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z",
"last_delivery": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"patch": {
"tags": [
"Webhooks"
],
"operationId": "updateWebhook",
"summary": "Update a webhook",
"description": "Update a webhook. Only resources belonging to your account are returned or changed.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string",
"description": "",
"enum": [
"video.ready",
"video.failed",
"clone_job.completed"
]
}
},
"description": {
"type": "string",
"description": "",
"maxLength": 200
},
"enabled": {
"type": "boolean"
}
},
"required": [],
"additionalProperties": false
},
"example": {
"enabled": true
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
},
"example": {
"object": "webhook",
"id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"url": "https://example.com/hooks/todayfiles",
"events": [
"video.ready",
"video.failed"
],
"description": "Production",
"enabled": true,
"status": "active",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z",
"last_delivery": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"tags": [
"Webhooks"
],
"operationId": "deleteWebhook",
"summary": "Delete a webhook",
"description": "Delete a webhook. Only resources belonging to your account are returned or changed.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a"
}
],
"responses": {
"204": {
"description": "No content.",
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/webhooks/{id}/rotate-secret": {
"post": {
"tags": [
"Webhooks"
],
"operationId": "rotateWebhookSecret",
"summary": "Rotate a signing secret",
"description": "Save the new secret before leaving this response. Deliveries include signatures for both secrets for 24 hours.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a"
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Webhook"
},
"example": {
"object": "webhook",
"id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"url": "https://example.com/hooks/todayfiles",
"events": [
"video.ready",
"video.failed"
],
"description": "Production",
"enabled": true,
"status": "active",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z",
"last_delivery": null,
"secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
}
},
"/webhooks/{id}/test": {
"post": {
"tags": [
"Webhooks"
],
"operationId": "testWebhook",
"summary": "Send a test event",
"description": "Send a ping event immediately. The response records the delivery outcome.",
"x-rate-class": "write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a"
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional key for safely replaying this request for 24 hours.",
"schema": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 255
},
"example": "upload-launch-trailer"
}
],
"x-idempotent": true,
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Delivery"
},
"example": {
"object": "delivery",
"id": "dlv_01jbqz5m3e6k8r9t2v4w6x8y0a",
"event_id": "evt_01jbqz5m3e6k8r9t2v4w6x8y0a",
"webhook_id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"attempt": 1,
"status": "succeeded",
"response_status": 200,
"duration_ms": 120,
"error": "",
"next_attempt_at": null,
"created_at": "2026-11-01T08:15:30Z"
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"422": {
"$ref": "#/components/responses/Invalid"
}
}
}
},
"/webhooks/{id}/deliveries": {
"get": {
"tags": [
"Webhooks"
],
"operationId": "listWebhookDeliveries",
"summary": "List webhook deliveries",
"description": "List webhook deliveries. Only resources belonging to your account are returned or changed.",
"x-rate-class": "read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Resource id.",
"schema": {
"type": "string",
"description": ""
},
"example": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a"
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"list"
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Delivery"
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false
},
"example": {
"object": "list",
"data": [
{
"object": "delivery",
"id": "dlv_01jbqz5m3e6k8r9t2v4w6x8y0a",
"event_id": "evt_01jbqz5m3e6k8r9t2v4w6x8y0a",
"webhook_id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"attempt": 1,
"status": "succeeded",
"response_status": 200,
"duration_ms": 120,
"error": "",
"next_attempt_at": null,
"created_at": "2026-11-01T08:15:30Z"
}
],
"has_more": false,
"next_cursor": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/events": {
"get": {
"tags": [
"Events"
],
"operationId": "listEvents",
"summary": "List events",
"description": "Events remain available for 30 days, newest first. Pass the last event id as after to continue.",
"x-rate-class": "read",
"parameters": [
{
"name": "type",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": "",
"enum": [
"video.ready",
"video.failed",
"clone_job.completed",
"ping"
]
},
"example": "video.ready"
},
{
"name": "after",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string",
"description": ""
},
"example": "evt_01jbqz5m3e6k8r9t2v4w6x8y0a"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "integer",
"description": "",
"minimum": 1,
"maximum": 100,
"default": 20
},
"example": 20
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"list"
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false
},
"example": {
"object": "list",
"data": [
{
"object": "event",
"id": "evt_01jbqz5m3e6k8r9t2v4w6x8y0a",
"type": "video.ready",
"created_at": "2026-11-01T08:15:30Z",
"data": {
"video": {
"object": "video",
"id": "h87x",
"title": "Launch trailer",
"status": "ready",
"processing": null,
"failure": null,
"source": "upload",
"folder_id": "fld_3",
"enabled": true,
"disabled_by_moderation": false,
"duration": 184,
"size": 119248005,
"max_height": 1080,
"playback": {
"player_url": "https://todayfiles-play.site/h87x",
"embed_html": "",
"thumbnail_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/thumb.jpg",
"poster_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/poster.jpg"
},
"created_at": "2026-10-30T23:41:52Z",
"updated_at": "2026-10-30T23:42:23Z"
}
}
}
],
"has_more": false,
"next_cursor": null
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"400": {
"$ref": "#/components/responses/Invalid"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "tf_live_...",
"description": "Authorization: Bearer followed by your API key. Create one in Developers."
}
},
"schemas": {
"Video": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"video"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"title": {
"type": "string",
"description": "Your video title.",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "string",
"description": "Uploads wait for bytes, then process before becoming ready or failed.",
"enum": [
"waiting_for_upload",
"processing",
"ready",
"failed"
]
},
"processing": {
"type": [
"object",
"null"
],
"properties": {
"stage": {
"type": "string",
"description": "Current processing step."
},
"percent": {
"type": "integer",
"description": "Completed percentage.",
"minimum": 0,
"maximum": 100
}
},
"required": [
"stage",
"percent"
],
"additionalProperties": false
},
"failure": {
"type": [
"object",
"null"
],
"properties": {
"reason": {
"type": "string",
"description": "",
"enum": [
"unplayable_source",
"processing_failed"
]
}
},
"required": [
"reason"
],
"additionalProperties": false
},
"source": {
"type": "string",
"description": "",
"enum": [
"upload",
"url",
"clone",
"ftp",
"torrent",
"import"
]
},
"folder_id": {
"type": [
"string",
"null"
],
"description": ""
},
"enabled": {
"type": "boolean"
},
"disabled_by_moderation": {
"type": "boolean"
},
"duration": {
"type": [
"integer",
"null"
],
"description": "Duration in seconds, when known."
},
"size": {
"type": [
"integer",
"null"
],
"description": "Size in bytes, when known."
},
"max_height": {
"type": [
"integer",
"null"
],
"description": ""
},
"playback": {
"type": [
"object",
"null"
],
"properties": {
"player_url": {
"type": [
"string",
"null"
],
"description": ""
},
"embed_html": {
"type": [
"string",
"null"
],
"description": ""
},
"thumbnail_url": {
"type": [
"string",
"null"
],
"description": ""
},
"poster_url": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"player_url",
"embed_html",
"thumbnail_url",
"poster_url"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "",
"format": "date-time"
}
},
"required": [
"object",
"id",
"title",
"status",
"processing",
"failure",
"source",
"folder_id",
"enabled",
"disabled_by_moderation",
"duration",
"size",
"max_height",
"playback",
"created_at",
"updated_at"
],
"additionalProperties": false,
"example": {
"object": "video",
"id": "h87x",
"title": "Launch trailer",
"status": "ready",
"processing": null,
"failure": null,
"source": "upload",
"folder_id": "fld_3",
"enabled": true,
"disabled_by_moderation": false,
"duration": 184,
"size": 119248005,
"max_height": 1080,
"playback": {
"player_url": "https://todayfiles-play.site/h87x",
"embed_html": "",
"thumbnail_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/thumb.jpg",
"poster_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/poster.jpg"
},
"created_at": "2026-10-30T23:41:52Z",
"updated_at": "2026-10-30T23:42:23Z"
}
},
"Upload": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"upload"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"video_id": {
"type": "string",
"description": ""
},
"status": {
"type": "string",
"description": "",
"enum": [
"waiting",
"expired",
"processing",
"completed"
]
},
"protocol": {
"type": "string",
"description": "",
"enum": [
"tus"
]
},
"tus": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "",
"enum": [
"1.0.0"
]
},
"endpoint": {
"type": "string",
"description": "Full tus endpoint. Use it without adding a path."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Pass the complete returned map to your tus client. The example omits its temporary values."
},
"chunk_size": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"description": ""
},
"recommended": {
"type": "integer",
"description": ""
},
"max": {
"type": [
"integer",
"null"
],
"description": ""
}
},
"required": [
"min",
"recommended",
"max"
],
"additionalProperties": false
}
},
"required": [
"version",
"endpoint",
"metadata",
"chunk_size"
],
"additionalProperties": false
},
"max_bytes": {
"type": "integer",
"description": "The byte ceiling signed for this upload target. Read this value before uploading."
},
"expires_at": {
"type": "string",
"description": "Creation deadline for this target.",
"format": "date-time"
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
}
},
"required": [
"object",
"id",
"video_id",
"status",
"protocol",
"tus",
"max_bytes",
"expires_at",
"created_at"
],
"additionalProperties": false,
"example": {
"object": "upload",
"id": "up_01jbqz5m3e6k8r9t2v4w6x8y0a",
"video_id": "h87x",
"status": "waiting",
"protocol": "tus",
"tus": {
"version": "1.0.0",
"endpoint": "https://upload.todayfiles.com/files/",
"metadata": {},
"chunk_size": {
"min": 5242880,
"recommended": 16777216,
"max": 67108864
}
},
"max_bytes": 53687091200,
"expires_at": "2026-11-01T10:15:30Z",
"created_at": "2026-11-01T08:15:30Z"
}
},
"Folder": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"folder"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"name": {
"type": "string",
"description": "",
"minLength": 1,
"maxLength": 64
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "",
"format": "date-time"
}
},
"required": [
"object",
"id",
"name",
"created_at",
"updated_at"
],
"additionalProperties": false,
"example": {
"object": "folder",
"id": "fld_3",
"name": "Trailers",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z"
}
},
"CloneJobItem": {
"type": "object",
"properties": {
"input": {
"type": "string",
"description": ""
},
"status": {
"type": "string",
"description": "",
"enum": [
"pending",
"running",
"succeeded",
"failed"
]
},
"video_id": {
"type": [
"string",
"null"
],
"description": ""
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"description": ""
},
"message": {
"type": "string",
"description": ""
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"input",
"status",
"video_id",
"error"
],
"additionalProperties": false,
"example": {
"input": "h87x",
"status": "succeeded",
"video_id": "q2m8",
"error": null
}
},
"CloneJob": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"clone_job"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"status": {
"type": "string",
"description": "",
"enum": [
"queued",
"running",
"completed"
]
},
"counts": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "",
"minimum": 0
},
"succeeded": {
"type": "integer",
"description": "",
"minimum": 0
},
"failed": {
"type": "integer",
"description": "",
"minimum": 0
},
"pending": {
"type": "integer",
"description": "",
"minimum": 0
}
},
"required": [
"total",
"succeeded",
"failed",
"pending"
],
"additionalProperties": false
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CloneJobItem"
}
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
},
"completed_at": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"id",
"status",
"counts",
"created_at",
"completed_at"
],
"additionalProperties": false,
"example": {
"object": "clone_job",
"id": "cj_1z",
"status": "completed",
"counts": {
"total": 1,
"succeeded": 1,
"failed": 0,
"pending": 0
},
"items": [
{
"input": "h87x",
"status": "succeeded",
"video_id": "q2m8",
"error": null
}
],
"created_at": "2026-11-01T08:15:30Z",
"completed_at": "2026-11-01T08:15:30Z"
}
},
"Webhook": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"webhook"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"url": {
"type": "string",
"description": "HTTPS endpoint on a public address, using port 443 or 8443.",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string",
"description": "",
"enum": [
"video.ready",
"video.failed",
"clone_job.completed"
]
}
},
"description": {
"type": "string",
"description": "",
"maxLength": 200
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "",
"enum": [
"active",
"disabled",
"disabled_after_failures"
]
},
"secret": {
"type": "string",
"description": "Shown only after creation or rotation. Save it before leaving this response."
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "",
"format": "date-time"
},
"last_delivery": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": ""
},
"status": {
"type": "string",
"description": ""
},
"at": {
"type": "string",
"description": "",
"format": "date-time"
}
}
}
},
"required": [
"object",
"id",
"url",
"events",
"description",
"enabled",
"status",
"created_at",
"updated_at",
"last_delivery"
],
"additionalProperties": false,
"example": {
"object": "webhook",
"id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"url": "https://example.com/hooks/todayfiles",
"events": [
"video.ready",
"video.failed"
],
"description": "Production",
"enabled": true,
"status": "active",
"created_at": "2026-11-01T08:15:30Z",
"updated_at": "2026-11-01T08:15:30Z",
"last_delivery": null
}
},
"Event": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"event"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"type": {
"type": "string",
"description": "",
"enum": [
"video.ready",
"video.failed",
"clone_job.completed",
"ping"
]
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
},
"data": {
"type": "object",
"properties": {
"video": {
"$ref": "#/components/schemas/Video"
},
"clone_job": {
"$ref": "#/components/schemas/CloneJob"
}
},
"required": [],
"additionalProperties": false
}
},
"required": [
"object",
"id",
"type",
"created_at",
"data"
],
"additionalProperties": false,
"example": {
"object": "event",
"id": "evt_01jbqz5m3e6k8r9t2v4w6x8y0a",
"type": "video.ready",
"created_at": "2026-11-01T08:15:30Z",
"data": {
"video": {
"object": "video",
"id": "h87x",
"title": "Launch trailer",
"status": "ready",
"processing": null,
"failure": null,
"source": "upload",
"folder_id": "fld_3",
"enabled": true,
"disabled_by_moderation": false,
"duration": 184,
"size": 119248005,
"max_height": 1080,
"playback": {
"player_url": "https://todayfiles-play.site/h87x",
"embed_html": "",
"thumbnail_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/thumb.jpg",
"poster_url": "https://todayfiles-play.site/img/k3q7wz2a/5x9a2k/poster.jpg"
},
"created_at": "2026-10-30T23:41:52Z",
"updated_at": "2026-10-30T23:42:23Z"
}
}
}
},
"Delivery": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"delivery"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"event_id": {
"type": "string",
"description": ""
},
"webhook_id": {
"type": "string",
"description": ""
},
"attempt": {
"type": "integer",
"description": "",
"minimum": 0
},
"status": {
"type": "string",
"description": "",
"enum": [
"pending",
"succeeded",
"failed"
]
},
"response_status": {
"type": [
"integer",
"null"
],
"description": ""
},
"duration_ms": {
"type": [
"integer",
"null"
],
"description": ""
},
"error": {
"type": "string",
"description": ""
},
"next_attempt_at": {
"type": [
"string",
"null"
],
"description": ""
},
"created_at": {
"type": "string",
"description": "",
"format": "date-time"
}
},
"required": [
"object",
"id",
"event_id",
"webhook_id",
"attempt",
"status",
"response_status",
"duration_ms",
"error",
"next_attempt_at",
"created_at"
],
"additionalProperties": false,
"example": {
"object": "delivery",
"id": "dlv_01jbqz5m3e6k8r9t2v4w6x8y0a",
"event_id": "evt_01jbqz5m3e6k8r9t2v4w6x8y0a",
"webhook_id": "wh_01jbqz5m3e6k8r9t2v4w6x8y0a",
"attempt": 1,
"status": "succeeded",
"response_status": 200,
"duration_ms": 120,
"error": "",
"next_attempt_at": null,
"created_at": "2026-11-01T08:15:30Z"
}
},
"Account": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"account"
]
},
"id": {
"type": "string",
"description": "Stable resource id."
},
"email": {
"type": "string",
"description": "",
"format": "email"
},
"username": {
"type": "string",
"description": ""
},
"clone_allowed": {
"type": "boolean"
},
"uploads": {
"type": "object",
"properties": {
"max_bytes_per_file": {
"type": [
"integer",
"null"
],
"description": ""
},
"daily_limit": {
"type": [
"integer",
"null"
],
"description": ""
},
"used_today": {
"type": "integer",
"description": ""
},
"remaining_today": {
"type": [
"integer",
"null"
],
"description": ""
},
"resets_at": {
"type": "string",
"description": "",
"format": "date-time"
}
},
"required": [
"max_bytes_per_file",
"daily_limit",
"used_today",
"remaining_today",
"resets_at"
],
"additionalProperties": false
}
},
"required": [
"object",
"id",
"email",
"username",
"clone_allowed",
"uploads"
],
"additionalProperties": false,
"example": {
"object": "account",
"id": "acct_7",
"email": "you@example.com",
"username": "demo",
"clone_allowed": true,
"uploads": {
"max_bytes_per_file": 53687091200,
"daily_limit": 100,
"used_today": 3,
"remaining_today": 97,
"resets_at": "2026-11-02T00:00:00Z"
}
}
},
"List": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "",
"enum": [
"list"
]
},
"data": {
"type": "array",
"items": {}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": ""
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
],
"additionalProperties": false,
"example": {
"object": "list",
"data": [],
"has_more": false,
"next_cursor": null
}
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "",
"enum": [
"invalid_request_error",
"authentication_error",
"permission_error",
"rate_limit_error",
"idempotency_error",
"api_error"
]
},
"code": {
"type": "string",
"description": "Stable error code."
},
"message": {
"type": "string",
"description": "Human-readable explanation."
},
"param": {
"type": "string",
"description": "Offending parameter, when relevant."
},
"request_id": {
"type": "string",
"description": "Quote this id when contacting support."
},
"doc_url": {
"type": "string",
"description": "Explanation and recovery steps."
}
},
"required": [
"type",
"code",
"message",
"request_id",
"doc_url"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false,
"example": {
"error": {
"type": "invalid_request_error",
"code": "invalid_parameter",
"message": "title must be 1 to 200 characters.",
"param": "title",
"request_id": "req_3k7f2qzv8m1xw",
"doc_url": "https://api.todayfiles.com/docs/errors#invalid_parameter"
}
}
}
},
"responses": {
"Invalid": {
"description": "A parameter or JSON body needs correction.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"type": "invalid_request_error",
"code": "invalid_parameter",
"message": "This value is not accepted.",
"param": "title",
"request_id": "req_3k7f2qzv8m1xw",
"doc_url": "https://api.todayfiles.com/docs/errors#invalid_parameter"
}
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"Unauthorized": {
"description": "Provide an active API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"type": "authentication_error",
"code": "api_key_required",
"message": "Provide your API key in the Authorization header.",
"param": "title",
"request_id": "req_3k7f2qzv8m1xw",
"doc_url": "https://api.todayfiles.com/docs/errors#api_key_required"
}
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"NotFound": {
"description": "Unknown or inaccessible resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"type": "invalid_request_error",
"code": "resource_not_found",
"message": "This resource does not exist or is not yours.",
"param": "title",
"request_id": "req_3k7f2qzv8m1xw",
"doc_url": "https://api.todayfiles.com/docs/errors#resource_not_found"
}
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"Conflict": {
"description": "The resource cannot accept this change.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"type": "invalid_request_error",
"code": "video_not_uploadable",
"message": "This video is not waiting for an upload.",
"param": "title",
"request_id": "req_3k7f2qzv8m1xw",
"doc_url": "https://api.todayfiles.com/docs/errors#video_not_uploadable"
}
}
}
},
"headers": {
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
},
"RateLimited": {
"description": "Wait before retrying.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"type": "rate_limit_error",
"code": "rate_limited",
"message": "Wait before sending another request.",
"param": "title",
"request_id": "req_3k7f2qzv8m1xw",
"doc_url": "https://api.todayfiles.com/docs/errors#rate_limited"
}
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"description": ""
},
"description": "Seconds to wait before retrying."
},
"Request-Id": {
"description": "Quote this id when contacting support.",
"schema": {
"type": "string"
},
"example": "req_3k7f2qzv8m1xw"
},
"RateLimit-Limit": {
"description": "Requests per minute in this class.",
"schema": {
"type": "integer"
},
"example": 300
},
"RateLimit-Remaining": {
"description": "Requests available in the current bucket.",
"schema": {
"type": "integer"
},
"example": 299
},
"RateLimit-Reset": {
"description": "Seconds until the bucket is full.",
"schema": {
"type": "integer"
},
"example": 1
}
}
}
}
}
}