Your videos. Your workflow. Our API.

Upload, organise and deliver video from your own applications. Choose the API that fits your integration.

Latest APIREST · v1 Legacy APIDoodstream compatible

For new integrations: Bearer authentication, JSON payloads and HTTP status codes.

Base URL: https://api.streamvault.example/api/v1
Authentication: Bearer YOUR_API_KEY
Responses: JSON + HTTP status codes
Rate limit: 10 requests per second

01 / Quickstart

Make your first request

Get your API key from your account settings, set it as $API_KEY on your server, then list your files.

cURL · List files

curl -X GET "https://api.streamvault.example/api/v1/files" \
  -H "Authorization: Bearer $API_KEY"

Examples use placeholders. Replace values in braces with your file codes or UUIDs before running them.

One key, in the header

Send Authorization: Bearer YOUR_API_KEY with each request. A session access token is also accepted. Keep credentials on your server; rotating your API key in Settings invalidates the previous key.

For JSON requests, also send Content-Type: application/json. Folder and upload session IDs are UUIDs; files use file codes.

Start with HTTPS

Send API credentials and uploads directly to HTTPS URLs. An HTTP redirect cannot protect a key that has already crossed the network. Use HTTPS for presigned storage URLs too; never rewrite a signed URL to change its scheme.

The reserved example hostname is a placeholder unless a public API origin is configured. Local HTTP endpoints are for isolated development, not public integrations.

See fair usage limits and integration support.

Read the HTTP status

Successful calls return JSON directly, without the Legacy envelope. Check the HTTP status before reading the response. A file list looks like this:

200 · Example response

{
  "page": 1,
  "per_page": 100,
  "files": []
}

Latest API error statuses
HTTP status	Meaning
400	Invalid request or parameters
401	Missing, invalid or expired credentials
403	Access denied
404	Resource not found
409	Resource already exists
429	Rate limit exceeded
500	Internal server error

401 · Example API error

{ "error": "Unauthorized" }

Leave room between requests

Authenticated requests share a limit of 10 requests per second per account. On HTTP 429, pause and retry with backoff.

Moving from Legacy?

Use the same account API key, with the new base URL and request format. Update your error handling to check HTTP status codes.

Authentication: ?key=… → Authorization: Bearer …
File listing: GET /api/file/list → GET /api/v1/files
Rename a file: GET /api/file/rename → PATCH /api/v1/files/{code}
Create a folder: GET /api/folder/create → POST /api/v1/folders
Folder identifiers: Numeric fld_id → UUID folder_id or parent_id

02 / API reference

Find your endpoint

Filter endpoints

Copy an example to run on your server. POST, PATCH and DELETE requests change account data.

Account

GET`/auth/me`

Read the authenticated account.

No parameters.

cURL · Example request

curl -X GET "https://api.streamvault.example/api/v1/auth/me" \
  -H "Authorization: Bearer $API_KEY"

Files

GET`/files`

List and search your files.

Query: folder_id (UUID), q (title search), page (default 1), per_page (default 100, maximum 500).

cURL · Example request

curl -X GET "https://api.streamvault.example/api/v1/files" \
  -H "Authorization: Bearer $API_KEY"

GET`/files/{code}`

Get metadata for one of your files.

Path: code is the file code.

cURL · Example request

curl -X GET "https://api.streamvault.example/api/v1/files/{code}" \
  -H "Authorization: Bearer $API_KEY"

PATCH`/files/{code}`

Update a title, folder, visibility or download permission.

JSON: title, folder_id (UUID or null for root), is_public, allow_download. All fields optional.

cURL · Example request

curl -X PATCH "https://api.streamvault.example/api/v1/files/{code}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Summer trip",
  "is_public": false
}'

POST`/files/{code}/clone`

Copy an accessible file into your account.

JSON: folder_id (UUID) and title, both optional.

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/files/{code}/clone" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "My copy"
}'

POST`/files/bulk`

Move, delete, change privacy or rotate aliases for up to 100 files.

JSON: action (move, delete, privacy, rotate_aliases), file_codes (array). move accepts folder_id; privacy requires is_public.

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/files/bulk" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "privacy",
  "file_codes": [
    "YOUR_FILE_CODE"
  ],
  "is_public": false
}'

Folders

GET`/folders`

List folders inside a parent, or at the root.

Query: parent_id (optional UUID). Omit it for root folders.

cURL · Example request

curl -X GET "https://api.streamvault.example/api/v1/folders" \
  -H "Authorization: Bearer $API_KEY"

POST`/folders`

Create a folder.

JSON: name (required), parent_id (optional UUID), is_public (optional boolean).

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/folders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Travel",
  "is_public": false
}'

PATCH`/folders/{id}`

Rename, move or change a folder’s visibility.

Path: id (UUID). JSON: name, parent_id (UUID or null for root), is_public. All fields optional.

cURL · Example request

curl -X PATCH "https://api.streamvault.example/api/v1/folders/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Travel films"
}'

DELETE`/folders/{id}`

Delete a folder.

Path: id is the folder UUID. This changes account data.

cURL · Example request

curl -X DELETE "https://api.streamvault.example/api/v1/folders/{id}" \
  -H "Authorization: Bearer $API_KEY"

Remote upload

GET`/remote`

Read remote upload jobs and available slots.

No parameters. Returns jobs, total_slots and used_slots.

cURL · Example request

curl -X GET "https://api.streamvault.example/api/v1/remote" \
  -H "Authorization: Bearer $API_KEY"

POST`/remote`

Queue videos from remote URLs.

JSON: urls (required array, 1–100 URLs), folder_id (optional UUID), title (optional, applies to a single URL).

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/remote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "urls": [
    "https://example.com/video.mp4"
  ]
}'

POST`/remote/actions`

Retry failed jobs or clear the remote upload queue.

JSON: restart_errors, clear_errors, clear_all (optional booleans), delete_code (optional file code).

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/remote/actions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "restart_errors": true
}'

Upload

POST`/upload/init`

Start a multipart upload or a proof-of-possession challenge.

JSON: filename, size_bytes, mime_type, blake3_hash (required). folder_id and title are optional.

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/upload/init" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "video.mp4",
  "size_bytes": 734003200,
  "mime_type": "video/mp4",
  "blake3_hash": "BLAKE3_HEX_OF_YOUR_FILE"
}'

POST`/upload/parts`

Request presigned URLs for upload parts.

JSON: session_id (UUID), part_numbers (array of part numbers).

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/upload/parts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "session_id": "YOUR_SESSION_UUID",
  "part_numbers": [
    1,
    2
  ]
}'

POST`/upload/complete`

Finalize an upload after sending all parts.

JSON: session_id, parts (array of part_number and etag). Use the ETag returned by storage.

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/upload/complete" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "session_id": "YOUR_SESSION_UUID",
  "parts": [
    {
      "part_number": 1,
      "etag": "ETAG_FROM_STORAGE"
    }
  ]
}'

POST`/upload/prove`

Complete a deduplicated upload using the returned challenge.

JSON: session_id, proof (hex BLAKE3 of decoded nonce bytes followed by the challenged file range).

cURL · Example request

curl -X POST "https://api.streamvault.example/api/v1/upload/prove" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "session_id": "YOUR_SESSION_UUID",
  "proof": "BLAKE3_PROOF_HEX"
}'

GET`/upload/{id}`

Inspect an upload session and resume progress.

Path: id is the upload session UUID.

cURL · Example request

curl -X GET "https://api.streamvault.example/api/v1/upload/{id}" \
  -H "Authorization: Bearer $API_KEY"

DELETE`/upload/{id}`

Abort an upload session.

Path: id is the upload session UUID. This cancels the upload.

cURL · Example request

curl -X DELETE "https://api.streamvault.example/api/v1/upload/{id}" \
  -H "Authorization: Bearer $API_KEY"

03 / Upload workflow

Upload in parts, resume when needed

Hash your file with BLAKE3, then call POST /upload/init with its metadata.
For a multipart session, PUT the file parts to the returned presigned storage URLs. Request additional URLs with POST /upload/parts.
Collect each part’s ETag, then call POST /upload/complete. Check GET /upload/{id} to resume a session.
If initialization returns a deduplication challenge instead, calculate its proof and call POST /upload/prove.

All paths above are relative to /api/v1. To import an existing remote video instead, use POST /remote.

04 / Delivery

From file code to player

Both APIs use the same player. Embed a file at /e/{file_code}. Set a poster, subtitles and autoplay below, then copy the embed code.

File coderequired

c_posteroptional

c1_file … c10_filesubtitle tracks

subtitle_jsonoptional

autoplay Start playing when loaded, where the browser allows it

Embed URL

https://streamvault.example/e/FILE_CODE

iframe

<iframe src="https://streamvault.example/e/FILE_CODE" width="640" height="360" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>

Enter a file code to preview the player.

Your videos. Your workflow. Our API.

Make your first request

One key, in the header

Start with HTTPS

Read the HTTP status

Leave room between requests

Moving from Legacy?

Find your endpoint

Account

GET/auth/me

Files

GET/files

GET/files/{code}

PATCH/files/{code}

POST/files/{code}/clone

POST/files/bulk

Folders

GET/folders

POST/folders

PATCH/folders/{id}

DELETE/folders/{id}

Remote upload

GET/remote

POST/remote

POST/remote/actions

Upload

POST/upload/init

POST/upload/parts

POST/upload/complete

POST/upload/prove

GET/upload/{id}

DELETE/upload/{id}

Upload in parts, resume when needed

From file code to player

GET`/auth/me`

GET`/files`

GET`/files/{code}`

PATCH`/files/{code}`

POST`/files/{code}/clone`

POST`/files/bulk`

GET`/folders`

POST`/folders`

PATCH`/folders/{id}`

DELETE`/folders/{id}`

GET`/remote`

POST`/remote`

POST`/remote/actions`

POST`/upload/init`

POST`/upload/parts`

POST`/upload/complete`

POST`/upload/prove`

GET`/upload/{id}`

DELETE`/upload/{id}`