---
url: /docs/guide/quick-start.md
description: Sign up, upload clips, run your first search, and try the API in minutes.
---

# Quick Start

Get from sign-up to your first semantic search in a few minutes — all on [findclix.com](https://findclix.com).

## 1. Create your account

Go to [findclix.com](https://findclix.com) and sign up. A personal workspace is created for you automatically, including an API key (find it later under **Settings → API Keys**).

## 2. Upload your first clips

1. Open the **Library** page and click **Upload**
2. Select a video or image file
3. Wait for indexing to finish (status changes to `complete`)

Uploads are stored securely in your workspace and indexed with AI multimodal embeddings — no tagging or preprocessing needed.

## 3. Search in plain English

Open the **Search** page and describe what you're looking for:

* *"woman dancing in red dress"*
* *"aerial shot of city at night"*
* *"dog running on grass"*

Results point to the exact moment in each video, ranked by relevance.

## 4. Organize (optional)

* **Creators** — link clips to the people or entities behind them, then filter search with `creator_id`
* **Categories** — label content and filter with `category_id`
* **Team** — invite members from the **Team** page; everyone shares the same workspace library

## 5. Try the API

Every workspace gets an API key automatically (**Settings → API Keys**), then:

```bash
curl -H "Authorization: Bearer findclix_a1b2c3…" \
  "https://findclix.com/api/v1/media/search?q=person+walking&n=3"
```

See [Authentication](/agent-api/authentication) for the full API reference.

---

---
url: /docs/api/overview.md
description: The Findclix REST API — base URL, auth, endpoints, and conventions.
---

# API Overview

The Findclix API is a versioned REST API that gives your code full access to your workspace: upload and index media, run semantic searches, manage creators and categories, and check quota. Use it from CLIs, MCP servers, scripts, and automations.

```
Base URL: https://findclix.com/api/v1
Auth:     Authorization: Bearer findclix_<key>
```

## Quick example

```bash
curl -H "Authorization: Bearer findclix_a1b2c3…" \
  "https://findclix.com/api/v1/media/search?q=sunset+over+water&n=5"
```

```json
{
  "success": true,
  "data": [
    {
      "id": "53aebcdc-…",
      "filename": "beach_evening.mp4",
      "score": 0.82,
      "start": 2.1,
      "end": 10.5,
      "url": "https://assets.findclix.com/…",
      "thumbnail": "https://assets.findclix.com/thumb__….jpg",
      "type": "video"
    }
  ],
  "meta": { "query": "sunset over water" }
}
```

## Authentication

Every request carries your workspace API key in the `Authorization` header. Find, rotate, or revoke keys in the dashboard under **Settings → API Keys** (only workspace owners can rotate or revoke).

Keys look like `findclix_a1b2c3…`. A key is tied to one workspace — you can only ever see your own data. Full details in [Authentication](/agent-api/authentication).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/media` | List media (paginated, filterable) |
| `GET` | `/api/v1/media/:id` | Get a single media item |
| `POST` | `/api/v1/media/upload` | Upload and index a media file |
| `GET` | `/api/v1/media/search?q=…` | Hybrid text search |
| `POST` | `/api/v1/media/search/image` | Image search (multipart or JSON) |
| `GET` | `/api/v1/media/highlights` | Most unusual clips, no query needed |
| `DELETE` | `/api/v1/media/:id` | Delete a media item and its chunks |
| `GET` | `/api/v1/creators` | List creators |
| `POST` | `/api/v1/creators` | Create a creator |
| `GET` | `/api/v1/creators/:id` | Get a single creator |
| `GET` | `/api/v1/categories` | List categories |
| `GET` | `/api/v1/categories/:id` | Get a single category |
| `GET` | `/api/v1/workspace` | Workspace info, plan, and usage |
| `GET` | `/api/v1/openapi.json` | OpenAPI 3.1 spec (no auth required) |

## Conventions

* **Response envelope:** success is always `{ success: true, data, meta? }`; errors are always `{ success: false, error: { code, message } }`. Check `success` before touching `data`.
* **Pagination:** list endpoints accept `page` (default `1`) and `per_page` (default `20`, max `100`), and return `meta: { total, page, per_page, total_pages, has_more }`.
* **Filtering:** list and search endpoints accept `creator_id` and `category_id`; media lists also accept `status` (`pending` / `indexing` / `complete` / `error`) and `type` (`video` / `image`).
* **Search tuning:** text and image search accept `dedupe` (drops near-duplicate chunks of the same event); text search accepts `rerank=1` for vision-model precision re-ranking; highlights accept `method` (`centroid` / `knn` / `lof`).
* **Errors:** see [Errors](/agent-api/errors) for every code and how to handle them.

## What to read next

* [Authentication](/agent-api/authentication) — keys, Bearer usage, OpenAPI spec
* [Media](/agent-api/media) — list, get, upload, delete
* [Search](/agent-api/search) — text, image, and highlights
* [Errors](/agent-api/errors) — error codes and handling patterns

---

---
url: /docs/agent-api/authentication.md
description: API keys, Bearer auth, and the OpenAPI spec.
---

# Authentication

The API uses **Bearer token** authentication. Every request must include your API key in the `Authorization` header.

## Getting your API key

Each workspace gets an API key automatically on creation. Find yours in the dashboard under **Settings → API Keys**.

API keys look like this:

```
findclix_a1b2c3d4e5f6...
```

## Making requests

Include the key as a Bearer token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer findclix_a1b2c3d4e5f6..." \
  "https://findclix.com/api/v1/media"
```

::: tip
The API key is tied to your **workspace**. All data returned is scoped to that workspace — you'll never see another workspace's media, creators, or categories.
:::

## OpenAPI spec

The full API spec is available at:

```
GET /api/v1/openapi.json
```

No auth required. Useful for generating client libraries or exploring the API surface.

```bash
curl -s https://findclix.com/api/v1/openapi.json | jq .info.title
# "Findclix API"
```

::: tip
Wiring up an AI agent? Point it at [llms.txt](https://findclix.com/docs/llms.txt) — an index of every docs page with links to per-page Markdown.
:::

## Rate limits

There are no hard rate limits currently, but excessive use may be throttled. If you need higher limits, [contact us](https://findclix.com).

---

---
url: /docs/agent-api/media.md
description: List, get, upload, and delete media.
---

# Media

List, get, upload, and delete media items in your workspace.

## List media

```
GET /api/v1/media
```

Returns a paginated list of all media in your workspace.

### Query parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `page` | int | `1` | Page number |
| `per_page` | int | `20` | Items per page (max `100`) |
| `creator_id` | string | — | Filter by creator ID |
| `category_id` | string | — | Filter by category ID |
| `status` | string | — | Filter: `pending`, `indexing`, `complete`, `error` |
| `type` | string | — | Filter: `video`, `image` |

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/media?page=1&per_page=5"
```

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "53aebcdc-...",
      "filename": "simple walk.MP4",
      "url": "https://assets.findclix.com/...",
      "thumbnail": "https://assets.findclix.com/thumb__....jpg",
      "type": "video",
      "status": "complete",
      "size": 2734894,
      "duration": 7,
      "width": 480,
      "height": 854,
      "category_ids": [],
      "creators": [],
      "notes": "Indexing complete",
      "created_at": "2026-07-07T15:09:50.978Z"
    }
  ],
  "meta": {
    "total": 9,
    "page": 1,
    "per_page": 5,
    "total_pages": 2,
    "has_more": true
  }
}
```

### Interactive reference

***

## Get media

```
GET /api/v1/media/:id
```

Returns a single media item by ID.

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/media/53aebcdc-beb1-4968-bd84-9c7d4a80334f"
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "53aebcdc-...",
    "filename": "simple walk.MP4",
    "url": "https://assets.findclix.com/...",
    "type": "video",
    "status": "complete",
    "size": 2734894,
    "duration": 7,
    "created_at": "2026-07-07T15:09:50.978Z"
  }
}
```

### Interactive reference

***

## Upload media

```
POST /api/v1/media/upload
Content-Type: multipart/form-data
```

Upload a video or image file. The file is stored in R2 and automatically indexed for search.

### Form fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | File | **Yes** | Video or image file |
| `creator_ids` | string | No | Comma-separated creator IDs to associate |
| `category_ids` | string | No | Comma-separated category IDs to associate |

### Example

```bash
curl -X POST -H "Authorization: Bearer findclix_..." \
  -F "file=@video.mp4" \
  -F "creator_ids=abc-123,def-456" \
  "https://findclix.com/api/v1/media/upload"
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "987a0257-...",
    "url": "https://assets.findclix.com/..."
  }
}
```

::: info
After upload, the file is indexed asynchronously. The `status` field will transition from `pending` → `indexing` → `complete`. Poll the media item or use the search API to check readiness.
:::

### Interactive reference

***

## Delete media

```
DELETE /api/v1/media/:id
```

Permanently deletes a media item and its associated chunks from the database and R2 storage.

### Example

```bash
curl -X DELETE -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/media/53aebcdc-..."
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "53aebcdc-...",
    "deleted": true
  }
}
```

::: warning
This action is irreversible. The media file, its thumbnails, and all vector embeddings are permanently removed.
:::

### Interactive reference

---

---
url: /docs/agent-api/search.md
description: Text, image, and highlights (anomaly) search.
---

# Search

Search your media library using natural language or reference images.

## Text search

```
GET /api/v1/media/search?q=<query>
```

Finds clips by describing what you're looking for in plain English. Uses hybrid search (semantic vectors + keyword matching) to return the most relevant results.

### Query parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `q` | string | **required** | Natural language search query |
| `n` | int | `10` | Max results (max `50`) |
| `creator_id` | string | — | Filter to a specific creator's clips |
| `category_id` | string | — | Filter to a specific category |
| `dedupe` | float | — | Cosine similarity ceiling (0–1). `0.9` drops near-duplicate chunks of the same event. |
| `rerank` | bool | `false` | Re-rank top candidates with a vision model for precision. Falls back to embedding order on failure. |

| `rerank_candidates` | int | `5` | How many candidates to send to the vision model when `rerank=1` (max `10`) |

### Example

```bash
# Basic search
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/media/search?q=dancing+woman&n=3"

# With deduplication + vision-model precision reranking
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/media/search?q=dancing+woman&dedupe=0.9&rerank=1"
```

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "78975543-...",
      "filename": "preview_video.mp4",
      "score": 0.795,
      "start": 0,
      "end": 8.7,
      "url": "https://assets.findclix.com/...",
      "thumbnail": "https://assets.findclix.com/thumb__....jpg",
      "type": "video",
      "created_at": "2026-07-07T15:09:50.978Z"
    }
  ],
  "meta": {
    "query": "dancing woman"
  }
}
```

::: tip
The `score` field is a cosine similarity score (0–1). Higher means more relevant. Results below 0.2 are filtered out automatically. Pure keyword matches (no vector similarity) report `1.0` — a 100% text match, not a visual similarity.
:::

### Interactive reference

***

## Image search

```
POST /api/v1/media/search/image
```

Find visually similar clips by uploading a reference image. The image is embedded and compared against your vector index.

### Multipart form

```bash
curl -X POST -H "Authorization: Bearer findclix_..." \
  -F "file=@reference.jpg" \
  "https://findclix.com/api/v1/media/search/image"
```

### JSON body (URL or base64)

```bash
# By URL
curl -X POST -H "Authorization: Bearer findclix_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}' \
  "https://findclix.com/api/v1/media/search/image?n=5"

# By base64
curl -X POST -H "Authorization: Bearer findclix_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "/9j/4AAQ...base64string...", "filename": "screenshot.png"}' \
  "https://findclix.com/api/v1/media/search/image"
```

### Parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `n` | int | `10` | Max results (max `50`) |
| `dedupe` | float | — | Cosine similarity ceiling (0–1) |

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "...",
      "score": 0.82,
      "start": 0,
      "end": 10.5,
      "url": "https://assets.findclix.com/...",
      "filename": "beach_sunset.mp4"
    }
  ]
}
```

### Interactive reference

***

## Highlights (Surprise Me)

```
GET /api/v1/media/highlights
```

Rank the most **unusual** clips in your library — no query needed. Uses anomaly detection on the embedding space to surface surprising or standout moments.

### Query parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `count` | int | `10` | Max results (max `50`) |
| `method` | string | `knn` | Anomaly scoring method: `centroid` (cheapest), `knn` (robust), `lof` (best with distinct sub-clusters) |
| `neighbors` | int | `10` | k for `knn`/`lof` |
| `dedupe` | float | `0.9` | Drop results too similar to a higher-ranked pick |
| `creator_id` | string | — | Filter by creator |
| `category_id` | string | — | Filter by category |

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/media/highlights?count=5&method=knn&dedupe=0.9"
```

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "...",
      "filename": "unusual_clip.mp4",
      "score": 0.87,
      "start": 2.1,
      "end": 15.3,
      "url": "https://assets.findclix.com/..."
    }
  ]
}
```

::: info
The `score` here is an **anomaly score** (higher = more unusual), not a search similarity score. Don't compare it with text/image search scores.
:::

### Interactive reference

---

---
url: /docs/agent-api/creators.md
description: List, get, and create creators.
---

# Creators

Manage the people or entities that produce content in your workspace.

## List creators

```
GET /api/v1/creators
```

Returns all creators in your workspace.

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/creators"
```

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "abc-123",
      "name": "John Doe",
      "avatar_url": "https://example.com/avatar.jpg",
      "profile_url": "https://instagram.com/johndoe",
      "created_at": "2026-01-01T00:00:00.000Z",
      "media_count": 12,
      "category_count": 2
    }
  ]
}
```

### Interactive reference

***

## Get creator

```
GET /api/v1/creators/:id
```

Returns a single creator by ID.

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/creators/abc-123"
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "abc-123",
    "name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "profile_url": "https://instagram.com/johndoe",
    "created_at": "2026-01-01T00:00:00.000Z",
      "media_count": 12,
      "category_count": 2
  }
}
```

### Interactive reference

***

## Create creator

```
POST /api/v1/creators
```

Creates a new creator. If a `profile_url` is provided (Instagram, YouTube, etc.), the avatar is fetched automatically.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | **Yes** | Creator's display name |
| `profile_url` | string | No | Social profile URL (used to fetch avatar) |

### Example

```bash
curl -X POST -H "Authorization: Bearer findclix_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "profile_url": "https://instagram.com/janesmith"}' \
  "https://findclix.com/api/v1/creators"
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "c1234567-89ab-cdef-0123-456789abcdef",
    "name": "Jane Smith",
    "avatar_url": "https://example.com/avatar.jpg",
    "profile_url": "https://instagram.com/janesmith",
    "created_at": "2026-09-09T12:00:00.000Z",
    "media_count": 0,
    "category_count": 0
  }
}
```

::: warning
Creator creation is subject to your plan's limits. The Free plan allows 1 creator — upgrade under Settings → Billing to add more.
:::

### Interactive reference

---

---
url: /docs/agent-api/categories.md
description: List and get categories.
---

# Categories

Categories help organize media by brand, topic, or type.

## List categories

```
GET /api/v1/categories
```

Returns all categories in your workspace.

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/categories"
```

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "xyz-789",
      "name": "Nike",
      "created_at": "2026-01-01T00:00:00.000Z",
      "media_count": 5,
      "logo_url": null
    }
  ]
}
```

### Interactive reference

***

## Get category

```
GET /api/v1/categories/:id
```

Returns a single category by ID.

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/categories/xyz-789"
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "xyz-789",
    "name": "Nike",
    "created_at": "2026-01-01T00:00:00.000Z",
      "media_count": 5,
      "logo_url": null
  }
}
```

### Interactive reference

---

---
url: /docs/agent-api/workspace.md
description: Workspace info, plan, and usage quotas.
---

# Workspace

Get information about your workspace, including plan details and usage quotas.

## Get workspace info

```
GET /api/v1/workspace
```

Returns your current workspace's details, plan, and storage usage.

### Example

```bash
curl -H "Authorization: Bearer findclix_..." \
  "https://findclix.com/api/v1/workspace"
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "org_abc123",
    "name": "My Team",
    "plan": {
      "id": "pro",
      "name": "Pro",
      "storage_limit_bytes": 53687091200,
      "max_creators": 0,
      "max_members": 5
    },
    "usage": {
      "storage_used_bytes": 1073741824,
      "storage_remaining_bytes": 52613349376,
      "storage_percent_used": 2,
      "media_count": 42,
      "creator_count": 3,
      "member_count": 2
    },
    "created_at": "2026-01-01T00:00:00.000Z"
  }
}
```

::: info
`max_creators` and `max_members` are `0` for unlimited (Pro, Agency, Enterprise). The Free plan allows 1 creator and 1 member. `storage_remaining_bytes` is `null` when storage is unlimited.
:::

### Interactive reference

---

---
url: /docs/agent-api/errors.md
description: Error codes and handling patterns.
---

# Errors

All error responses follow a consistent shape:

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}
```

Always check the `success` field before accessing `data`.

## Error codes

These are the only error codes the API returns:

| Status | Code | When |
|--------|------|------|
| `400` | `BAD_REQUEST` | Missing or invalid parameters — e.g. no `q` on search, no `file` on upload, empty creator `name`, or storage quota exceeded |
| `401` | `UNAUTHORIZED` | Missing, malformed, or unknown API key |
| `404` | `NOT_FOUND` | Resource doesn't exist in your workspace |
| `500` | `INTERNAL_SERVER_ERROR` | Unexpected server failure — safe to retry |

## Handling errors

A robust integration should:

1. Check `response.success === true` before using `response.data`
2. Handle `401` by verifying your API key (Settings → API Keys)
3. Fix the request on `400`/`404` — retrying won't help
4. Retry `500` errors with backoff, then contact support if they persist

### Example error handling

```typescript
const res = await fetch('https://findclix.com/api/v1/media/search?q=hello', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
})

const json = await res.json()

if (!json.success) {
  console.error(`API error: ${json.error.code} — ${json.error.message}`)
  return
}

// Use json.data safely
for (const clip of json.data) {
  console.log(clip.filename, clip.score)
}
```