Authentication and API basics

The API's address, API keys, headers, environments, response conventions and versioning.

Base URL#

Every request goes to https://api.videxo.io, over HTTPS. Paths start with the API version, /v1. Request and response bodies are JSON, except file uploads and downloads.

bash

export VIDEXO_API_URL="https://api.videxo.io"

API keys#

Create a key in the dashboard under API keys. Give it a name that says where it runs, and choose when it expires: never, or in 30 days, 90 days or one year. The key is shown once, so copy it into your secret store. A key is vdx_ followed by 64 letters.

A key belongs to the organization it was created in, not to the member who created it (Teams and organizations): it keeps working after that member leaves, and the keys page shows who created each one.

Send it in the Authorization header of every request:

text

Authorization: Bearer <your key>

A key gives full access to its organization through the API, whatever the role of the member who created it: it creates jobs that use the organization's credits, reads its jobs and their files, and manages its webhooks. Keep it on your server. Never put it in browser or mobile app code; for uploads from a browser or an app, your server creates a one-time upload URL (Files).

To replace a key, create a new one, deploy it, then revoke the old one in the dashboard. A revoked key stops working within about a minute. A request without a valid key returns 401 authentication_failed with one of these reasons (Error codes). Many requests from one IP address with keys the API has not seen recently, such as unknown keys, can return 429 rate_limited instead, before the key is checked (Rate limits).

Reason	What to do
`missing_api_key`	Send the `Authorization: Bearer` header.
`invalid_api_key`	Check the key: it is not a key of any account.
`api_key_revoked`	Use another key; this one was revoked.
`api_key_expired`	Create a new key; this one passed its expiry date.

Signed file links and upload URLs carry their own signature and need no API key.

Headers#

Header	Direction	Use
`Authorization`	request	`Bearer` and your API key.
`Content-Type`	request	`application/json` for a JSON body.
`Idempotency-Key`	request	Makes a job creation safe to repeat (Idempotency).
`Content-Type`	response	`application/json`, or `application/problem+json` for an error.
`Retry-After`	response	On `429 rate_limited` and `503 service_unavailable`: the seconds to wait (Rate limits).
`WWW-Authenticate`	response	On `401`: the `Bearer` scheme the API expects.
`Request-Id`	response	On every response: the request's id, to quote to support (Error codes).

Environments#

During the preview there is one environment: the API at https://api.videxo.io. There are no separate test keys or sandbox, so every job runs and uses credits. To try requests, use the free credits of your personal organization, and POST /v1/jobs/compile, which validates a request and returns the command it compiles to without creating a job or using credits.

Responses#

Times are ISO 8601 in UTC, such as 2026-11-04T12:00:00.000Z.
IDs start with their kind: job_ for jobs, up_ for uploads, we_ for webhook endpoints and msg_ for webhook deliveries.
A list returns its items in data. A paged list also returns next_cursor: pass it as cursor, with the same filters, for the next page. It is null on the last page.
An error is problem details with a stable code. A response from outside the API, such as a proxy error, may not be JSON.

Versioning#

The version is part of the path: /v1. Within /v1 the API adds new endpoints, optional request fields, response fields, error codes and enum values, so read responses in a way that ignores fields you do not know.

During the preview a change may also break a client. Every such change is listed in the changelog with what to change in your code. After launch, /v1 changes only by additions.