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-16): new workspaces search with Arrow by default, .nmap exports, several moments per video in search, one error envelope and rate-limit headers on every response, and the TypeScript SDK and MCP server 0.2.0. See the changelog. 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) or failed. Then search your library:

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", "limit": 5}'

A new workspace searches with Arrow by default, so no engine is needed. The first search of a library takes about 4 seconds while its index loads; after that, searches answer in under a second. A finished upload is searchable within seconds of completing (3 to 7 s measured); assets still processing never appear in results.

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
const mine = await niravi.search("a man speaking into a microphone", { engine: "arrow", momentsPerVideo: 3 });

The Python SDK 0.2.0 has the same surface but is not on PyPI yet: see Python SDK. Until it is, call the HTTP API from Python (any HTTP client works).

Where to next

ConceptsKeys & scopes, workspaces, pagination, the error envelope, 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 and Python 0.2.0, 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.