Skip to navigation
REST APIFile

Search files

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.

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.

Headers

AcceptstringRequired
Version header.

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, or tags.

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].

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.

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 nullOptionalformat: "uri"
Next page URL.
previousstring or nullOptionalformat: "uri"
Previous page URL.
totalintegerOptional>=0
Total number of matching files.
per_pageintegerOptional
Number of results per page.
resultslist of objectsOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
429
Too Many Requests Error