> ## Documentation Index
> Fetch the complete documentation index at: https://docs.icelab.sh/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.
</Warning>

## 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 title="TypeScript SDK" icon="square-js" href="/sdks/typescript">
  Inputs, outputs, and error types for the TypeScript client.
</Card>