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

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

{
  "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.

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 for every code and how to handle them.

What to read next

• Authentication — keys, Bearer usage, OpenAPI spec
• Media — list, get, upload, delete
• Search — text, image, and highlights
• Errors — error codes and handling patterns