voyageai-cli

# Query Parameters Query parameters customize request behavior, allowing filtering, sorting, pagination, and field selection without changing the endpoint URL. ## Standard Query Parameters **page** and **per_page**: Control pagination. ``` GET /users?page=2&per_page=50 ``` Returns 50 users starting at offset (page-1)*per_page. See [Pagination](pagination.md) for details. **filter**: Filter results by field values. Format depends on data type. ``` GET /users?filter[status]=active&filter[created_after]=2026-01-01 ``` See [Filtering](filtering.md) for comprehensive syntax. **sort**: Order results by one or more fields. ``` GET /users?sort=-created_at,name ``` Prefix with `-` for descending order. See [Sorting](sorting.md). **fields**: Specify which fields to include in response (projection). ``` GET /users?fields=id,name,email ``` Reduces response size by excluding unused fields. Useful for bandwidth optimization. **expand**: Include related resources in the response. ``` GET /users/user_123?expand=profile,permissions ``` Reduces round-trips by embedding related data. **include**: Include additional computed fields. ``` GET /users/user_123?include=total_projects,last_login_date ``` ## Parameter Encoding Special characters in query values must be URL-encoded: ``` GET /users?filter[name]=John%20Doe // Space is %20 GET /users?filter[email]=test%40example.com // @ is %40 ``` Most HTTP clients encode this automatically. ## Boolean Parameters Use `true` or `false` for boolean values: ``` GET /users?active=true&verified=false ``` Alternatively use `1`/`0`, but string values are preferred for clarity. ## Multiple Values For multi-valued parameters, repeat the parameter name: ``` GET /users?status=active&status=pending ``` Or use array bracket syntax: ``` GET /users?status[]=active&status[]=pending ``` ## Parameter Validation Invalid parameter values return 400 Bad Request: ```json { "error": "invalid_parameter", "parameter": "page", "value": "abc", "message": "page must be a positive integer" } ``` Required parameters omitted in the URL should be checked—some endpoints require specific query parameters. ## Reserved Parameters Parameters beginning with `_` are reserved: - `_debug=true` - Include debugging information in response (admin only) - `_format=xml` - Return XML instead of JSON (legacy, not recommended) Regular applications should not use `_` prefixed parameters. ## Case Sensitivity Parameter names are case-insensitive. These are equivalent: ``` GET /users?Page=1&Per_Page=50 GET /users?page=1&per_page=50 ``` Parameter *values* are case-sensitive. `status=Active` differs from `status=active`. ## URL Length Limits URLs have a practical limit of ~2,000 characters. For complex filters with many conditions, use POST requests with a request body instead. ## Query String Best Practices - Use consistent naming conventions (snake_case vs. camelCase) - Validate user input before constructing URLs - Avoid exposing internal implementation details - Document all supported query parameters - Consider query complexity impact on performance ## Caching with Query Parameters Query strings affect caching headers. The same base URL with different query parameters is a separate cache key: ``` GET /users?page=1 - Cache key 1 GET /users?page=2 - Cache key 2 ``` This ensures correct pagination caching behavior.