Niravi Cloud API

Search, recall, and analyze a library of video, photos and documents over a simple HTTP API, with a TypeScript SDK and an MCP server for Claude.

Everything is one base URL, https://api.niravi.io, and one credential, an API key (nv_…). A key works in its home workspace and any others you grant it (Concepts).

New (2026-10-15): every upload runs on Arrow unless you name a deprecated NiNo tier. Since 2026-10-14: images & documents, object regions, library-wide People and an Arrow-only feature set. The older NiNo pipelines and NiQu (classic) search are deprecated.

1. Get an API key

Create one in the dashboard → Settings → Developer. Pick the scopes (read and/or write) and an optional expiry. The secret is shown once — store it somewhere safe.

2. Make your first call

A new key’s home workspace is empty, so start with a read-only demo. Keys can read demo_newsroom, demo_enterprise and demo_creator by default; GET /api/v1/workspaces lists what yours can reach.

curl https://api.niravi.io/api/v1/search \
  -H "X-API-Key: $NIRAVI_API_KEY" \
  -H "X-Workspace-Id: demo_newsroom" \
  -H "Content-Type: application/json" \
  -d '{"query": "a reporter speaking to the camera", "limit": 5}'

A successful response is an envelope, { "success": true, "data": … }; hits are in data.results. Errors are described in Concepts.

3. Upload, then search your own library

Uploads need a key with the write scope and land in its home workspace.

curl https://api.niravi.io/api/v1/videos \
  -H "X-API-Key: $NIRAVI_API_KEY" \
  -F "[email protected]"

The response carries a video_id. Processing is asynchronous: poll GET /api/v1/videos/{video_id} until data.video.status is completed (seconds for a photo, about a minute for a short clip). Then search with Arrow:

curl https://api.niravi.io/api/v1/search \
  -H "X-API-Key: $NIRAVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "a man speaking into a microphone", "engine": "arrow", "limit": 5}'

The first search of a new library can take up to 15 seconds while its index loads; after that, searches answer in about a second. A new upload shows up in search within about five minutes of completing.

4. Or use the SDK

// npm install @niravi/sdk
import { connect } from "@niravi/sdk";
const demo = connect("nv_...", { workspace: "demo_newsroom" });
const hits = await demo.search("a reporter speaking to the camera", { limit: 5 });

const niravi = connect("nv_...");                 // the key's home workspace
const { video_id } = await niravi.upload("./clip.mp4");   // Node; runs on Arrow

The SDK’s search() does not take engine yet, so it uses your workspace’s default engine (GET /api/v1/engines). To search Arrow uploads from code today, call POST /api/v1/search with "engine": "arrow", or ask [email protected] to make Arrow your workspace’s default.

The Python SDK is on its way to PyPI; until then, call the HTTP API from Python (any HTTP client works).

Where to next

ConceptsKeys & scopes, workspaces, pagination, errors, rate limits. SearchSemantic search + typed "magic" search by character, location, music, emotion. Recall & ChatAsk natural-language questions grounded in your video. Images & documentsPhotos, PDFs and decks: hits land on the page, the passage and the box. PeopleFaces grouped into people across your whole library. Indexing & enginesChoose the stages per upload or workspace; Arrow vs the deprecated engines. ChangelogWhat changed, and what is deprecated. SDKsTypeScript (Python soon), generated from the same OpenAPI spec. MCP for ClaudeExpose your corpus to Claude as tools. API ReferenceEvery endpoint, grouped, with try-it.

Demo without a key? The interactive API Reference lets you browse every endpoint and its schemas. To run live calls you’ll need a key.