vewo Business API

Upload, private playback and webhooks

Upload video from your backend, get a signed webhook when it can play, and show private video to one viewer at a time. The API is part of vewo Business. Base URL https://api.vewo.io/v1.

On this page

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/me tells 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
  }
}
  1. PUT byte range [(n-1) * part_size, n * part_size) of the file to part n'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.
  2. Part URLs expire after an hour. Get fresh ones with POST /v1/videos/{id}/upload/parts {"part_numbers": [7, 8]}.
  3. After an interruption, GET /v1/videos/{id}/upload/parts returns uploaded and missing, so you send only what is missing.
  4. 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 returns 409 and 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, READY or FAILED.
title
Text, possibly empty.
visibility
public (anyone, embeddable), link (only with the full link) or private (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}. url is 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_in is 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_url can 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-id stays 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-After seconds.

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-Remaining and RateLimit-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.