Search Environments visible in the current Owner Scope using Forward API filters.
POST /api/v1/forward/environments/search
Supports PAT, Admin SAT, and Identity SAT. You must include x-qoder-beta: search-2026-08-31. Search filters are optional and belong in the JSON body; search parameters in the URL query are ignored. The request body must be a single JSON object; use {} for no filters.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
identity_id | string | No | Optional; used only for Identity-owned resources. PAT callers can pass it explicitly; omitting it uses the administrator scope. For SAT, issue an Identity-scoped token and do not explicitly pass this parameter, or the request returns HTTP 400. See Identity ownership. |
identity_id, a PAT searches Environments owned by the current account or Workspace. With it, a PAT searches only the specified Identity. Admin SAT searches only the Workspace; Identity SAT searches only the token-bound Identity. Resources in other scopes are excluded.
Request 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 Environment name. Maximum length: 255. |
include_archived | boolean | Whether to include archived Environments visible to both CAS and Forward. Default: false. |
created_at[gte] | string | Returns Environments created at or after the specified RFC 3339 timestamp. |
created_at[lte] | string | Returns Environments created at or before the specified RFC 3339 timestamp. |
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 Environments.
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, an RFC 3339 timestamp is invalid, or a search parameter is invalid. Also returned if SAT explicitly includes identity_id. |
| 401 | authentication_error | The authentication token is missing or invalid. |
| 403 | permission_error | The caller cannot access the resource. |
| 404 | not_found_error | The PAT-specified identity_id does not exist, is disabled, 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. |