Experimental Valkey cache sync and prefetch endpoints

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

Type	Strategy	On limit exceeded
`allOne`	Sync all files	Returns error, nothing is synced
`allTwo`	Sync all files	Truncates - syncs as many files as fit within the limit
`mostOne`	Sync most active files as a group	Returns error, nothing is synced
`mostTwo`	Sync most active files as a group	Truncates - 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

string

required

The user ID whose files you want to sync.

string

required

The sync strategy. One of: allOne, allTwo, mostOne, mostTwo.

Example request

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

Response `200`

{
  "user": "usr_9f8e7d6c",
  "synced": 142,
  "skipped": 8
}

number

Number of file metadata entries successfully synced to Valkey.

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

string

required

The user ID whose file metadata you want to prefetch.

number

required

Maximum number of files to prefetch. The service selects the most frequently queried files up to this limit.

Example request

{
  "user": "usr_9f8e7d6c",
  "limit": 50
}

Response `200`

{
  "user": "usr_9f8e7d6c",
  "prefetched": 48
}

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

Type	Trigger	What it does
`OUT`	User logs out	Removes metadata from Valkey only. The database is untouched.
`DEL`	User deletes account	Removes metadata from both Valkey and the database (Convex).

Request body

string

required

The user ID whose cached metadata you want to invalidate.

string

required

Invalidation type. One of: OUT, DEL.

Example request - logout

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

Example request - account deletion

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

Response `200`

{
  "user": "usr_9f8e7d6c",
  "type": "OUT",
  "invalidated": 142
}

string

The invalidation type that was executed (OUT or DEL).

number

Number of metadata entries removed.

Response `404`

{
  "error": "user_not_found"
}

​Sync metadata cache

​How sync works

​Sync types

​Request body

​Response 200

​Response 400

​Response 404

​Prefetch metadata

​Request body

​Response 200

​Response 404

​Invalidate metadata cache

​Invalidation types

​Request body

​Response 200

​Response 404

Sync metadata cache

How sync works

Sync types

Request body

Response `200`

Response `400`

Response `404`

Prefetch metadata

Request body

Response `200`

Response `404`

Invalidate metadata cache

Invalidation types

Request body

Response `200`

Response `404`