Search API

Search files by name, metadata, tags, and content hashes

copyparty provides powerful search capabilities including metadata search, tag-based queries, and content-hash lookups.

Basic Search

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.

Phrase Search

{"q": "\"family vacation\""}

Matches exact phrase “family vacation”.

Wildcard Search

{"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)

Tag Search

Search by metadata tags (requires indexing with -e2ts):

Artist Search

{"q": "artist:Beethoven"}

Album Search

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

Title Search

{"q": "title:Moonlight"}

Genre Search

{"q": "genre:Classical"}

Year Search

{"q": "year:2020"}

Bitrate Search

{"q": "rate:>320"}

Bitrate in kbps.

Duration Search

{"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.