GET /ai/assistants: filter[tags] and page[*] query params missing from spec

[vasilich6107]

Summary

GET /ai/assistants supports filter[tags] and page[number] / page[size] in production, but the spec declares no parameters at all for the endpoint. Because every SDK is generated from this spec, the filter is unreachable through any official client.

The Telnyx portal itself uses these parameters — the AI Assistants list page issues:

GET /v2/ai/assistants?page%5Bnumber%5D=1&page%5Bsize%5D=25&filter%5Btags%5D=<tag>

What the spec says

paths['/ai/assistants'].get has no parameters key. The rendered docs page says the same: List assistants documents zero query parameters.

What the API does

Verified against a live account today:

request	meta.total_results
GET /v2/ai/assistants	13
?filter[tags]=tag-a	1
?filter[tags]=tag-b	5
?filter[tags]=tag-a,tag-b	0
?filter[tags]=does-not-exist	0
?page[number]=1&page[size]=2	13 (total_pages: 7, page_size: 2)

So filter[tags] is comma-separated with AND semantics (intersection, not union), and the endpoint is paginated with the standard page[number] / page[size] envelope returning meta.total_results / total_pages. Default page_size is 100.

Unknown filter keys appear to be ignored rather than rejected, so the behaviour is easy to miss.

Impact on generated SDKs

telnyx-node@7.21.0:

list(options?: RequestOptions): APIPromise<AssistantsList>;

No AssistantListParams type is generated, so there is no way to pass the filter through the SDK — callers have to drop to a raw request. AssistantsList is also typed as a bare { data: Assistant[] } with no meta, so pagination metadata is lost even when it is returned.

Second endpoint, same class of gap

GET /integration_secrets documents filter with only one property:

"filter": { "type": "object", "properties": { "type": { "enum": ["bearer", "basic"] } } }

But filter[identifier] also works, as an exact match:

• ?filter[identifier]=<full identifier> → total_results: 1
• ?filter[identifier]=<prefix> → total_results: 0

Ask

Add the missing parameters to the spec for both endpoints, and document the filter[tags] AND semantics — the intersection behaviour is not what most people assume from a comma-separated list.

Checked against

• Spec: openapi/spec3.json on master, fetched 2026-09-15
• SDK: telnyx-node@7.21.0
• Live API: api.telnyx.com/v2