feat: add metadata and state filtering to GET /instances

[rgarcia]

Summary

• Adds state and metadata query parameters to GET /instances so callers can filter the list by instance state and/or user-defined metadata key-value pairs
• Uses OpenAPI deepObject style for the metadata parameter (?metadata[team]=backend&metadata[env]=staging), which oapi-codegen deserializes into map[string]string automatically
• Multiple metadata entries are ANDed — an instance must match all specified key-value pairs

Example:

GET /instances?state=Running&metadata[team]=backend&metadata[env]=staging

Changes

• openapi.yaml: Added state (enum) and metadata (deepObject) query params to GET /instances
• lib/oapi/oapi.go: Regenerated from updated spec
• lib/instances/types.go: Added ListInstancesFilter type with Matches() method
• lib/instances/manager.go: Updated Manager interface and implementation to accept *ListInstancesFilter
• cmd/api/api/instances.go: Handler converts OAPI params → domain filter
• lib/instances/filter_test.go: 19 test cases covering filter matching and end-to-end filtered listing with on-disk metadata

Test plan

• TestListInstancesFilter_Matches — 13 cases covering nil/empty filter, state, metadata, and combinations
• TestListInstancesFilter_Matches_NilMetadata — instance with no metadata vs metadata filter
• TestListInstances_WithFilter — 6 sub-tests exercising the full ListInstances path with on-disk metadata files (no KVM required)
• Existing tests updated and passing (TestStorageOperations, TestStateTransitions, builds mock, etc.)

Made with Cursor

---

Note

Medium Risk
Touches the ListInstances interface and OpenAPI-generated bindings, so downstream callers/tests must be updated and subtle query-binding/filtering bugs could change which instances are returned.

Overview
Adds optional filtering to GET /instances via new state and metadata query parameters (metadata uses OpenAPI deepObject syntax and all criteria are ANDed).

Plumbs the filter through the API handler into the domain layer by introducing instances.ListInstancesFilter (with Matches) and updating instances.Manager.ListInstances to accept a filter; updates call sites/tests and regenerates the OpenAPI client/server bindings + spec. Includes new unit and on-disk integration tests for filter behavior.

^{Written by Cursor Bugbot for commit 84f3ae5. This will update automatically on new commits. Configure here.}

[github-actions]

✱ Stainless preview builds

This PR will update the hypeman SDKs with the following commit message.

feat: add metadata and state filtering to GET /instances

⚠️ hypeman-openapi studio · code

There was a regression in your SDK.
generate ⚠️

⚠️ hypeman-typescript studio · code

There was a regression in your SDK.
generate ❗ → build ⏳ → lint ⏳ → test ⏳

⚠️ hypeman-go studio · code

There was a regression in your SDK.
generate ⚠️ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@713209d693a641679cef6c4f1a85fd4134c1bbe3

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-02-17 16:01:11 UTC