For AI agents: a documentation index is available at /llms.txt. Markdown versions are available at matching .md URLs.

Skip to content

Redactor API Playground

Redactor API sample

Download the Redactor API Playground, a small runnable Node.js and TypeScript project that walks through a complete Redactor workflow against your own Redactor Server: load a video, run detections, edit in the embedded editor, then render, export, and persist the result.

What is the Redactor API Playground?

The Redactor API Playground is a standalone Node.js and TypeScript sample that shows the Redactor API and the embedded editor working together in one linear, readable workflow. It connects to a Redactor Server running in Docker (a Compose file is included), serves its own small web page that hosts the embedded editor, and calls the API for every step from loading a video to exporting the redacted result.

Use it as a working reference when building your own integration: run it once to see the full flow, then lift the pieces you need from the source. It is a demo, not a test harness or a production service. To get a Redactor deployment with Docker examples and AI-optimized documentation, see the Redactor Agent Toolkit.

What the playground does

Each run walks through the same sequence, pausing for you in the terminal and in the browser.

Load and detect

Loads the bundled sample video with MEDIA_PREPARE, then runs license plate and vehicle detection as a separate operation on the prepared session.

Edit in the embedded editor

Adds sample boxes with the EDIT feature, then opens the embedded Redactor editor so you can review, adjust, and start an export.

Render and export

When the editor reports redactor.export.submit, runs MEDIA_RENDER and exports the redacted MP4 to a local folder.

Persist and zone

Persists the session so it can be reloaded later and, optionally, scopes everything to a tenant with a signed JWT.

Along the way, the playground also:

  • Hosts the editor page with a small Express server that proxies Redactor on the same origin (/proxy/redactor and /socket.io), the same-domain pattern described in Embedded Redactor UI.
  • Detaches the editor from the session before rendering.
  • Logs every API request and response to run/logs/client.log.
  • Types request bodies and editor events with the public Sighthound TypeScript definitions in src/sh-types.

Requirements

  • Node.js 18 or newer with npm, to run the sample (npm start).
  • Docker with Docker Compose, to run the Redactor Server container defined in the included docker-compose.yml. The playground does not start Redactor itself.
  • A Redactor license with API access. Contact [email protected] to obtain a Redactor API serial number. Optional tenant zoning additionally needs a tenant-capable license.
  • An Intel or AMD (x86_64) host for the Redactor Server container.
  • Free local ports 9000 (Redactor) and 3456 (playground page).
  • A recent browser such as Chrome, Firefox, Edge, or Safari.
  • Optional: an NVIDIA GPU. The Compose file reserves GPUs for Redactor. On a host without one, remove the deploy block from docker-compose.yml to run CPU-only.

Apple Silicon not supported

Redactor Server currently requires an Intel or AMD x86_64 processor. Apple Silicon M-series Macs are not supported for the Redactor server container.

Set up the playground

Prefer the terminal? Copy the download command or fetch this page as Markdown.

  1. Download and extract the zip. The archive has no top-level folder, so extract it into a folder of its own.

    curl -L -o redactor-api-playground.zip "https://sh-io-downloads.s3.us-east-1.amazonaws.com/redactor/api-playground/redactor-api-playground.zip"
    unzip redactor-api-playground.zip -d redactor-api-playground
    cd redactor-api-playground
    
    Invoke-WebRequest -Uri "https://sh-io-downloads.s3.us-east-1.amazonaws.com/redactor/api-playground/redactor-api-playground.zip" -OutFile redactor-api-playground.zip
    Expand-Archive redactor-api-playground.zip -DestinationPath redactor-api-playground
    cd redactor-api-playground
    
  2. Start Redactor. From the extracted folder, start the Redactor Server container:

    docker compose up -d --pull always
    

    This runs sighthound/redactor:7 on port 9000 with the API enabled, an API token that matches config.json, and its data under run/volumes/. If the host has no NVIDIA GPU, remove the deploy block from docker-compose.yml first.

  3. Complete the first-time setup. If this is the first run of this Redactor instance, open http://localhost:9000/admin, create the initial admin user, add your license, and wait for the server to restart.

  4. Install dependencies and start the playground.

    npm install
    npm start
    
  5. Follow the prompts. The playground checks that Redactor is healthy, loads the sample video, runs the detections and the edit, and opens the embedded editor in your browser. Then:

    1. Review the video in the editor, click Export at the top of the page, and complete the export dialog.
    2. Press Enter in the terminal. The playground renders the session, exports the redacted MP4, and opens it.
    3. Press Enter again to persist the session and exit.

The first run can take a few minutes

On a GPU-enabled container, the first processing operation can take a few minutes while Redactor warms up its models. CPU-only instances do not have this delay.

Where the results go

Paths are relative to the extracted playground folder.

  • run/volumes/data/work/output/video_REDACTED.mp4 - the rendered, redacted video.
  • run/volumes/data/persisted/ - the persisted session, including its data and media.
  • run/logs/client.log - every API request and response, appended on each run.

Each run clears run/volumes/data/work and drops the previous demo session before starting, so copy out anything you want to keep from work. The persisted folder is not cleared.

What's in the zip

The extracted folder is a complete project. Its README.md covers the workflow step by step, the full configuration table, and the folder layout, so continue there once the sample runs.

  • README.md and AGENTS.md - full documentation, the module map, and the exact operation sequence. AGENTS.md also gives AI coding agents the rules for adapting the sample.
  • docker-compose.yml and config.json - the Redactor Server container and the connection settings for the sample.
  • src/ - the TypeScript sources. Start with src/main.ts, which contains the whole workflow in order. src/api.ts is the API client, src/server.ts hosts the editor page and proxies, and src/sh-types/ holds the Sighthound TypeScript definitions.
  • public/index.html - the page that mounts the embedded editor and forwards its events.
  • samples/input.mp4 - the sample video used on every run.
  • keys/ - a demo key pair used only for optional tenant zoning.

Configuration

Connection settings live in config.json (see config.example.json). The defaults match the included Compose file, so most people change nothing.

If you change the API token, update REDACTOR_API_TOKEN in docker-compose.yml and redactorApiToken in config.json together, then recreate the container. The token and the keys/ pair that ship in the zip are demo material for local use only.

Optional: tenant zoning

Tenant zoning is off by default. To try it, set tenantId in config.json to a licensed tenant that matches a public key in keys/public/, enable REDACTOR_TENANT_PUBLIC_KEYS in docker-compose.yml, add a tenant-capable license, and recreate the container. The playground then signs an RS256 tenant JWT with the demo key pair and passes it to the editor.

See the README.md in the zip for the exact steps, and Multi-Tenant Zoning (JWT) for how zoning works.

Troubleshooting and safety

  • API traffic: Check run/logs/client.log to see the requests the playground sent and the responses it received.
  • Container changes: Recreate the Redactor container after changing docker-compose.yml. The API token and tenant zoning settings are read when Redactor starts.
  • Hardware: Use an x86_64 host for the Redactor server container. Apple Silicon M-series Macs are not supported.
  • Secrets: Do not paste API tokens, license keys, or credentials into chat.
  • Official download: Use only the official playground zip URL: redactor-api-playground.zip.
  • Version: The zip always contains the latest version of the playground. If you run into an issue, you can find the version you have in the version field of package.json.

If you need support, include relevant log context when contacting [email protected], but do not send tokens, license keys, or credentials.