{ "openapi": "3.1.0", "info": { "title": "Stillhaven API", "version": "1.0.0", "description": "Manage your Stillhaven library from your own tools. Everything here is scoped to one account, and no scope grants billing, team management, branding, key management, or permanent deletion. Those stay in the console." }, "servers": [ { "url": "https://console.stillhaven.io/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Who this credential acts for, and what the plan allows." }, { "name": "Videos", "description": "Reading, uploading, editing, and trashing videos." }, { "name": "Folders", "description": "The folder tree, up to three levels deep." }, { "name": "Channels", "description": "Playlists with their own page, and who may watch them." } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "summary": "Read the account this credential acts for", "description": "Cheap, and the only route that needs no scope: a client calls it at connect time to find out what it may do, and requiring a scope to ask what your scopes are would be a loop. `member` is null for an API key, which belongs to an account rather than to a person. Needs no scope: any valid credential may call it.", "operationId": "getMe", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "tags": [ "Account" ], "summary": "Read storage and bandwidth against the plan", "description": "The same numbers the Settings page shows. Bandwidth is metered per calendar month in UTC; `period_start` is inclusive and `period_end` exclusive. `overage` states what going over costs, in cents, so a client warning about a quota can say what it means. Scope: `usage:read`.", "operationId": "getUsage", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos": { "get": { "tags": [ "Videos" ], "summary": "List videos, newest first", "description": "Trashed videos are not included. Filters compose, and a filter that cannot be used fails the request rather than being ignored: a silently dropped filter returns a longer list that looks like a correct answer. Scope: `videos:read`.", "operationId": "getVideos", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Up to 200. Defaults to 50.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "From `next_cursor` on the previous page.", "schema": { "type": "string" } }, { "name": "folder_id", "in": "query", "required": false, "description": "A folder id. Send it empty to list unfiled videos.", "schema": { "type": "string" } }, { "name": "channel_id", "in": "query", "required": false, "description": "Only videos in this channel.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "One of uploading, scanning, processing, ready, held, blocked, failed.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive match on the title.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601. Videos changed at or after this moment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoList" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Videos" ], "summary": "Start an upload", "description": "Step one of three. Creates the video and an S3 multipart session, and returns how many parts to send. Your bytes go straight to S3 and never pass through this API. Limited to 50 upload starts an hour on top of the usual rate limit. Scope: `videos:write`.", "operationId": "postVideos", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filename", "size_bytes" ], "properties": { "filename": { "type": "string", "description": "Required. The name of the file, used for its extension and as a default title.", "example": "..." }, "size_bytes": { "type": "integer", "description": "Required. The size of the file, in bytes.", "example": 0 }, "title": { "type": "string", "description": "Defaults to the filename without its extension.", "example": "..." }, "folder_id": { "type": "string", "description": "An existing folder. Omit to leave the video unfiled.", "example": "..." }, "orientation": { "type": "string", "description": "portrait or landscape. Defaults to landscape.", "example": "..." }, "content_type": { "type": "string", "description": "The file MIME type.", "example": "..." }, "transcript": { "type": "boolean", "description": "true to have a transcript generated.", "example": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadIntent" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Out of room on the plan. `used_bytes`, `limit_bytes` and `free_bytes` say by how much.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}": { "get": { "tags": [ "Videos" ], "summary": "Read one video", "description": "A trashed video answers 404 here. Restore it first. `poster_url` carries a signature and stops working after about six hours, so fetch it again rather than storing it. Scope: `videos:read`.", "operationId": "getVideosId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Videos" ], "summary": "Change a video", "description": "Only the fields you send are changed. A field you omit is left exactly as it was. `description_html` is sanitized, so tags outside a small safe set are removed. Scope: `videos:write`.", "operationId": "patchVideosId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "title": { "type": "string", "description": "Up to 200 characters.", "example": "..." }, "description_html": { "type": "string", "description": "Markup shown beside the video on its share page.", "example": "..." }, "description_visible": { "type": "boolean", "description": "Whether that description is shown.", "example": true }, "folder_id": { "type": "string", "description": "An existing folder, or empty to unfile the video.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/analytics": { "get": { "tags": [ "Videos" ], "summary": "Read play analytics for one video", "description": "Two different counts, kept apart rather than reconciled: a windowed count from the per-day source rows, and the lifetime counters carried on the video. Source rows are kept 90 days, so a 90d window is the whole of what is retained. There is no per-video bandwidth figure and no viewer count, because neither is measured anywhere in the product. Scope: `usage:read`.", "operationId": "getVideosIdAnalytics", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "One of 7d, 30d, or 90d. Defaults to 30d.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analytics" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/upload-parts": { "post": { "tags": [ "Videos" ], "summary": "Get presigned URLs for a batch of parts", "description": "Step two. PUT each part to its URL with that part number's bytes and keep the ETag the response returns. Ask for up to 1000 at a time. URLs expire, so call this again for the rest of a long upload rather than requesting everything at the start. Scope: `videos:write`.", "operationId": "postVideosIdUploadParts", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "part_numbers" ], "properties": { "part_numbers": { "type": "array", "description": "Required. Part numbers, from 1 to parts_expected.", "example": [] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadParts" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/upload-complete": { "post": { "tags": [ "Videos" ], "summary": "Finish an upload", "description": "Step three. The parts S3 is holding are measured and checked against the plan before anything is finalised, so an upload larger than declared is refused here and nothing is saved. Processing starts on success. Scope: `videos:write`.", "operationId": "postVideosIdUploadComplete", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "parts": { "type": "array", "description": "Required. Every part as {part_number, etag}.", "example": [] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadComplete" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The uploaded file is larger than the plan allows. Nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/import": { "post": { "tags": [ "Videos" ], "summary": "Import a video from a URL", "description": "Not available yet. The route exists so its shape is settled, and it answers 501 in the meantime. Scope: `videos:write`.", "operationId": "postVideosIdImport", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "source_url": { "type": "string", "description": "The video to fetch.", "example": "..." } } } } } }, "responses": { "501": { "description": "Not built yet. Import from URL is not available yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/trash": { "post": { "tags": [ "Videos" ], "summary": "Move a video to trash", "description": "Reversible for 30 days. There is no permanent delete in this API at all, so this is the most a key can do, and the next call undoes it. Scope: `videos:write`.", "operationId": "postVideosIdTrash", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trashed" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/restore": { "post": { "tags": [ "Videos" ], "summary": "Restore a video from trash", "description": "The one video route that addresses a trashed video, since that is the only kind it can act on. Scope: `videos:write`.", "operationId": "postVideosIdRestore", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/allowed-domains": { "put": { "tags": [ "Videos" ], "summary": "Set where a video may be embedded", "description": "inherit follows the account default, locked allows only the domains you list, open allows every site. Send bare hostnames: no scheme, no path. Scope: `settings:write`. Plan: any paid plan.", "operationId": "putVideosIdAllowedDomains", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "description": "Required. inherit, locked, or open.", "example": "..." }, "domains": { "type": "array", "description": "Up to 20 hostnames. Required when mode is locked.", "example": [] }, "unknown_origin": { "type": "string", "description": "lenient or strict, for a request whose origin cannot be read.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos/{id}/share-page": { "put": { "tags": [ "Videos" ], "summary": "Set the share page, its password, and downloads", "description": "Only the fields you send are changed. `password` is write-only and never comes back; the read side reports only whether one is set. Sending null clears it, which also signs out anyone currently holding an unlock. Scope: `settings:write`.", "operationId": "putVideosIdSharePage", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "enabled": { "type": "boolean", "description": "Whether the video has a public share page.", "example": true }, "password": { "type": "string", "description": "4 to 64 characters, or null to remove the password.", "example": "..." }, "downloads_enabled": { "type": "boolean", "description": "Whether the share page offers a download.", "example": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/folders": { "get": { "tags": [ "Folders" ], "summary": "List folders, by name", "description": "Every folder and subfolder on the account. A folder with an empty `parent_id` is at the top level. Scope: `videos:read`.", "operationId": "getFolders", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Up to 200. Defaults to 50.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "From `next_cursor` on the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderList" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Folders" ], "summary": "Create a folder", "description": "Folders go three levels deep at most. Scope: `videos:write`.", "operationId": "postFolders", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Required. Up to 80 characters.", "example": "..." }, "parent_id": { "type": "string", "description": "An existing folder. Omit for a top-level folder.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/folders/{id}": { "patch": { "tags": [ "Folders" ], "summary": "Rename a folder", "description": "There is no delete. Removing a folder stays in the console, because it decides what happens to what is inside it. Scope: `videos:write`.", "operationId": "patchFoldersId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Required. Up to 80 characters.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/channels": { "get": { "tags": [ "Channels" ], "summary": "List channels, newest first", "description": "Summaries: `video_count` without the playlist. Read one channel for its order. Scope: `channels:read`. Plan: any paid plan.", "operationId": "getChannels", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Up to 200. Defaults to 50.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "From `next_cursor` on the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelList" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Create a channel", "description": "A new channel has no videos and no public name. Set `slug` to give it a page. Scope: `channels:write`. Plan: any paid plan.", "operationId": "postChannels", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "title": { "type": "string", "description": "Up to 120 characters.", "example": "..." }, "description_html": { "type": "string", "description": "Markup shown beside the video on the channel page.", "example": "..." }, "visibility": { "type": "string", "description": "public or private. Defaults to public.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/channels/{id}": { "get": { "tags": [ "Channels" ], "summary": "Read one channel, with its video order", "description": "`share_url` is empty until the channel has a slug, because a channel without one has no public page to link to. Scope: `channels:read`. Plan: any paid plan.", "operationId": "getChannelsId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Channels" ], "summary": "Change a channel", "description": "Only the fields you send are changed. A private channel admits only invited viewers; inviting them needs the Studio plan, though marking a channel private does not. Scope: `channels:write`. Plan: any paid plan.", "operationId": "patchChannelsId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "title": { "type": "string", "description": "Up to 120 characters.", "example": "..." }, "description_html": { "type": "string", "description": "Markup shown beside the video on the channel page.", "example": "..." }, "visibility": { "type": "string", "description": "public or private.", "example": "..." }, "slug": { "type": "string", "description": "The channel's public name, 3 to 32 lowercase letters, numbers, and hyphens. Unique across Stillhaven. Send null to take the page down.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/channels/{id}/videos": { "put": { "tags": [ "Channels" ], "summary": "Replace a channel's playlist and its order", "description": "Every id is checked before any of them is stored, so a list with one bad entry changes nothing. Send an empty list to clear the channel. Scope: `channels:write`. Plan: any paid plan.", "operationId": "putChannelsIdVideos", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_ids" ], "properties": { "video_ids": { "type": "array", "description": "Required. Video ids, in the order they should play.", "example": [] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Add one video to a channel", "description": "Appends without disturbing the existing order. Scope: `channels:write`. Plan: any paid plan.", "operationId": "postChannelsIdVideos", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_id" ], "properties": { "video_id": { "type": "string", "description": "Required.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/channels/{id}/videos/{videoId}": { "delete": { "tags": [ "Channels" ], "summary": "Remove one video from a channel", "description": "Removing a video that is not in the channel succeeds: that is the state you asked for. Scope: `channels:write`. Plan: any paid plan.", "operationId": "deleteChannelsIdVideosVideoid", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } }, { "name": "videoId", "in": "path", "required": true, "description": "The video to remove.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/channels/{id}/users": { "get": { "tags": [ "Channels" ], "summary": "List a private channel's viewers and what each has watched", "description": "One entry per invited viewer, most recently active first, with the channel's videos in order and how far the viewer got in each: 0 not started, 75 watched, 100 finished. The same rows the console's Progress card shows. Public channels are not tracked, so they return their viewers with nothing watched. Scope: `channels:read`. Plan: any paid plan.", "operationId": "getChannelsIdUsers", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelUserList" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Invite a viewer to a private channel", "description": "The endpoint the CRM integrations use. The viewer is emailed a sign-in link. Needs the Studio plan, which is what carries a viewer allowance. Scope: `channels:write`. Plan: any paid plan.", "operationId": "postChannelsIdUsers", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Required. The viewer to invite.", "example": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/channels/{id}/users/{email}": { "delete": { "tags": [ "Channels" ], "summary": "Remove a viewer from a private channel", "description": "The viewer loses access immediately. Scope: `channels:write`. Plan: any paid plan.", "operationId": "deleteChannelsIdUsersEmail", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the thing being addressed.", "schema": { "type": "string" } }, { "name": "email", "in": "path", "required": true, "description": "The viewer's email address, URL encoded.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "That credential is not valid. Check the token in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope this route needs, the account is not on a plan that includes it, or the account is suspended. `error` is `forbidden_scope` or `plan_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such thing on this account. An id belonging to another account answers the same way, deliberately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some values were not usable. `fields` names which ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the rate limit of 600 requests a minute. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key from Settings, API in the console, sent as `Authorization: Bearer shk_...`. Keys are shown once at creation and stored only as a hash, so a lost key is replaced rather than recovered. Keys are available on every paid plan." } }, "schemas": { "Error": { "type": "object", "description": "Every failure. `error` is a stable machine code; `message` is a sentence for a person. Some codes carry extra fields: `fields` on validation_failed, `plan` on plan_required, byte counts on quota_exceeded.", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "unauthorized", "forbidden_scope", "plan_required", "not_found", "validation_failed", "rate_limited", "quota_exceeded", "not_implemented", "server_error" ] }, "message": { "type": "string" }, "fields": { "type": "object", "description": "Field name to what was wrong with it." }, "plan": { "type": "string", "description": "The lowest plan that includes what was asked for." } } }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "Me": { "type": "object", "description": "The account this credential acts for. `member` is null under an API key.", "properties": { "account_id": { "type": "string" }, "account_name": { "type": "string" }, "plan": { "type": "string" }, "plan_label": { "type": "string" }, "member": { "type": "object" }, "scopes": { "type": "array" } } }, "Usage": { "type": "object", "description": "Storage and bandwidth against the plan. Byte counts throughout, cents for rates.", "properties": { "plan": { "type": "string" }, "plan_label": { "type": "string" }, "storage": { "type": "object" }, "bandwidth": { "type": "object" }, "overage": { "type": "object" } } }, "Video": { "type": "object", "description": "A video. `duration_seconds` is null when no duration was ever recorded, which is possible on a video that is otherwise ready: the pipeline writes it only when the transcode reports a positive length. Treat null as unknown, not as zero. `share_url` is empty when the share page is off. `poster_url` is signed and expires after about six hours. `edits` is null when the video plays as uploaded; otherwise `trim_start`, `trim_end`, `fade_in` and `fade_out` in seconds, measured from the untouched original, and `duration_seconds` is the edited length.", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description_html": { "type": "string" }, "description_visible": { "type": "boolean" }, "folder_id": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "duration_seconds": { "type": "integer" }, "edits": { "type": "object" }, "size_bytes": { "type": "integer" }, "orientation": { "type": "string" }, "has_captions": { "type": "boolean" }, "poster_url": { "type": "string" }, "share_url": { "type": "string" }, "embed_code": { "type": "string" }, "share_page": { "type": "object" }, "allowed_domains": { "type": "object" }, "player": { "type": "object" } } }, "Folder": { "type": "object", "description": "A folder. An empty `parent_id` means top level.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": "string" }, "created_at": { "type": "string" } } }, "Channel": { "type": "object", "description": "A channel. `video_ids` appears when one channel is read, not in a list. `share_url` is empty until the channel has a slug.", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description_html": { "type": "string" }, "visibility": { "type": "string" }, "slug": { "type": "string" }, "share_url": { "type": "string" }, "video_count": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "video_ids": { "type": "array" } } }, "Analytics": { "type": "object", "description": "`plays` and `loads` cover the requested window; `all_time` carries the lifetime counters, including how far viewers got.", "properties": { "period": { "type": "string" }, "plays": { "type": "integer" }, "loads": { "type": "integer" }, "all_time": { "type": "object" } } }, "UploadIntent": { "type": "object", "description": "Split the file into `parts_expected` pieces of `part_size_bytes`, the last one shorter. `upload_id` is informational: later calls take the video id.", "properties": { "video_id": { "type": "string" }, "upload_id": { "type": "string" }, "part_size_bytes": { "type": "integer" }, "parts_expected": { "type": "integer" }, "expires_at": { "type": "string" } } }, "UploadParts": { "type": "object", "description": "One entry per requested part, as {part_number, url}. PUT the part's bytes to its URL and keep the ETag header from the response.", "properties": { "urls": { "type": "array" }, "expires_at": { "type": "string" } } }, "UploadComplete": { "type": "object", "description": "Processing has started. Poll the video until its status is ready.", "properties": { "video_id": { "type": "string" }, "status": { "type": "string" } } }, "Trashed": { "type": "object", "description": "The video is in trash and can be restored for this many days.", "properties": { "id": { "type": "string" }, "trashed": { "type": "boolean" }, "restorable_days": { "type": "integer" } } }, "ChannelUser": { "type": "object", "description": "An invited viewer and their progress. `status` is `invited` until they first sign in, then `active`. `videos` lists the channel's videos in order as {id, title, progress, watched_at}; `progress` is 0, 75 or 100.", "properties": { "email": { "type": "string" }, "status": { "type": "string" }, "invited_at": { "type": "string" }, "watched": { "type": "integer" }, "finished": { "type": "integer" }, "total": { "type": "integer" }, "last_watched_at": { "type": "string" }, "videos": { "type": "array" } } }, "VideoList": { "type": "object", "description": "A page of results. `next_cursor` is null on the last page; send it as `?cursor=` to get the next one.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "next_cursor": { "type": "string" } } }, "ChannelUserList": { "type": "object", "description": "A page of results. `next_cursor` is null on the last page; send it as `?cursor=` to get the next one.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelUser" } }, "next_cursor": { "type": "string" } } }, "FolderList": { "type": "object", "description": "A page of results. `next_cursor` is null on the last page; send it as `?cursor=` to get the next one.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } }, "next_cursor": { "type": "string" } } }, "ChannelList": { "type": "object", "description": "A page of results. `next_cursor` is null on the last page; send it as `?cursor=` to get the next one.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "next_cursor": { "type": "string" } } } } } }