Search

Guide →

Only the following expression subset is supported. Unsupported syntax or fields return HTTP 400 INVALID_EXPRESSION; compatible errors contain only the message. Tags and context are omitted by default; request them with with_field.

Syntax	Meaning
AND / OR / NOT / - / ( )	Boolean combinations; adjacent terms imply AND
field:value / field=value	Field match
bytes > 1000 / width >= 160	Numeric comparisons; also height and duration
created_at >= 2026-01-01 / uploaded_at > 7d	Dates or relative time, d/w/m/y
tags:docs / context.alt:"sample image"	Tags and custom text
public_id:docs*	Trailing wildcard only
"sample image"	Phrase
sunset	Bare word: full-text match over public_id, display_name, tags, context, and understood captions, image text, and transcripts; case-insensitive
~ / ^ / [a TO z] / prefix / ab	Unsupported; returns 400

Field names are case-insensitive (RESOURCE_TYPE:image equals resource_type:image). Values of resource_type, type, and format are case-insensitive; values of tags, context, and other fields are case-sensitive. An empty expression returns every asset; an expression that cannot be parsed returns 400 INVALID_EXPRESSION.

Queryable fields: asset_id, resource_type, type, format, public_id, asset_folder, display_name, tags, bytes, width, height, duration, created_at, uploaded_at, context.<key>.

Sort fields: created_at, public_id, display_name, bytes, uploaded_at.

Aggregate fields: resource_type, format, asset_folder, processing_state. Guide →

Base URL and authentication

Visual search

GET /cloudinary/v1_1/{library_id}/resources/visual_search

Parameter	Location	Type	Description
library_id	path	string	Library ID
image_asset_id	query	string	Asset ID in this library
image_url	query	string	Only delivery URLs from this library; external URLs are not fetched
text	query	string	Natural-language query using semantic search
max_results	query	integer	Up to 500; Search defaults to 100, Admin to 10
filter	query	string	Expression filter

Returns: VisualResources.

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 image_asset_id, multipart image_file, image_url, or text. Text uses semantic-only search; the response is { "resources": [...] }. image_url accepts only this library’s delivery URLs. External URLs are never fetched and return 400 with “不支持抓取外部 URL”.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
resources	array<object>
resources[].asset_id	string
resources[].public_id	string
resources[].display_name	string
resources[].asset_folder	string
resources[].resource_type	string
resources[].type	string
resources[].format	string
resources[].version	number
resources[].version_id	string
resources[].bytes	number
resources[].etag	string
resources[].width	number
resources[].height	number
resources[].duration	number
resources[].pages	number
resources[].is_audio	boolean
resources[].original_filename	string
resources[].tags	array<string>
resources[].context	object
resources[].created_at	string
resources[].url	string
resources[].secure_url	string
resources[].placeholder	boolean
resources[].existing	boolean
resources[].processing	object

Visual search

POST /cloudinary/v1_1/{library_id}/resources/visual_search

Parameter	Location	Type	Description
library_id	path	string	Library ID

Request body

Field	Type	Required	Description
image_asset_id	string	no	Asset ID in this library
image_url	string	no	Only delivery URLs from this library; external URLs are not fetched
image_file	string	no	JPEG, PNG, WebP or GIF file, at most 10 MiB
text	string	no	Natural-language query using semantic search
max_results	integer	no	Up to 500; Search defaults to 100, Admin to 10
filter	string	no	Expression filter

Returns: VisualResources.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
resources	array<object>
resources[].asset_id	string
resources[].public_id	string
resources[].display_name	string
resources[].asset_folder	string
resources[].resource_type	string
resources[].type	string
resources[].format	string
resources[].version	number
resources[].version_id	string
resources[].bytes	number
resources[].etag	string
resources[].width	number
resources[].height	number
resources[].duration	number
resources[].pages	number
resources[].is_audio	boolean
resources[].original_filename	string
resources[].tags	array<string>
resources[].context	object
resources[].created_at	string
resources[].url	string
resources[].secure_url	string
resources[].placeholder	boolean
resources[].existing	boolean
resources[].processing	object

Search

GET /cloudinary/v1_1/{library_id}/resources/search

Parameter	Location	Type	Description
library_id	path	string	Library ID
expression	query	string	Structured query expression; an empty expression returns every asset
sort_by	query	string	Sort fields and directions
max_results	query	integer	Up to 500; Search defaults to 100, Admin to 10
next_cursor	query	string	Next-page cursor; null or absent at the end
with_field	query	string[]	Include tags or context
aggregate	query	string[]	Aggregation fields

Returns: CompatExpressionSearchResult.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
total_count	number
time	number
next_cursor	string
resources	array<object>
resources[].asset_id	string
resources[].public_id	string
resources[].display_name	string
resources[].asset_folder	string
resources[].resource_type	string
resources[].type	string
resources[].format	string
resources[].version	number
resources[].version_id	string
resources[].bytes	number
resources[].etag	string
resources[].width	number
resources[].height	number
resources[].duration	number
resources[].pages	number
resources[].is_audio	boolean
resources[].original_filename	string
resources[].tags	array<string>
resources[].context	object
resources[].created_at	string
resources[].url	string
resources[].secure_url	string
resources[].placeholder	boolean
resources[].existing	boolean
resources[].processing	object
aggregations	object

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search?expression=tags%3Adocs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "total_count": 1,
  "time": 0,
  "resources": [
    {
      "asset_id": "9339cdae93804c0c8c65d5189ef1f646",
      "public_id": "docs/pixel",
      "display_name": "Sample image",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538418,
      "version_id": "35848c1529994e338e7aa634a1c13d9c",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:38.899Z",
      "url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
      "placeholder": false
    }
  ]
}

Search

POST /cloudinary/v1_1/{library_id}/resources/search

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: CompatExpressionSearchResult.

Response

HTTP 200

Successful response.

application/json

Name	Type	Description
total_count	number
time	number
next_cursor	string
resources	array<object>
resources[].asset_id	string
resources[].public_id	string
resources[].display_name	string
resources[].asset_folder	string
resources[].resource_type	string
resources[].type	string
resources[].format	string
resources[].version	number
resources[].version_id	string
resources[].bytes	number
resources[].etag	string
resources[].width	number
resources[].height	number
resources[].duration	number
resources[].pages	number
resources[].is_audio	boolean
resources[].original_filename	string
resources[].tags	array<string>
resources[].context	object
resources[].created_at	string
resources[].url	string
resources[].secure_url	string
resources[].placeholder	boolean
resources[].existing	boolean
resources[].processing	object
aggregations	object

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"expression":"tags:docs"}'

HTTP 200

{
  "total_count": 2,
  "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": "running",
          "visual": "failed",
          "tagging": "failed"
        },
        "updated_at": "2026-10-11T15:50:21.512Z"
      },
      "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
    },
    {
      "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
    }
  ]
}

VisualResources

Field	Type	Required	Description
resources	CloudinaryResource[]	yes	Assets in this page

CompatExpressionSearchResult

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	SearchResource[]	yes	Assets in this page
aggregations	object	no	Counts by requested fields

SearchResource

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	no	Overall and per-kind processing states

Search

On this page