Build on the NULX API.

Choose a link or site embed

Look up one video's public player link, protected share links and assigned site destinations before using a playback URL. Both read calls require assets:read.

curl https://nulx.dev/api/v1/assets/<asset_id>/distribution \
  -H "X-API-Key: $NULX_API_KEY"
curl https://nulx.dev/api/v1/deliveries \
  -H "X-API-Key: $NULX_API_KEY"

Create or edit a site delivery in the owner dashboard. Its ?delivery=slug embed scopes the videos, iframe domains, language and stats; it does not deploy a website. Pausing the site makes its embed return 410.

Public links are stable. Protected share links can have a PIN and expiry. Signed embeds need a server-issued playback token that expires; do not save one as a permanent embed. Domain allowlists restrict iframe placement, not access to a copied URL.

For an external player that only accepts HLS, the account owner can manage an external HLS link in Video → Share → Connect to an external platform. Its playback address is visible to the receiving platform and viewers.

Authentication

One header, scoped keys.

Send your key on /api/v1 requests. oEmbed needs no key. Keys are created in the dashboard and can carry only the scopes you need.

Example request

curl https://nulx.dev/api/v1/assets \
  -H "X-API-Key: $NULX_API_KEY"

Available scopes

API keys are available on paid plans. Free-plan accounts see the key screen but cannot issue keys.

Connect a course platform

Instructors upload on your course site, and enrolled students watch there. Keep the NULX API key on your platform backend.

1. Check the instructor's access

   After checking instructor permissions, your backend starts the upload with an assets:write key. Use initiate for a single PUT, or initiate_multipart for large or resumable files on either R2 path. Pass storage_connection_id for a customer R2 connection. Set playback_policy to signed for paid lessons.

2. Transfer the file to R2

   For default R2 storage, have your platform backend send the file to the short-lived upload URL. With a customer R2 connection, browser uploads need CORS that permits your course site's origin, PUT, and the upload request headers, and exposes the ETag response header. Call the NULX completion API afterward to start transcoding.

3. Add the ready video to a lesson

   Wait for video.asset.ready or check the asset status, then associate the NULX asset ID with the instructor's lesson. Enforce instructor ownership in your platform.

4. Issue playback for enrolled students

   On each playback request, your backend checks enrollment before using a separate playback:read key and returning embed_url only to the authorized learner. The token lasts 15 minutes by default; reissue the URL server-side and reopen the player when it expires. Put the previous watch time in the new embed_url's t query parameter to resume. Never expose an API key or original download URL to the browser.

{"filename":"lecture.mp4","bytes_expected":73400320,"playback_policy":"signed"}

Show upload and transcoding status

Measure file transfer progress in the instructor's browser. NULX sends video.upload.completed/failed, video.job.queued/started/failed, and video.asset.ready/errored webhooks as the state changes. A job failure may be retried; an asset error means this processing run has no playable output. While transcoding, your backend can poll the numeric asset_id from the upload response with an assets:read key for the current job status and progress. Progress is worker-reported and can drop when a job retries.

GET /api/v1/assets/<asset_id>
{"playback_status":"processing","processing_stage":"transcoding","transcoding_job":{"status":"running","progress_percent":42}}

Upload to R2 with the JavaScript SDK

The /lessons/42/... paths below are example routes to implement on your course backend. The SDK sends the file only to the short-lived upload URL returned by that backend; no NULX API key belongs in browser code.

<script src="https://nulx.dev/player/nulx-player-dd7597fd0f3742ce.js?locale=en"
  integrity="sha384-9sVWZ35V6gt1rYswpaB09YVGjGfA3BOvHgdZ7CLbDFy3fMEKJB3VNmRhw2319SCU" crossorigin="anonymous" async></script>
<input id="lesson-file" type="file" accept="video/*">
<p id="upload-status" role="status"></p>
<script type="module">
await customElements.whenDefined("nulx-player")
const post = async (path, body) => {
  const headers = { "Content-Type": "application/json" }
  const csrf = document.querySelector('meta[name="csrf-token"]')?.content
  if (csrf) headers["X-CSRF-Token"] = csrf
  const response = await fetch(path, {
    method: "POST", credentials: "same-origin", headers, body: JSON.stringify(body)
  })
  if (!response.ok) {
    const error = new Error("Request failed: " + response.status)
    error.status = response.status
    throw error
  }
  return response.json()
}
document.querySelector("#lesson-file").addEventListener("change", async (event) => {
  const file = event.target.files[0]
  if (!file) return
  const status = document.querySelector("#upload-status")
  try {
    await NulxSDK.uploadMultipart(file, {
      create: (file) => post("/lessons/42/uploads", { filename: file.name, bytes_expected: file.size, content_type: file.type || "application/octet-stream" }),
      signPart: ({ uploadId, partNumber, contentLength }) => post(`/lessons/42/uploads/${uploadId}/parts`, { part_number: partNumber, content_length: contentLength }),
      complete: ({ uploadId, bytesReceived, parts }) => post(`/lessons/42/uploads/${uploadId}/complete`, { bytes_received: bytesReceived, parts }),
      onProgress: ({ percent }) => { status.textContent = percent + "%" }
    })
    status.textContent = "Upload finished. Video processing has started."
  } catch (_error) {
    status.textContent = "Could not upload the video. Try again."
  }
})
</script>

Your course backend must check login, instructor ownership, and CSRF. It calls NULX initiate_multipart with a server-enforced signed policy and Idempotency-Key, then proxies sign_part and complete_multipart, returning only needed fields to the browser. The SDK supports R2 s3_multipart uploads. R2 CORS must allow PUT from your course site and expose ETag. The short-lived upload URL is visible in the browser, so do not log or share it. After a failed upload, resume the same session on your backend or clean it up with abort_multipart.

Receive learner player state

The SDK comes in the version-pinned, integrity-checked script above. Older copied player snippets may not contain it. Request playback through your course site's login session. Call lesson.renew() before the token expires to resume at the last reported position.

<div id="lesson-player"></div>
<p id="lesson-status" role="status"></p>
<script type="module">
await customElements.whenDefined("nulx-player")
const host = document.querySelector("#lesson-player")
const status = document.querySelector("#lesson-status")
host.addEventListener("nulx:state", ({ detail }) => {
  // detail.state: idle, loading, ready, buffering, playing, paused, ended, error
  status.textContent = {
    loading: "Loading video…",
    buffering: "Getting playback ready…",
    error: "Could not play this video. Try again."
  }[detail.state] || ""
})
host.addEventListener("nulx:progress", ({ detail }) => {
  // detail.currentTime and detail.duration are seconds
})
const lesson = NulxSDK.player(host, async () => {
  const response = await fetch("/lessons/42/playback", { credentials: "same-origin" })
  if (!response.ok) throw new Error("Playback denied: " + response.status)
  return response.json() // { asset_id, playback_policy: "signed", embed_url }
})
try { await lesson.load() }
catch (_error) { status.textContent = "Could not play this video. Try again." }
// Refresh from your backend before the token expires; watch position is kept.
// await lesson.renew()
</script>

For every request, your course backend checks enrollment and uses a separate playback:read key to ask NULX for playback. Return only asset_id, signed playback_policy, and the short-lived embed_url to the browser. The SDK rejects public or foreign-origin embeds, but cannot prevent an authorized viewer from copying a short-lived URL or recording the screen.

Configure Cloudflare R2 CORS

Signed playback needs an eligible plan and protected delivery configured for the storage connection. A public source bucket can bypass playback protection. Add your course site's domain to the embed allowlist.

Give external players a per-viewer address

For another company's web player (hls.js, Video.js and the like) or its own app playing NULX videos directly. Each time a signed-in viewer presses play, the platform's server asks for a new address with a playback:read key and hands it to that viewer's player only. Private and protected videos only.

• It plays only where it was first played (the same internet connection). Opened anywhere else, it is blocked.
• It works for the video's length plus 30 minutes (at least 2 hours, at most 24).
• It plays in other companies' website players and in their own apps.
• If the viewer's connection changes (Wi-Fi to mobile data), get a new address.

POST /api/v1/playback/<asset_id>/grants
X-API-Key: <playback:read key>
{"viewer":"student-1024"}

201 {"grant_id":"0123456789abcdef","hls_url":"https://cdn.nulx.dev/_nulx_edge/grant-…/master.m3u8",
     "expires_at":"…","ttl_seconds":7200,"binding":"first_network","viewer":"student-1024"}

DELETE /api/v1/playback/<asset_id>/grants/<grant_id>

Public videos are refused with 422 public_video, videos on your own connected storage with 422 storage_unsupported. Played anywhere else, media requests get 403; get a new address then. Trashing the video, making it unplayable or deleting the key stops its addresses at once.

oEmbed API

Turn a public video URL into JSON containing its title, thumbnail and iframe code. No API key is required.

oEmbed is available only for ready, public videos. Private, signed and scheduled videos, and protected share links are not supported.

Example request

curl --get https://nulx.dev/oembed \
  --data-urlencode "url=https://nulx.dev/watch/<external_id>" \
  --data-urlencode "format=json" \
  --data-urlencode "maxwidth=640"

Replace <external_id> with the video's external ID. Copy the request URL from video details → Share → Embed this video on a website → Show developer integrations.

Query parameters

url

Required. A /watch/<external_id> or /embed/<external_id> URL on the same host. URL-encode this query value. Protected /s/ links and HLS URLs are not supported.

format

Optional. Only json is supported; JSON is also the default.

maxwidth

Optional. Default width is 640px. Positive integers are clamped to 80–1920px; height is calculated at 16:9.

maxheight

Optional. Default height is 360px. Positive integers are clamped to 80–1080px; if smaller than the current height, width is reduced proportionally.

Example success response

{
  "version": "1.0",
  "type": "video",
  "provider_name": "NULX",
  "provider_url": "https://nulx.dev/",
  "title": "...",
  "author_name": "...",
  "width": 640,
  "height": 360,
  "html": "<iframe src=\"https://nulx.dev/embed/<external_id>\" width=\"640\" height=\"360\" frameborder=\"0\" allow=\"autoplay; fullscreen; picture-in-picture; encrypted-media\" allowfullscreen title=\"...\"></iframe>",
  "thumbnail_url": "https://nulx.dev/watch/<external_id>/poster"
}

thumbnail_url is returned only when a poster is configured. Public watch and embed pages advertise an application/json+oembed discovery link. Automatic embedding depends on the consuming service.

Error responses have empty bodies. 404: missing URL, invalid host/path, unknown, private, signed, processing or scheduled video. 501: a format other than JSON. 429: more than 60 requests per minute per IP. Embed domain restrictions still apply.

Webhooks

Subscribe instead of polling.

Register an HTTPS endpoint from the dashboard or the API and NULX posts lifecycle events as signed JSON. 5xx, 429, and transport errors are retried with backoff; other 4xx/3xx responses are not retried.

Delivery format

POST https://your-server.example/hooks/nulx
NULX-Event: video.asset.ready
NULX-Event-Id: <event uuid>
NULX-Delivery-Id: <delivery uuid>
NULX-Timestamp: 1758432000
NULX-Signature: t=1758432000,v1=<hex hmac-sha256>

{
  "id": "<event uuid>",
  "event": "video.asset.ready",
  "created_at": "2026-09-21T04:00:00Z",
  "data": { "asset_id": "…", "title": "…", "playback_status": "ready", "playback_url": "…" }
}

Signature verification

Compute hex HMAC-SHA256 of "<timestamp>.<raw body>" with the secret shown once at endpoint creation, and compare it to v1. Reject timestamps older than 5 minutes to stop replays.

expected = "t=" + timestamp + ",v1=" + hex_hmac_sha256(secret, timestamp + "." + raw_body)

Events you can subscribe to