Quickstart
Create a key in your workspace under API, then Create a key. You need the admin or write role. The key is shown once; store it as a secret on your server and never put it in a browser.
Check the key works:
curl https://api.vewo.io/v1/me \ -H "Authorization: Bearer $VEWO_KEY"
Create a video. You get its id and a URL to send the file to:
curl -X POST https://api.vewo.io/v1/videos \
-H "Authorization: Bearer $VEWO_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Lesson 4", "size_bytes": 734003200, "visibility": "private"}'
{
"video": { "id": "a41f09c2be17", "status": "UPLOADING", ... },
"upload": { "method": "PUT", "url": "https://...", "headers": { ... } },
"note": "PUT the file to upload.url, then ..."
}Send the bytes straight to storage, with every header from upload.headers:
curl -X PUT "$UPLOAD_URL" \ -H "Content-Type: video/mp4" \ --upload-file lesson-4.mp4
When the video can play, your webhook endpoint receives video.ready. Add an endpoint in the workspace or with POST /v1/webhooks (see Webhooks). If you would rather poll, call GET /v1/videos/{id} until status is READY.
POST https://your-app.example/hooks/vewo
webhook-id: msg_...
webhook-timestamp: 1791393004
webhook-signature: v1,...
{
"type": "video.ready",
"workspace_id": "ws_...",
"created_at": 1791393004,
"data": { "id": "a41f09c2be17", "status": "READY", "width": 1080, "height": 1920, ... }
}Authentication
Every request carries a key as a bearer token: Authorization: Bearer vewo_sk_.... Browser sessions are not accepted on /v1.
- A key belongs to one workspace for its whole life and cannot see any other, so a staging key never reaches production video.
- A key can be read-only. Read-only keys can list and read videos, analytics, webhook endpoints and deliveries, and mint view tokens. Changing anything needs a write key.
- No key can change billing, seats or workspaces.
- To rotate, create a new key, deploy it, then revoke the old one under API. Revoking takes effect on the next request.
GET /v1/metells you which company and workspace a key belongs to, whether it can write, and the workspace's limits.
A missing or malformed key returns 401 with {"detail": "Provide an API key as a bearer token."}, and an unknown or revoked key {"detail": "Invalid API key."}. A key that is valid but not allowed to do something returns 403 {"detail": "Not allowed for this role."}.
Uploading
POST /v1/videos takes size_bytes (required, the exact file size), and optionally title (up to 160 characters), visibility (public, link or private; the workspace default applies when you leave it out), content_type (default video/mp4) and multipart.
Up to 5 GB, the response has upload.method "PUT": one request to upload.url with the headers in upload.headers. Processing starts when the bytes land.
Files over 5 GB, up to 100 GB
Above 5 GB the response is a multipart plan. You can also ask for one at any size with "multipart": true, which makes an upload resumable.
{
"video": { "id": "b3d9e0a71c44", "status": "UPLOADING", ... },
"upload": {
"method": "multipart",
"part_size": 67108864,
"part_count": 120,
"parts": [ { "part_number": 1, "url": "https://..." }, ... ],
"urls_expire_in": 3600
}
}- PUT byte range
[(n-1) * part_size, n * part_size)of the file to partn's URL. Parts can go in any order and in parallel. Parts are at least 64 MB and there are never more than 1,000. - Part URLs expire after an hour. Get fresh ones with
POST /v1/videos/{id}/upload/parts {"part_numbers": [7, 8]}. - After an interruption,
GET /v1/videos/{id}/upload/partsreturnsuploadedandmissing, so you send only what is missing. - Finish with
POST /v1/videos/{id}/upload/complete. You do not send ETags; vewo checks what storage holds. If a part is missing or the wrong size it returns409and lists them, so a short file is never processed. Calling it again after a success returns the same answer.
curl https://api.vewo.io/v1/videos/b3d9e0a71c44/upload/parts -H "Authorization: Bearer $VEWO_KEY"
{ "part_size": 67108864, "part_count": 120, "uploaded": [ ... ], "missing": [7, 8] }
curl -X POST https://api.vewo.io/v1/videos/b3d9e0a71c44/upload/complete -H "Authorization: Bearer $VEWO_KEY"An upload that never finishes is removed after 12 hours, and a video.deleted webhook is sent with "status": "UPLOADING".
Videos and statuses
GET /v1/videos lists the workspace, newest first. It takes limit (1 to 200, default 50) and cursor; pass next_cursor back while has_more is true. GET /v1/videos/{id} returns one video. PATCH /v1/videos/{id} changes title or visibility. DELETE /v1/videos/{id} deletes it and its files, and sends video.deleted. A video in another workspace, or one that does not exist, is 404 either way.
- id
- 12 characters.
- status
UPLOADING,PROCESSING,READYorFAILED.- title
- Text, possibly empty.
- visibility
public(anyone, embeddable),link(only with the full link) orprivate(your members, or one viewer with a view token).- created_at
- Unix seconds.
- size_bytes
- The uploaded file's size.
- duration_seconds
- Null until processed.
- width, height
- The source dimensions, so you can reserve the right box before the player loads. A phone video is usually taller than it is wide.
- uploaded_by
- The key or person that created it.
- play_count
- Plays so far.
- expires_at
- Null when the video does not expire, which is the default. Set only if the workspace has a retention policy.
- thumbnail_url
- A signed URL of the poster frame once the video is
READY, null before. It works for 24 hours; fetch the video again for a fresh one. - captions
- Ready caption tracks, each
{lang, label, source, url}.urlis a signed WebVTT file valid for 24 hours. Captions are added by the owner in the workspace, never automatically. - watch_url, embed_url
- The vewo page and the player for iframes. For a link video both include its key.
- password_protected
- Present and true when the video has a password.
- error
- Present on
FAILED: why processing failed.
A new video stays UPLOADING until a processing worker starts on it, then moves to PROCESSING. Most videos are ready within a minute or two of the upload finishing. When many arrive at once they are processed in turn, and a video can wait in UPLOADING for several minutes before it starts, so do not treat a long UPLOADING as a failed upload. The webhook fires the moment each video can play.
Private playback with view tokens
A private video does not play from a link or on vewo.io for anyone outside your company. Your own members watch it on vewo.io by signing in. To show it to someone else, your backend decides they may watch, then asks for a view token:
curl -X POST https://api.vewo.io/v1/videos/a41f09c2be17/view-token \
-H "Authorization: Bearer $VEWO_KEY" \
-H "Content-Type: application/json" \
-d '{"expires_in": 3600}'
{
"video_id": "a41f09c2be17",
"token": "...",
"expires_at": 1791396604,
"embed_url": "https://vewo.io/embed/a41f09c2be17?vt=...",
"visibility": "private"
}New to the idea? The guide how to embed a private video on your website walks through the whole pattern.
Put embed_url in an iframe on your page:
<iframe src="{embed_url}" width="640" height="360"
allow="autoplay; fullscreen" allowfullscreen></iframe>expires_inis 60 to 86,400 seconds (one minute to one day). The default is one hour.- The token works for that one video only, and only inside an iframe on a site that is not vewo.io. Opened as a link, or after it expires, it does not play.
- If the workspace limits embeds to your domains, the token only plays on those.
- A token is a pass: anyone holding a valid
embed_urlcan watch until it expires. Keep lifetimes short and mint one per viewer. - To cancel every token issued so far, a workspace admin rotates the view key under API, then View tokens.
Webhooks
vewo sends an HTTPS POST to your endpoint for video.ready, video.failed and video.deleted. Every event has the same envelope; data carries the video fields from GET /v1/videos/{id} (without play_count and expires_at), including a thumbnail_url valid for 24 hours from when the event was sent.
{
"type": "video.failed",
"workspace_id": "ws_...",
"created_at": 1791393004,
"data": { "id": "...", "status": "FAILED", "error": "...", ... }
}Verifying the signature
Deliveries are signed with the Standard Webhooks scheme, so any of its official libraries will verify them. The headers are webhook-id, webhook-timestamp (unix seconds) and webhook-signature (v1, plus a base64 HMAC-SHA256 of {id}.{timestamp}.{body}, keyed with the base64-decoded part of your secret after whsec_). Verify the raw body, before parsing it, and reject timestamps more than a few minutes old.
# pip install standardwebhooks from standardwebhooks.webhooks import Webhook wh = Webhook(os.environ["VEWO_WEBHOOK_SECRET"]) # "whsec_..." event = wh.verify(raw_body, request.headers) # raises if the signature is wrong
import crypto from "node:crypto";
function verify(secret, headers, rawBody) {
const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = crypto.createHmac("sha256", key)
.update(`${id}.${ts}.${rawBody}`).digest("base64");
return headers["webhook-signature"].split(" ").some((part) => {
const [version, sig] = part.split(",");
return version === "v1" && sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
});
}Delivery and retries
- Any 2xx answer within 10 seconds counts as delivered. Anything else is retried after 10 s, 30 s, 1 min, 2 min, 5 min and 10 min, then every 15 minutes, for up to 24 hours.
- Delivery is at least once, so the same event can arrive twice.
webhook-idstays the same across retries: use it to ignore a repeat. - An endpoint that fails 10 deliveries in a row, each after all its retries, is disabled and shows a
disabled_reason. Fix it, then set"enabled": true. - Every delivery, with its request body and your endpoint's answer, is kept in the log for 30 days.
- A company can have up to 20 endpoints. Each has its own secret. Endpoint URLs must be https.
Managing endpoints with a key
GET /v1/webhooks list, plus the event names
POST /v1/webhooks {"url": "https://...", "events": ["video.ready"], "name": "prod"}
returns the secret once
GET /v1/webhooks/{id}
PATCH /v1/webhooks/{id} {"url"?, "events"?, "enabled"?, "name"?}
POST /v1/webhooks/{id}/rotate-secret returns the new secret once
POST /v1/webhooks/{id}/test sends a signed test video.ready now, returns your answer
GET /v1/webhooks/{id}/deliveries ?limit=1..200
DELETE /v1/webhooks/{id}A key manages its own workspace's endpoints. Company-wide endpoints, created in the workspace by an admin, are listed but can only be changed there. Leaving out events subscribes to all three.
Analytics
GET /v1/videos/{id}/analytics?days=30 returns the same figures as the dashboard, for the last 1 to 365 days. The main ones:
- views
- Times the video's page or player was opened.
- unique_viewers
- Distinct viewers, counted by a one-way hash of their network address. No address is stored.
- started
- Views where playback began.
- play_rate
- Percent of views that started playing.
- watch_seconds
- Total time watched.
- avg_watch_seconds, median_watch_seconds
- Per started play.
- avg_watch_pct
- How far into the video plays reached, on average.
- completion_rate
- Percent of started plays that reached 95%.
- on_vewo, embedded
- Views on vewo.io and in embeds.
- by_day
- Views per day.
- retention
- The share of plays still watching at each point in the video.
- countries, devices, browsers, embed_hosts, sources
- Top values with counts.
- change
- Percent change of the headline figures against the previous period of the same length, when there is one.
Errors, retries and request ids
Errors return a status code and {"detail": "..."} with a sentence you can show or log. A failed multipart complete returns {"detail": {"message": "...", "parts": [7, 8]}}.
- 400
- Something in the request is invalid.
- 401, 403
- No valid key, or the key may not do this.
- 402
- The company's free month ended without a subscription. The library is read-only until it subscribes; reads still work.
- 404
- Not found, or not in this key's workspace.
- 409
- Conflict, for example completing an upload with missing parts.
- 413
- The file is over 100 GB, or would exceed the storage limit.
- 422
- A body that does not match the schema, or an Idempotency-Key reused for a different request.
- 429
- Too many requests. Wait for
Retry-Afterseconds.
Idempotency-Key
POST /v1/videos and POST /v1/webhooks accept an Idempotency-Key header (1 to 255 printable characters). Retrying with the same key within 24 hours returns the first response, marked Idempotent-Replayed: true, instead of creating a second video. The same key with a different body is 422. A retry while the first is still running gets 409 with Retry-After. A request that failed is not remembered, so retrying it runs it again. Keys are scoped to your API key.
Request ids
Every response has an X-Request-Id header. If you send your own (8 to 64 letters, digits, dots, dashes or underscores) it is kept, so your logs and ours share it. Include it when you write to support@vewo.io and we can find the request.
Limits
- Per upload
- 100 GB. A single PUT up to 5 GB, multipart above that.
- Storage
- 2 TB per company, shared by its workspaces.
- Seats
- 15 people per company.
- Workspaces
- 5 per company.
- Webhook endpoints
- 20 per company.
- Requests
- 120 a minute per key. Every key response has
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset. - View tokens
- One minute to one day each.
- Quality
- Up to 4K.
Reference
The OpenAPI 3.1 description of every /v1 operation is at https://api.vewo.io/v1/openapi.json, for generating a client or importing into an API tool.
Something missing or wrong here? Write to support@vewo.io and a person will answer.