Using the API

The Videas REST API lets you manage videos, workspaces and uploads from your own backend. This guide covers everything you need to make your first authenticated call.

Base URL

Every endpoint lives under this prefix:

https://api.videas.com/api/external/v1/

The examples below show the full URL for each call.

Authentication

Every request must carry an API key as a Bearer token:

Authorization: Bearer sk_your_key_here

Create one from Settings → API keys — see Creating an API key. The key both identifies the organization the call acts on and defines the scopes it may use. Requests without a valid key return 401 Unauthorized.

Your first request

List the videos in your organization:

curl https://api.videas.com/api/external/v1/videos/ \
  -H "Authorization: Bearer sk_your_key_here"

The same call in JavaScript:

const res = await fetch('https://api.videas.com/api/external/v1/videos/', {
  headers: { Authorization: 'Bearer sk_your_key_here' },
})
const { items } = await res.json()

…and in Python:

import requests

res = requests.get(
    "https://api.videas.com/api/external/v1/videos/",
    headers={"Authorization": "Bearer sk_your_key_here"},
)
res.raise_for_status()
videos = res.json()["items"]

Scopes

A key only works within the scopes it was granted:

A call that needs a scope the key doesn’t hold returns 403 Forbidden.

Core endpoints

Paths are relative to the base URL above. The full list, with parameters and response schemas, is in the API reference.

Pagination

List endpoints accept limit (1–100, default 20) and offset:

curl "https://api.videas.com/api/external/v1/videos/?limit=50&offset=100" \
  -H "Authorization: Bearer sk_your_key_here"

The /videos/ endpoint also supports filters such as search, status, tag, created_after, created_before and ordering.

Rate limits

Each key is rate-limited (by default 1000 requests per hour). Every response includes:

• X-RateLimit-Limit — the ceiling for the current window;
• X-RateLimit-Remaining — calls left in the window;
• X-RateLimit-Reset — Unix timestamp when the window resets.

When you go over the limit you get 429 Too Many Requests with a Retry-After header (seconds to wait). Pause until then before retrying.

Billing

API calls are not billed. There is no per-request cost and no block of calls to buy: API access is included, and only the rate is capped (see Rate limits above).

What your calls trigger does draw on your organization’s credits, at the rates published on the Pricing page — exactly as it would if the action came from the app:

• storage for the videos and files you upload;
• delivery to your viewers;
• subtitle generation you request.

If your organization’s credit balance is depleted, a call that triggers one of these actions may be rejected with 402 Payment Required — add credits to resume.

Errors

The API uses standard HTTP status codes and returns a JSON body with an error object describing the problem:

Uploading a video (TUS)

Uploads use the resumable TUS protocol: create an upload session (POST /upload/, Write Assets), then transfer the file in chunks (≤ 50 MiB each) to the URL returned in the Location header.

The dedicated Uploads guide has the full walkthrough, including how to handle large files:

• How uploads work
• Upload with the REST API — curl, chunks, resume
• Upload with the SDK — one call, chunking built in

Next steps

• Creating an API key
• Try any endpoint live with Try it out in the API reference.