Search Files visible to the current account using Forward API filters.
POST /api/v1/forward/files/search
You must include the x-qoder-beta: search-2026-08-31 header. All search filters are optional and must be provided in a JSON body; search parameters with the same names in the URL query are ignored. The ownership selector identity_id is an exception and can only be supplied in the query. The request body must be a single JSON object; use {} when no filters are required.
Ownership query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
identity_id | string | No | For Identity-owned resources only. PATs may supply this query parameter; omitting it uses the administrator scope. SAT ownership is determined by the credential; any SAT (including Admin SAT) explicitly supplying this parameter, even with an empty value, receives HTTP 400. Supplying it in the JSON body is treated as an unknown field and returns 400. See Identity ownership. |
Search filters (JSON body)
| Parameter | Type | Description |
|---|---|---|
metadata | object<string,string> | Exact metadata filters combined with AND. Maximum 16 entries. |
limit | integer | Page size. Default: 20. Range: 1–100. |
page | string | Cursor returned in next_page from the previous response. |
name | string | Case-insensitive substring match on the filename. Maximum length: 255. |
scope_id | string | Resource scope ID. Currently, this is a Session ID. |
Response
| Field | Type | Description |
|---|---|---|
data | array | Forward-visible resources on the current page. Resource fields match the corresponding List endpoint. |
first_id | string | null | ID of the first resource on the current page. |
last_id | string | null | ID of the last resource on the current page. |
has_more | boolean | Whether a subsequent page of Forward-visible resources is confirmed to exist. |
next_page | string | null | Cursor for the next page, or null when there is no next page. |
data match List Files.
Metadata keys must contain 1–64 characters and cannot consist only of whitespace. Metadata values must be strings with a maximum length of 512 characters. Clients must replay next_page exactly as returned and must not construct cursors.
Errors
| HTTP | Type | Trigger |
|---|---|---|
| 400 | invalid_request_error | The Beta header or request body is missing, or a search parameter is invalid; any SAT explicitly supplies query identity_id (even with an empty value), or identity_id is supplied in the JSON body. |
| 401 | authentication_error | The authentication token is missing or invalid. |
| 403 | permission_error | An owner mismatch occurs in the administrator scope, or a downstream service denies access. |
| 404 | not_found_error | The Identity specified by the PAT does not exist, is disabled or deleted, or does not belong to the caller. |
| 429 | rate_limit_error | A Forward or downstream rate limit is exceeded. |
| 500/502/503 | api_error | Forward or a dependent service failed. |