feat: enhance API responses with pagination support and model updates

[Joffref]

• Updated the API methods for listing agents, sandboxes, drives, functions, jobs, and job executions to support cursor-based pagination.
• Refactored response parsing to return structured lists (e.g., AgentList, SandboxList, DriveList, FunctionList, JobList, JobExecutionList) instead of raw arrays.
• Added new parameters for cursor, limit, sort, and anchor to improve query flexibility and response handling.
• Updated documentation to reflect changes in response structure and pagination capabilities.

This change improves the API's usability and aligns with the latest versioning standards.

---

Note

Adds cursor-based pagination to all list endpoints (agents, sandboxes, drives, functions, jobs, job executions). Return types change from list[T] to structured TList objects with data and meta fields. New query parameters cursor, limit, sort, q, and anchor are threaded through all four call variants. The code is auto-generated from an OpenAPI spec. Two follow-up commits hardened the generated client to handle bare-array responses from older API versions and preserve the JobExecutionList wrapper contract.

^{Written by Mendral for commit 78aad04.}

[mendral-app]

🧪 Testing Guide

What this PR addresses

This PR adds cursor-based pagination support to all 35 list API methods in the SDK (agents, sandboxes, drives, functions, jobs, models, policies, volumes, etc.). List methods now return structured wrapper objects (e.g., AgentList, SandboxList) containing data and meta (with has_more, next_cursor, total) instead of bare arrays. New query parameters (cursor, limit, sort, q, anchor) are added for pagination control. The PR also hardens response parsing with proper JSON error handling.

Steps to exercise the new behavior

1. Basic list call (no pagination params)
   Call any updated list method (e.g., list_agents) without pagination parameters. Verify it returns an AgentList object (or equivalent wrapper) with .data containing the items and .meta containing pagination metadata.

2. Paginated iteration

   from blaxel.client import Client
   from blaxel.api.agents import list_agents
   
   client = Client(base_url="...")
   result = list_agents.sync(client=client, limit=2)
   assert result.data is not None
   if result.meta and result.meta.has_more:
       page2 = list_agents.sync(client=client, cursor=result.meta.next_cursor, limit=2)
       assert page2.data is not None

3. Sort and anchor parameters
   Call with sort=ListAgentsSort.CREATEDAT_DESC and verify results are ordered correctly. Test anchor=ListAgentsAnchor.END to anchor to end of list.

4. Backward compatibility with older API versions
   If the API returns a bare JSON array (pre-2026-04-28 format), verify the SDK wraps it correctly — AgentList.from_dict([...]) should auto-wrap into {"data": [...]}.

5. Error handling
   Simulate a response with invalid JSON body and confirm a ResponseParseError is raised (when raise_on_unexpected_status=True) or None is returned.

What to verify (expected behavior)

• All list methods accept new optional params (cursor, limit, sort, q, anchor) without breaking existing callers that pass no arguments
• Return types are the new wrapper models (AgentList, SandboxList, etc.) with .data (list of items) and .meta (PaginationMeta)
• PaginationMeta contains has_more (bool), next_cursor (str), and total (int)
• Default limit is 50 when not specified
• Backward compat: if API returns a bare array, from_dict() auto-wraps it into {"data": array} without error
• JSON parse errors are caught and either raise ResponseParseError or return None based on client config
• Existing tests pass without modification (or are updated appropriately)
• Type checking passes (mypy / type stubs are consistent with new models)
• All 10 new List models and 18 Sort/Anchor enums are properly exported from the models package

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.

[mendral-app]

LGTM

The previously flagged from_dict guard issue has been fully resolved — all *List models now handle bare arrays via isinstance(src_dict, list) wrapping, None via early return, and empty dicts safely. No new issues found.

_{Tag @mendral-app with feedback or questions. View session}