> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Key concepts for working with the Visual Search API — authentication, indexing, and status.

## Authentication

Every request requires your API key in the `Authorization` header:

```
Authorization: sk-mavi-...
```

Requests without a valid key are rejected with a `401` error. See [Create Your Key](/visual-search/create-your-key).

## Indexing Pipeline

When you upload content, the platform runs two indexing pipelines in parallel and automatically — you don't need to trigger them:

| Pipeline                    | What it does                                          | Enables                               |
| --------------------------- | ----------------------------------------------------- | ------------------------------------- |
| **Embedding**               | Encodes visual frames and audio into semantic vectors | Natural-language search, image search |
| **Caption & transcription** | Generates scene descriptions and transcribes speech   | Transcript search, audio search       |

## Task Status

Every uploaded item has a processing status:

| Status    | Meaning                                                     |
| --------- | ----------------------------------------------------------- |
| `UNPARSE` | Upload accepted — indexing in progress. Not yet searchable. |
| `PARSE`   | Indexing complete. Fully searchable across all modalities.  |

To wait for `PARSE`, either register a `callback` URL at upload time, or poll the status. The right polling endpoint depends on the upload method — see [Upload Overview → How to wait for indexing to finish](/visual-search/upload-overview#how-to-wait-for-indexing-to-finish) for the per-method mapping.

## A Note on Field Casing

The Visual Search API mixes **camelCase** and **snake\_case** across endpoints. The same logical concept can appear with different casings in different responses or parameter names:

| Concept                      | Casing varies                                                                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Video identifier             | Upload returns `videoNo`; `list_videos` / `get_metadata` / `get_video_ids_by_task_id` responses use `video_no`; request parameters use `video_no` |
| Task identifier              | `upload_from_creator` returns `taskId`; `get_video_ids_by_task_id` request parameter is `task_id`                                                 |
| Timestamps in search results | `startTime`, `endTime` (camel) in `search` responses; `start_time`, `end_time` (snake) in `search_clips_by_image`                                 |

Pass the value through verbatim — both casings refer to the same underlying ID. Each endpoint page documents the exact field names it uses.

## Callback Notifications

When you provide a `callback` URL on upload, the platform `POST`s to it when indexing finishes:

```json theme={null}
{
    "videoNo": "VI554046065381212160",
    "status": "PARSE"
}
```

The platform retries up to 5 times on failure. Use a tool like [Beeceptor](https://beeceptor.com/) to test webhook delivery during development.

## Folders (`folder_id`)

Organize your library into **folders**. Every upload can target a folder via `folder_id`, and every list/search can be scoped to one folder. Folders are managed through the [Folder Management](/visual-search/list-folders) endpoints (list, create, rename, delete, and move videos between folders).

* **On upload** — omit `folder_id` (or pass `-1`) to store in your account's **Default folder**, created automatically on first use. Pass a folder id to store in that folder.
* **On list / search** — omit `folder_id` to query across your **entire account**; pass a folder id to scope to that folder.
* Create folders with [Create Folder](/visual-search/create-folder), list them with [List Folders](/visual-search/list-folders), and reorganize existing videos with [Move Videos](/visual-search/move-videos-to-folder).

<Note>
  **Migration note**: the old `unique_id` namespace parameter has been removed. Every request is now scoped to your whole account; organize content with `folder_id` and the Folder Management endpoints instead.
</Note>

## Rate Limits & Billing

* All endpoints are rate-limited per account. See [Rate Limits](/visual-search/rate-limits).
* Uploads and searches deduct credits from your account balance. Insufficient balance causes requests to fail.