Skip to main content
GET
Search Workspace Files

Authorizations

Authorization
string
header
required

Logged-in user-session JWT authentication for first-party clients. Org-scoped requests also require the Replicas-Org-Id header. User JWTs cannot create workspaces with POST /v1/replica.

Headers

Replicas-Org-Id
string<uuid>
required

Organization UUID containing the workspace.

Path Parameters

workspaceId
string<uuid>
required

Query Parameters

q
string
default:""

Filename or path search; empty lists all indexed files.

prefix
string
default:""

Restrict results to repository-relative paths starting with this prefix.

limit
integer
default:50

Page size. Out-of-range integers are clamped to 1–5,000.

Required range: 1 <= x <= 5000
cursor
string

Opaque nextCursor from the previous page. Keep q, prefix, and limit unchanged.

refresh
boolean
default:false

On the first page, true waits for an active engine refresh. Does not wake inactive workspaces. On failure, a saved index or repository fallback may still be returned as stale.

Response

Live, cached, or repository-fallback file paths.

files
object[]
required
nextCursor
string | null
required

Opaque cursor for the next page; null when pagination is complete.

indexedAt
string<date-time>
required

Index version. Discard accumulated pages and restart without refresh if this value changes between pages.

stale
boolean
required

Results are cached or from a repository fallback and may not reflect the current workspace. Does not by itself mean a refresh is pending.

refreshing
boolean

A background workspace index refresh is pending. Poll only while true; inactive fallback results do not enable polling.

truncated
boolean

Index is incomplete due to provider limits, index caps, or unavailable repositories; independent of nextCursor.

unsupported
boolean

Optional compatibility flag indicating repository file search is unsupported.