Media
Search
Requests, objects, and responses.
expression accepts expressions; semantic and search accept natural language. Semantic search returns ready assets only.
Expression search
POST /media/v1/libraries/{library_id}/search/expression
| Parameter | Location | Type | Description |
|---|---|---|---|
| library_id | path | string | Library ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| expression | string | no | Structured query expression; an empty expression returns every asset |
| sort_by | object[] | no | Sort fields and directions |
| max_results | integer | no | Up to 500; Search defaults to 100, Admin to 10 |
| next_cursor | string | no | Next-page cursor; null or absent at the end |
| with_field | tags / context[] | no | Include tags or context |
| aggregate | AggregateField[] | no | Aggregation fields |
Returns: ExpressionSearchResult.
Response
HTTP 200
Successful response.
application/json
| Name | Type | Description |
|---|---|---|
| total_count | number | Number of matching assets across pages; a lower bound when total_count_exact is false. |
| time | number | Elapsed search time in whole milliseconds. |
| next_cursor | string | Continuation token for the next page; omitted when no further page is available. |
| resources | array<object> | Assets in this page, ordered by sort_by; tags and context follow with_field. |
| resources[].asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| resources[].public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| resources[].display_name | string | Human-readable asset name, independent of its delivery identifier. |
| resources[].asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| resources[].resource_type | string | Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection. |
| resources[].type | string | Public asset delivery mode; upload is the only supported value. |
| resources[].format | string | Detected file format used as the delivery URL extension. |
| resources[].version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| resources[].version_id | string | Identifier for this asset version, regenerated on overwrite. |
| resources[].bytes | number | Size of the original source content, in bytes. |
| resources[].etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| resources[].width | number | Source image or video width in pixels, when known. |
| resources[].height | number | Source image or video height in pixels, when known. |
| resources[].duration | number | Source audio or video duration in seconds, when known. |
| resources[].pages | number | |
| resources[].is_audio | boolean | True for audio-only media, which uses resource_type video. |
| resources[].original_filename | string | Original or overridden source filename with its final extension removed. |
| resources[].tags | array<string> | Labels attached to the asset. |
| resources[].context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| resources[].created_at | string | Time this asset identity was created, in UTC. |
| resources[].url | string | URL for retrieving this version of the asset’s original content. |
| resources[].secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| resources[].placeholder | boolean | False because this response represents stored source content. |
| resources[].existing | boolean | |
| resources[].processing | object | Progress of understanding and embedding tasks for the asset. |
| resources[].library_id | string | Identifier of the library containing this asset. |
| resources[].sha256 | string | SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters. |
| resources[].status | string | Resource status; active identifies an asset that has not been deleted. |
| resources[].semantic | string | Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending. |
| resources[].preview | object | Generated video previews, present once preview generation succeeds. |
| aggregations | object | Requested facet counts, keyed by facet name and then by field value. |
| total_count_exact | boolean | Whether total_count covers all matches; false indicates a bounded partial count. |
| aggregations_exact | boolean | Whether the returned facet counts cover all matching assets. |
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/search/expression" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"expression":"tags:docs"}'HTTP 200
{
"total_count": 2,
"total_count_exact": true,
"time": 0,
"resources": [
{
"asset_id": "9dfa312ef9bc4b00816339b598b1152c",
"public_id": "walk-lib-r1-MDP-1791733789929-tagged",
"display_name": "walk-lib-r1-MDP-1791733789929-tagged",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733815,
"version_id": "26cb8171caa5431b8373ad417fd71e32",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"processing": {
"state": "processing",
"kinds": {
"embedding": "pending",
"visual": "running",
"tagging": "running"
},
"updated_at": "2026-10-11T15:50:17.571Z"
},
"created_at": "2026-10-11T15:50:15.996Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
"placeholder": false,
"library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
"sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
"status": "active",
"semantic": "pending"
},
{
"asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
"public_id": "walk-lib-r1-MDP-1791733789929-plain",
"display_name": "walk-lib-r1-MDP-1791733789929-plain",
"asset_folder": "",
"resource_type": "image",
"type": "upload",
"format": "png",
"version": 1791733810,
"version_id": "fdf3c8cd40c2424d86e8397425a69857",
"bytes": 70,
"etag": "b357a19c87624c7c4d131aeeb4ae677f",
"width": 1,
"height": 1,
"original_filename": "file",
"created_at": "2026-10-11T15:50:10.842Z",
"url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
"placeholder": false,
"library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
"sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
"status": "active",
"processing": {
"state": "processing",
"kinds": {
"embedding": "pending",
"visual": "running"
},
"updated_at": "2026-10-11T15:50:17.571Z"
},
"semantic": "pending"
}
]
}Visual search
POST /media/v1/libraries/{library_id}/search/visual
| Parameter | Location | Type | Description |
|---|---|---|---|
| library_id | path | string | Library ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| asset_id | AssetId | no | Asset ID |
| image | object | no | Query image object: base64 data and image MIME type |
| top_k | integer | no | Maximum hits, 1–50 |
| filter | string | no | Expression filter |
Returns: SemanticSearchResult.
Available when library search.image is true; unsupported libraries return LIBRARY_INVALID_STATE. JPEG, PNG, WebP and GIF are accepted, with a maximum decoded size of 10 MiB. Each asset returns its highest-scoring match; videos identify the best frame. qwen3-vl-embedding uses 0.35 for image similarity. Measurements on 2026-10-10: variants of the same image scored 0.82–0.96, similar scenes 0.38–0.66, and unrelated images at most 0.34.
Provide exactly one of asset_id or image: { data, mime }. Asset queries reuse existing image understanding and exclude the source asset; videos use the first frame. Incomplete understanding returns LIBRARY_INVALID_STATE. Uploaded image data is base64. top_k defaults to 20 and accepts 1–50; filter uses the semantic-search expression syntax. Only image similarity is searched. The response shares semantic search’s hits, embedding_producer and not_ready_excluded fields. matches.kind is image; snippet uses the latest caption or asset name. Deleted assets, old versions and replaced understanding are excluded.
Response
HTTP 200
Successful response.
application/json
| Name | Type | Description |
|---|---|---|
| hits | array<object> | Ranked assets up to top_k; an empty array means no eligible matches were found. |
| hits[].asset | object | Asset matched by the query. |
| hits[].score | number | Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first. |
| hits[].semantic_score | number | null | Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode. |
| hits[].matches | array<object> | Supporting content or metadata matches contributing to this asset’s hit. |
| embedding_producer | string | Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query. |
| not_ready_excluded | number | Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library. |
Semantic search
POST /media/v1/libraries/{library_id}/search/semantic
| Parameter | Location | Type | Description |
|---|---|---|---|
| library_id | path | string | Library ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| query | string | yes | Describe what you want to find |
| filter | string | no | Expression filter |
| top_k | integer | no | Maximum hits, 1–50 |
| mode | hybrid / semantic | no | hybrid combines keywords and semantics; semantic uses semantics only |
Returns: SemanticSearchResult.
With bge-m3, vector candidates must have cosine similarity ≥ 0.55 before keyword fusion, including newly understood content. Calibration on seven demo assets on 2026-10-09 found relevant results at approximately 0.58 or higher (0.581–0.729), irrelevant results at most 0.523, and wholly unrelated queries at most 0.478. qwen3-vl-embedding text queries use 0.40 against text content (captions, transcripts) and 0.25 against image content. Other models remain uncalibrated and unfiltered. Keyword matches are unaffected. Queries unrelated to the library return an empty list; mode=semantic returns only results meeting the vector threshold.
Response
HTTP 200
Successful response.
application/json
| Name | Type | Description |
|---|---|---|
| hits | array<object> | Ranked assets up to top_k; an empty array means no eligible matches were found. |
| hits[].asset | object | Asset matched by the query. |
| hits[].score | number | Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first. |
| hits[].semantic_score | number | null | Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode. |
| hits[].matches | array<object> | Supporting content or metadata matches contributing to this asset’s hit. |
| embedding_producer | string | Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query. |
| not_ready_excluded | number | Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library. |
Semantic search alias
POST /media/v1/libraries/{library_id}/search
| Parameter | Location | Type | Description |
|---|---|---|---|
| library_id | path | string | Library ID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| query | string | yes | Describe what you want to find |
| filter | string | no | Expression filter |
| top_k | integer | no | Maximum hits, 1–50 |
| mode | hybrid / semantic | no | hybrid combines keywords and semantics; semantic uses semantics only |
Returns: SemanticSearchResult.
Response
HTTP 200
Successful response.
application/json
| Name | Type | Description |
|---|---|---|
| hits | array<object> | Ranked assets up to top_k; an empty array means no eligible matches were found. |
| hits[].asset | object | Asset matched by the query. |
| hits[].score | number | Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first. |
| hits[].semantic_score | number | null | Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode. |
| hits[].matches | array<object> | Supporting content or metadata matches contributing to this asset’s hit. |
| embedding_producer | string | Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query. |
| not_ready_excluded | number | Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library. |
ExpressionSearchResult
| Field | Type | Required | Description |
|---|---|---|---|
| total_count | number | yes | Matching count |
| time | number | yes | Search time in whole milliseconds, measured by the service |
| next_cursor | string | no | Next-page cursor; null or absent at the end |
| resources | SearchAsset[] | yes | Assets in this page |
| aggregations | object | no | Counts by requested fields |
| total_count_exact | boolean | no | Whether the count is exact |
| aggregations_exact | boolean | no | Whether aggregations are exact |
SemanticSearchResult
| Field | Type | Required | Description |
|---|---|---|---|
| hits | SemanticHit[] | yes | Search hits |
| embedding_producer | string | yes | Semantic understanding producer |
| not_ready_excluded | number | yes | Assets excluded because they are not ready |
SearchAsset
| Field | Type | Required | Description |
|---|---|---|---|
| asset_id | AssetId | yes | Asset ID |
| public_id | string | yes | Asset name in delivery URLs; may contain path segments |
| display_name | string | yes | Display name |
| asset_folder | string | yes | Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root |
| resource_type | ResourceType | yes | image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400 |
| type | DeliveryType | yes | Resource or event type |
| format | string | yes | File format |
| version | number | yes | Delivery version |
| version_id | string | yes | Version identifier |
| bytes | number | yes | File size in bytes |
| etag | string | yes | File checksum |
| width | number | no | Width in pixels |
| height | number | no | Height in pixels |
| duration | number | no | Duration in seconds |
| pages | number | no | Document pages |
| is_audio | boolean | no | Whether this is audio |
| original_filename | string | no | Original file name |
| tags | string[] | no | Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list |
| context | object | no | Custom text key/value pairs; PATCH replaces the whole map, {} clears it |
| created_at | IsoTimestamp | yes | Creation time |
| url | string | yes | Original-file URL |
| secure_url | string | yes | HTTPS delivery URL |
| placeholder | false | yes | Always false |
| existing | boolean | no | Whether an existing asset was returned without overwrite |
| processing | Processing | yes | Overall and per-kind processing states |
| library_id | LibraryId | yes | Library ID |
| sha256 | string | yes | Content checksum |
| status | "active" | yes | Resource status |
| semantic | "pending" / "ready" / "unavailable" | yes | Searchable semantically when ready |
| preview | object | no | Preview poster and storyboard |
SemanticHit
| Field | Type | Required | Description |
|---|---|---|---|
| asset | Asset | yes | Matching asset |
| score | number | yes | Relevance score |
| semantic_score | number / null | no | — |
| matches | SemanticMatch[] | yes | Matched content and segment times |
SemanticMatch
| Field | Type | Required | Description |
|---|---|---|---|
| kind | UnderstandingKind / "metadata" / "image" | yes | Understanding or processing kind; filters the understanding list |
| understanding_id | UnderstandingId / null | yes | Understanding ID; null for metadata matches |
| segment | Segment / null | yes | Start/end milliseconds; null for whole assets |
| snippet | string | yes | Matching text snippet |