Skip to content

feat(search): add typed sync and async resource search #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
moonyue-w merged 1 commit into from
Oct 27, 2026
Merged

feat(search): add typed sync and async resource search #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ existing `0.1.0` release; earlier development prereleases are not listed.

## [Unreleased]

### Added

- Forward resource search for Environments, Skills, Vaults, and Files, with PAT Identity scope in the query.
- Managed resource search for Agents, Sessions, Deployments, Environments, Skills, Vaults, Files, and Memory Stores, including typed metadata and resource filters.
- Automatic Search beta headers and POST body cursor pagination that preserves filters and request options across pages.

## [0.11.0] - 2026-10-27

### Changed
Expand Down
50 changes: 50 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -818,3 +818,53 @@ Released under the [MIT License](LICENSE).
## Forward Webhooks

Manage webhook endpoints and verify signed event deliveries. See [Webhook usage and receiver examples](docs/webhooks.md).

## Resource search

Search uses `POST /<resource>/search` with typed filters in the JSON body.
The SDK automatically includes `x-qoder-beta: search-2026-08-31`, preserving
other effective beta flags. Calling Search with no filters sends `{}`.

- Forward: Environments, Skills, Vaults, and Files.
- Managed: Agents, Sessions, Deployments, Environments, Skills, Vaults, Files,
and Memory Stores.

Metadata filters are exact string matches combined with AND. Each resource also
supports its documented filters, such as name, creation time, Session status,
or Skill source/display title. See the official
[Forward search](https://docs.qoder.com/cloud-agents/api/forward/environments/search)
and [Managed Session search](https://docs.qoder.com/cloud-agents/api/sessions/search)
contracts. This searches QCA resources; it does not perform a web search.

Forward's `identity_id` selector is sent only in the URL query. Set it when a PAT
should search an Identity's resources; omit it with all SATs, whose scope comes
from the token. Search cursors are opaque: automatic pagination puts `next_page`
back into the JSON body's `page` while preserving filters, ownership, and request
options. Existing List methods retain their GET/query pagination behavior.

```python
# client is a Forward client.
for environment in client.environments.search(
metadata={"team": "core"},
name="dev",
identity_id="idn_example", # PAT only; omit for SAT.
limit=20,
):
print(environment.id)

# managed_client is a Managed client. Time filters accept datetime or RFC 3339 strings.
page = managed_client.sessions.search(
metadata={"ticket": "A-123"},
statuses=["idle", "running"],
created_at_gte="2026-01-01T00:00:00Z",
)

# async_client is an AsyncForward client.
async for environment in async_client.environments.search(metadata={"team": "core"}):
print(environment.id)
```

Synchronous searches return `SyncPage`; asynchronous searches can be awaited for
an `AsyncPage` or directly iterated with `async for`. Use `get_next_page()` for
manual pagination (await it on an async page). `*SearchParams` TypedDicts are
exported from `qca.forward.types` and `qca.managed.types`.
Loading
Loading