> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raidzero.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Walk through our media lifecycle: ingest assets, index video and transcripts, poll for readiness, and run scoped natural-language search.

## Assets start in your system

Ingest requests carry your `asset_id`, so search results can join back to your database, CRM, support ticket, observability platform, or call log without ID translation.

```ts theme={null}
await client.ingest({
  source: "url",
  asset_id: "call_8294",
  asset_class: "customer_acme",
  url: "https://storage.example.com/calls/8294.mp3",
});
```

## Asset classes define search scope

`asset_class` is how you draw the boundary around what gets searched together. For most products, it maps to the entity your customers think in terms of:

* one end customer
* one workspace
* one project
* one support queue

> [!WARNING]
>
> If you're building customer-facing search, scope by `asset_class` or explicit `asset_ids`. Global search (`scope: "all"`) searches across your indexed assets.

## Indexing surface types

`types` controls what gets indexed and searched.

| Type | Use when |
| - | - |
| `audio` | Speaker identity, acoustic events, sound-level patterns. |
| `video` | On-screen content, visual context, screen recordings. |
| `transcript` | Spoken words, topic retrieval, semantic search over dialogue. |

Most voice AI use cases want all three:

```ts theme={null}
types: ["audio", "video", "transcript"]
```

## Indexing is async

Ingest returns a `task_id` immediately. The actual indexing happens in the background. Poll until `ready` or `failed`.

```ts theme={null}
const { task_id } = await client.ingest(request);
const task = await client.pollTask(task_id);

if (task.status === "failed") {
  throw new Error(task.error ?? "indexing failed");
}
```

Task states: `pending` → `indexing` → `ready` (or `failed`).

## Search returns timestamped matches

Results include `start_ms` and `end_ms`: millisecond offsets into the source recording.

```json theme={null}
{
  "asset_id": "call_8294",
  "score": 0.87,
  "start_ms": 42000,
  "end_ms": 58000,
  "match_type": "transcript"
}
```

`threshold` controls how strict the match has to be. Default is `0.5`. Raise it to get fewer, higher-confidence results.

## Your data stays yours

The API returns: `asset_id`, `asset_class`, `types`, scores, and timestamps. Provider IDs, index keys, and pipeline details stay behind the API.

> [card] [TypeScript SDK](https://docs.raidzero.icu/sdks/typescript.md)
>
> Inputs, outputs, and error types for the TypeScript client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.