Retrieve Videos

GET /api/videos

Retrieves videos in the API key’s workspace, together with each video’s ready streams.

A video is included when it is not deleted, has a thumbnail, and has at least one stream job with a stream URL. Published and unpublished videos are both included. Deleted videos, videos without a thumbnail, and videos without a stream job URL are omitted.

Each video’s streams array contains every stream that is ready, not deleted, and belongs to the same workspace. When you do not pass visibility, a video can be returned with an empty streams array if it has a stream job but no ready stream. When you do pass visibility, videos with no matching streams are omitted.

Results follow library order: Home first, then other folders by folder id, and within each folder by position.

To list only published videos and the single most recent stream for each one, use Retrieve Published Videos.

Allowed API Key Roles

adminreadonly

Query Parameters

Parameter	Type	Required	Description
folderName	string	No	Filters results by folder name. Repeat this parameter to include videos from several folders. Home selects videos that are not in a folder. Names are matched exactly and are case-sensitive. Blank values are ignored. If omitted, videos from every folder are returned.
visibility	string	No	Filters streams by visibility. Accepted values are public and drm. Repeat this parameter to include more than one visibility. If omitted, every ready stream is returned.

Any other query parameter is rejected.

Example request

getVideos.js

fetch('https://spatialgen.com/api/videos', {
    method: 'GET',
    headers: {
        'X-SPATIALGEN-APPKEY': apiKey,
    }
})

Example request filtered by folder and visibility

getVideosFiltered.js

fetch('https://spatialgen.com/api/videos?folderName=Launch%20Assets&folderName=Home&visibility=drm', {
    method: 'GET',
    headers: {
        'X-SPATIALGEN-APPKEY': apiKey,
    }
})

Example Response

response.json

[
    {
        "streams": [
            {
                "createdAt": string,              // Date in string format
                "status": string,                 // Always "ready"
                "streamName": string,             // Name of the stream
                "streamUrl": string,              // URL for the stream
                "visibility": string,             // "public" or "drm"
                "highestResolutionURL": string,   // URL to the highest resolution converted video
                "highestResolutionBytes": number, // Bytes in the highest resolution converted video
                "jobId": number                   // Stream job ID, or -1 when no job matches this stream URL
            }
        ],
        "library": {
            "createdAt": string,            // Date in string format
            "description": string,          // Description of the video
            "fileFormat3D": string,         // Format of the 3D file
            "folderName": string,           // Folder name, or "Home" when the video is not in a folder
            "id": number,                   // ID of the video
            "is3D": boolean,                // If the video is in 3D
            "isStreaming": boolean,         // If the video is streaming
            "perspective": number,          // Perspective
            "thumbnailUrl": string,         // Thumbnail URL
            "videoLength": number,          // Length of the video in seconds
            "videoHeight": number,          // Height of the video
            "videoName": string             // Name of the video
        }
    }
]

Errors

Error bodies use { "status": <code>, "error": "<message>" }. An empty match is 404, not an empty array.

• 400 — The X-SPATIALGEN-APPKEY header is missing. Invalid request: missing X-SPATIALGEN-APPKEY header
• 400 — visibility is not public or drm. Invalid request: visibility must be either public or drm
• 400 — The query includes a parameter this endpoint does not accept. Invalid request: …
• 401 — The API key is revoked, expired, or not recognized. Invalid API key
• 403 — The API key does not include the videos:read scope. upload keys do not include this scope. API key missing required scope: videos:read
• 404 — folderName was set, none of those folders exist in the workspace, and Home was not requested. No videos found in the specified folders
• 404 — The workspace has no videos that match the filters. No published videos found for this workspace and filter set
• 405 — The request method is not GET. Method Not Allowed