Skip to main content
Experimental endpoints are prefixed with /api/v1/e/ and are not guaranteed to be included in the main API. They are subject to change or removal without notice.

​
Sync metadata cache

POST /api/v1/e/meta/sync
Synchronizes file metadata from the database to Valkey with an extended TTL.

​
How sync works

Under normal operation, individual file metadata entries are cached in Valkey with a 1-hour TTL based on access patterns. This works well for most users, but when a user switches between apps frequently, the cache can become stale or fragmented. The sync endpoint performs a bulk synchronization. It takes all (or the most active) files for a user and pushes them into Valkey with a longer TTL in a single operation. This avoids the overhead of relying on individual cache hits.
Hard limit: A single sync operation cannot exceed 450 MB of data. Behavior when exceeding this limit depends on the selected sync type.

​
Sync types

TypeStrategyOn limit exceeded
allOneSync all filesReturns error, nothing is synced
allTwoSync all filesTruncates - syncs as many files as fit within the limit
mostOneSync most active files as a groupReturns error, nothing is synced
mostTwoSync most active files as a groupTruncates - syncs as many files as fit within the limit
Why mostOne / mostTwo? Instead of making 15 separate cache hits for the 15 most active files, you make a single sync call to cache them all at once. This reduces endpoint hits and ensures the most accessed files are always warm in cache.

​
Request body

​
user
string
required
The user ID whose files you want to sync.
​
type
string
required
The sync strategy. One of: allOne, allTwo, mostOne, mostTwo.
{
  "user": "usr_9f8e7d6c",
  "type": "mostTwo"
}

​
Response 200

{
  "user": "usr_9f8e7d6c",
  "synced": 142,
  "skipped": 8
}
​
synced
number
Number of file metadata entries successfully synced to Valkey.
​
skipped
number
Number of entries skipped (e.g., due to the hard limit in allTwo / mostTwo).

​
Response 400

Returned when the sync would exceed the 450 MB hard limit (for allOne and mostOne types). 
{
  "error": "limit_exceeded"
}

​
Response 404

{
  "error": "user_not_found"
}

​
Prefetch metadata

POST /api/v1/e/meta/prefetch
Proactively loads file metadata into the Valkey cache before the TTL expires. Instead of waiting for cache entries to expire and then re-fetching on demand, prefetch pushes data into the cache ahead of time. The endpoint fetches the most frequently accessed files for the given user from the database and pushes them into Valkey.

​
Request body

​
user
string
required
The user ID whose file metadata you want to prefetch.
​
limit
number
required
Maximum number of files to prefetch. The service selects the most frequently queried files up to this limit.
{
  "user": "usr_9f8e7d6c",
  "limit": 50
}

​
Response 200

{
  "user": "usr_9f8e7d6c",
  "prefetched": 48
}
​
prefetched
number
Number of file metadata entries pushed to cache.

​
Response 404

{
  "error": "user_not_found"
}

​
Invalidate metadata cache

POST /api/v1/e/meta/invalidate
Forces immediate removal of cached file metadata without waiting for the TTL to expire. The behavior depends on the invalidation type.

​
Invalidation types

TypeTriggerWhat it does
OUTUser logs outRemoves metadata from Valkey only. The database is untouched.
DELUser deletes accountRemoves metadata from both Valkey and the database (Convex).

​
Request body

​
user
string
required
The user ID whose cached metadata you want to invalidate.
​
type
string
required
Invalidation type. One of: OUT, DEL.
{
  "user": "usr_9f8e7d6c",
  "type": "OUT"
}

{
  "user": "usr_9f8e7d6c",
  "type": "DEL"
}

​
Response 200

{
  "user": "usr_9f8e7d6c",
  "type": "OUT",
  "invalidated": 142
}
​
type
string
The invalidation type that was executed (OUT or DEL).
​
invalidated
number
Number of metadata entries removed.

​
Response 404

{
  "error": "user_not_found"
}