Skip to main content
copyparty provides powerful search capabilities including metadata search, tag-based queries, and content-hash lookups. Search for files by name, path, or metadata: 
curl -X POST \
  -H "Content-Type: application/json" \
  -H "PW: your-password" \
  -d '{"q": "vacation photos"}' \
  http://server:3923/ | jq
​
q
string
required
Search query string. Supports multiple search operators and filters
​
n
integer
default:"200"
Maximum number of results to return (server default configurable with --srch-hits)

​
Search Syntax

​
Text Search

Basic text matching: 
{"q": "vacation"}
Matches files/paths containing “vacation”.

​
Multiple Terms (AND)

{"q": "vacation beach 2024"}
Matches files containing all three terms. 
{"q": "\"family vacation\""}
Matches exact phrase “family vacation”. 
{"q": "*.jpg"}
Matches all JPEG files.

​
Search Filters

​
Size Filters

Filter by file size: 
{"q": "size:>10M"}
​
size
string
Size filter operators:
  • size:>10M - Larger than 10 MiB
  • size:<1G - Smaller than 1 GiB
  • size:=1024 - Exactly 1024 bytes
  • Units: K (KiB), M (MiB), G (GiB), T (TiB)

​
Date Filters

Filter by modification date: 
{"q": "date:>2024-01-01"}
​
date
string
Date filter operators:
  • date:>2024-01-01 - Modified after Jan 1, 2024
  • date:<2024-12-31 - Modified before Dec 31, 2024
  • date:=2024-03-03 - Modified on Mar 3, 2024
  • Format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS

​
Path Filters

Search in specific paths: 
{"q": "path:/photos vacation"}
​
path
string
Restrict search to specific path prefix

​
Extension Filters

{"q": "ext:jpg,png,gif beach"}
​
ext
string
Filter by file extension (comma-separated list)
Search by metadata tags (requires indexing with -e2ts): 
{"q": "artist:Beethoven"}

{"q": "album:\"Symphony No. 9\""}

{"q": "title:Moonlight"}

{"q": "genre:Classical"}

{"q": "year:2020"}

{"q": "rate:>320"}
Bitrate in kbps. 
{"q": "dur:>180"}
Duration in seconds.

​
Combined Queries

Combine multiple filters: 
{
  "q": "artist:Mozart genre:Classical year:>1780 ext:flac size:>10M"
}

​
Content Hash Search

Search for files by up2k content hash: 
curl -X POST \
  -H "Content-Type: application/json" \
  -H "PW: your-password" \
  -d '{
    "srch": true,
    "hash": [
      "base64-encoded-chunk-hash-1",
      "base64-encoded-chunk-hash-2"
    ]
  }' \
  http://server:3923/ | jq
​
srch
boolean
required
Enable hash-based search mode
​
hash
array
required
Array of up2k chunk hashes (URL-safe base64 encoded SHA-512)
Returns files that match any of the provided hashes.

​
Search Response

​
Successful Response

{
  "hits": [
    {
      "rp": "/music/album/01-track.flac",
      "fn": "01-track.flac",
      "sz": 45678901,
      "mt": 1234567890,
      "tags": {
        "artist": "Example Artist",
        "album": "Example Album",
        "title": "Track 1",
        "track": "1",
        "year": "2024",
        "genre": "Electronic"
      }
    }
  ],
  "tag_order": ["artist", "album", "title", "track", "year", "genre"],
  "trunc": false
}
​
hits
array
Array of matching files
​
hits[].rp
string
Relative path from volume root
​
hits[].fn
string
Filename
​
hits[].sz
integer
File size in bytes
​
hits[].mt
integer
Modification timestamp (Unix epoch)
​
hits[].tags
object
Metadata tags (if indexed with -e2ts)
​
tag_order
array
Recommended order for displaying tags
​
trunc
boolean
True if results were truncated (hit result limit)

​
Rate Limiting

Search implements adaptive rate limiting: 
{
  "error": "rate-limit 0.7 sec, cost 0.85, idle 0.32"
}
  • Queries taking > 0.7s incur 0.7s penalty
  • Next query must wait until penalty expires
  • Returns HTTP 429 if attempted too soon
Rate limiting prevents expensive queries from overloading the server. Wait for the penalty duration before retrying.

​
Search Requirements

​
Indexing

Search requires file indexing to be enabled: 
# Enable basic indexing
copyparty -e2dsa

# Enable metadata indexing (for tag search)
copyparty -e2dsa -e2ts
  • -e2d - Enable file indexing (delete tracking)
  • -e2s - Enable search
  • -e2a - Enable all indexing features
  • -e2ts - Index audio/video metadata tags

​
SQLite Requirement

Search requires SQLite3: 
{
  "error": "sqlite3 not found on server; search is disabled"
}
If SQLite is not available, search will return HTTP 500.

​
Search Examples

​
Find Large Files

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"q": "size:>1G", "n": 50}' \
  http://server:3923/

​
Find Recent Photos

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"q": "date:>2024-01-01 ext:jpg,png,heic"}' \
  http://server:3923/

​
Find High-Quality Audio

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"q": "ext:flac rate:>900"}' \
  http://server:3923/

​
Find Music by Artist

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"q": "artist:Beatles album:Abbey"}' \
  http://server:3923/

​
Find Long Videos

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"q": "ext:mp4,mkv,webm dur:>3600"}' \
  http://server:3923/

​
Search Tips

  • Use quotes for exact phrase matching: "exact phrase"
  • Combine multiple filters for precise results
  • Use wildcards for pattern matching: *.log
  • Check trunc field - if true, refine query to get more specific results
  • Tag search requires -e2ts server flag and FFprobe or Mutagen installed

​
Error Handling

​
429
error
Rate limit exceeded - wait for penalty duration before retrying
​
500
error
Search unavailable - SQLite not found or indexing not enabled
​
503
error
Server busy - indexing in progress, retry in a moment

​
Performance Considerations

  • First search after server restart may be slow (index loading)
  • Wildcard searches are slower than exact matches
  • Tag searches require metadata indexing (adds overhead)
  • Large result sets may be truncated (use more specific queries)
  • Rate limiting prevents search abuse

​
Custom Tag Parsers

You can add custom metadata parsers with file parser plugins to index additional file types and tags.

Build docs developers (and LLMs) love

Get started for freeTalk to us