Search files | Uploadcare docs

Search files by filename, metadata, MIME type, UUID, or tags using full-text or exact matching, with optional filtering by size, upload date, and file type.

Use query for a quick search across all full-text fields at once. Use phrase to search specific fields. Use exact, datetime_uploaded, size, is_image, or tags for structured filtering. At least one condition is required.

How conditions combine: all top-level conditions are combined with AND — a file must satisfy every condition you pass. There is no top-level OR and no general NOT. OR is available only within a single exact field (multiple values), within query (across fields), and in tags.any; NOT is available only via tags.none and is_image: false.

A field cannot appear in both phrase and exact in the same request.

Full-text matching (query, phrase) is substring-aware: a term matches anywhere inside a word. Each value must be at least 4 characters; for short or precise values use exact.

Set fuzziness: true to enable typo-tolerant search. Disabled by default. Note: Enabling fuzziness significantly increases query latency.

Note: Newly uploaded files are indexed asynchronously and may not appear in search results immediately.

See the file search guide for worked examples.

Search files by filename, metadata, MIME type, UUID, or tags using full-text or exact matching, with optional filtering by size, upload date, and file type. Use `query` for a quick search across all full-text fields at once. Use `phrase` to search specific fields. Use `exact`, `datetime_uploaded`, `size`, `is_image`, or `tags` for structured filtering. At least one condition is required. **How conditions combine:** all top-level conditions are combined with AND — a file must satisfy every condition you pass. There is no top-level OR and no general NOT. OR is available only within a single `exact` field (multiple values), within `query` (across fields), and in `tags.any`; NOT is available only via `tags.none` and `is_image: false`. A field cannot appear in both `phrase` and `exact` in the same request. Full-text matching (`query`, `phrase`) is substring-aware: a term matches anywhere inside a word. Each value must be at least 4 characters; for short or precise values use `exact`. Set `fuzziness: true` to enable typo-tolerant search. Disabled by default. **Note:** Enabling fuzziness significantly increases query latency. **Note:** Newly uploaded files are indexed asynchronously and may not appear in search results immediately. See the [file search guide](https://uploadcare.com/docs/file-search/) for worked examples.

Authentication

Authorizationstring

Every request made to https://api.uploadcare.com/ MUST be signed. HTTPS SHOULD be used with any authorization scheme.

Requests MUST contain the Authorization header defining auth-scheme and auth-param: Authorization: auth-scheme auth-param.

Every request MUST contain the Accept header identifying the REST API version: Accept: application/vnd.uploadcare-v0.7+json.

There are two available authorization schemes:

For production: Uploadcare, a scheme where a signature, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend.
For quick tests: Uploadcare.Simple, a simple scheme where your Secret API Key MUST be specified in every request’s auth-param.

Every request made to `https://api.uploadcare.com/` MUST be signed. HTTPS SHOULD be used with any authorization scheme. Requests MUST contain the `Authorization` header defining `auth-scheme` and `auth-param`: `Authorization: auth-scheme auth-param`. Every request MUST contain the `Accept` header identifying the REST API version: `Accept: application/vnd.uploadcare-v0.7+json`. There are two available authorization schemes: * For production: `Uploadcare`, a scheme where a `signature`, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend. * For quick tests: `Uploadcare.Simple`, a simple scheme where your [Secret API Key](https://app.uploadcare.com/projects/-/api-keys/) MUST be specified in every request's `auth-param`.

Query parameters

limitintegerOptional1-100Defaults to 20

Number of results per page. Range: 1–100. Default: 20.

offsetintegerOptional>=0Defaults to 0

Pagination offset. Default: 0. The sum of offset and limit must not exceed 1000.

includeenumOptional

Include additional fields in each result object. The only supported value is appdata, which embeds application data (e.g. moderation or virus-scan results).

Allowed values:

Request

At least one of the following fields must be present: query, phrase, exact, datetime_uploaded, size, is_image.

querystringOptional>=4 characters

Quick full-text search across all searchable fields (original_filename, metadata, detected_mime_type); fields are OR-ed. Substring-aware (matches anywhere inside a word). The value is also matched against the file UUID with a relevance boost, so pasting a UUID returns that file at the top. Minimum 4 characters.

phraseobjectOptional

Full-text search scoped to specific fields; multiple fields are combined with AND. Substring-aware (matches anywhere inside a word). Each value must be ≥ 4 characters. Cannot reference the same field as exact. metadata searches across all metadata keys and values at once — to match a specific key, use exact with metadata[key].

Full-text search scoped to specific fields; multiple fields are combined with AND. Substring-aware (matches anywhere inside a word). Each value must be ≥ 4 characters. Cannot reference the same field as `exact`. `metadata` searches across all metadata keys and values at once — to match a specific key, use `exact` with `metadata[key]`.

exactobjectOptional

Exact value matching. Each key takes a non-empty array of values. Cannot reference the same field as phrase. Use metadata[key] syntax to match metadata fields, e.g. "metadata[camera]": ["Canon"].

datetime_uploadedanyOptional

Filter by upload date (ISO 8601). Supported operators: gt, gte, lt, lte. At least one operator is required; combine two to form a range.

sizeanyOptional

Filter by file size in bytes. Supported operators: gt, gte, lt, lte. At least one operator is required; combine two to form a range.

is_imagebooleanOptional

true to return images only; false to exclude images.

fuzzinessbooleanOptionalDefaults to false

Enable typo-tolerant matching for query and phrase searches (does not affect exact). When true, searches tolerate small spelling differences; the allowed edit distance scales with term length (roughly 1 edit for 3–5 characters, 2 for longer). Disabled by default. Note: Enabling fuzziness significantly increases query latency.

Enable typo-tolerant matching for `query` and `phrase` searches (does not affect `exact`). When `true`, searches tolerate small spelling differences; the allowed edit distance scales with term length (roughly 1 edit for 3–5 characters, 2 for longer). Disabled by default. **Note:** Enabling fuzziness significantly increases query latency.

tagsobjectOptional

Filter files by tags. All specified keys are combined with AND logic. Tag values are normalized (lowercased, whitespace-stripped) before matching.

sortlist of enumsOptional

Sort order. Array of 1–4 unique sort keys. Prefix with - for descending order. If omitted, results are ordered by relevance. For filter-only requests (no query or phrase) there is no relevance to rank by, so pass an explicit sort to get a deterministic order.

Response

Search results.

nextstring or nullformat: "uri"

Next page URL.

previousstring or nullformat: "uri"

Previous page URL.

totalinteger>=0

Total number of matching files.

per_pageinteger

Number of results per page.

resultslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

406

Not Acceptable Error

429

Too Many Requests Error