---
title: "POST /v1/search/assets — Search the archival media catalog."
method: POST
path: "/v1/search/assets"
tags: ["Search"]
---

# POST /v1/search/assets — Search the archival media catalog.

`POST /v1/search/assets`

## Request

- Base URL: `https://api.stockfilm.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stockfilm.com/v1/search/assets`
- Auth: API key in header `Authorization`

## Request body

- SearchAssetsRequest: Request body for POST /v1/search/assets.
  - `cursor` string, nullable: Cursor for pagination (opaque, base64-encoded offset).
  - `filters` SearchAssetsFilters: Filters within the search request.
    - `archival_classes` string[], nullable: Filter by archival class tags.
    - `categories` string[], nullable: Filter by category tags.
    - `color_modes` string[], nullable: Filter by color mode values: `color`, `black_and_white`.
    - `commercial_eligible` boolean, nullable: Filter by commercial eligibility.
    - `decades` string[], nullable: Filter by decade labels (e.g. `["1960s"]`).
    - `editorial_exclusion` boolean, nullable: Exclude editorial-only assets when true.
    - `locations` string[], nullable: Filter by location labels/tags.
    - `machine_ready` boolean: Only return machine-ready assets (default true).
    - `max_duration_ms` integer, nullable: Maximum duration in milliseconds.
    - `max_height` integer, nullable: Maximum height in pixels.
    - `max_width` integer, nullable: Maximum width in pixels.
    - `media_types` string[], nullable: Filter by media types (e.g. `["video", "image"]`).
    - `min_duration_ms` integer, nullable: Minimum duration in milliseconds.
    - `min_height` integer, nullable: Minimum height in pixels.
    - `min_width` integer, nullable: Minimum width in pixels.
    - `price_ceiling_cents` integer, nullable: Optional price ceiling under filters for PRD parity.
    - `rights_classes` string[], nullable: Filter by rights classes (allowed use classes).
    - `rights_cleared` boolean: Only return assets with cleared rights (default true).
    - `subjects` string[], nullable: Filter by subject tags.
    - `tags` string[], nullable: Require ALL specified tags.
    - `years` integer[], nullable: Filter by exact year values (e.g. `[1963, 1969]`).
  - `image_base64` string, nullable: Optional base64-encoded image (or data URI) for live visual search mode.
  - `image_mime_type` string, nullable: Optional MIME type for `image_base64` payload (e.g. `image/jpeg`).
  - `limit` integer, nullable: Maximum results per page (default 20, max 100).
  - `price_ceiling_cents` integer, nullable: Maximum price ceiling in cents. Assets with estimated price above this value are excluded from results.
  - `query` string, nullable: Free-text query for full-text search.

## Response `200`

Search results

- SearchAssetsResponse: Response for POST /v1/search/assets.
  - `next_cursor` string, nullable
  - `ranking` SearchRankingInfo, required: Ranking metadata in the response.
    - `method` string, required
    - `total_results` integer, required
  - `results` SearchAssetResult[], required
    - `asset_id` string, uuid, required
    - `created_at` string, date-time, required
    - `description` string, required
    - `duration_ms` integer, nullable
    - `estimated_price_cents` integer, nullable
    - `external_clip_id` string, nullable
    - `has_preview` boolean, required
    - `height` integer, nullable
    - `machine_ready` boolean, required
    - `manual_review_required` boolean, required
    - `media_type` string, required
    - `original_filename` string, nullable
    - `rights_summary` RightsSummary, required: Summary of rights status for an asset in search results.
      - `cleared` boolean, required: Whether at least one cleared rights record exists.
    - `sale_mode` string, nullable: Mirrored `licensing_profile.sale_mode` (`direct_rf`, `editorial_only`, ...). Check this before quoting: `editorial_only` clips refuse commercial/broadcast scopes.
    - `score` number, double, required
    - `source_href` string, nullable
    - `tags` string[], required
    - `title` string, required
    - `width` integer, nullable

## Other responses

- `400`: Invalid request

---

[API](https://skmtc.dev/stockfilm/apis/stockfilm-api.md) · [All operations](https://skmtc.dev/stockfilm/apis/stockfilm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stockfilm/apis/stockfilm-api/revisions/ef244025c706?raw)