feat(api): align beta pagination limits and non-null parameters (#4057) · openai/openai-python@800899e · GitHub
Skip to content

Commit 800899e

Browse files
jbeckwith-oaijbeckwith-oai
authored
feat(api): align beta pagination limits and non-null parameters (#4057)
## Summary Aligns beta agent pagination with the API’s shared validation rules. ## Changes Beta agent pagination now follows shared API validation: page sizes must be 1–100 (default 20). Session, vault, and vault-credential listings reject out-of-range limits with HTTP 400 instead of clamping them. Omit optional pagination arguments to use defaults. List parameter annotations no longer include `None` for the five list limits or the artifact `after` cursor. Prefer omitting these arguments; existing Python `None` serialization still omits them. Affected beta resources: agents, sessions, session artifacts, vaults, and vault credentials (`beta.agents`). The corresponding HTTP paths are `/agents`, `/agents/sessions`, `/agents/sessions/{session_id}/artifacts`, `/vaults`, and `/vaults/{vault_id}/credentials`. ## Compatibility and migration This follows the beta API’s move to shared pagination validation. Omit `limit` to use 20, or supply an integer from 1 through 100. Omit `after` to start at the first page. Artifact listing already enforced the numeric range; the newly rejected out-of-range requests identified here are session, vault, and vault-credential listings. The change remains within the beta surface and does not use a major-version marker. Co-authored-by: jbeckwith-oai <269036200+jbeckwith-oai@users.noreply.github.com>
1 parent b7a1990 commit 800899e

14 files changed

Lines changed: 121 additions & 150 deletions

File tree

‎.castiron.stats.yml‎

Lines changed: 6 additions & 6 deletions

‎api_reference/openapi.transformed.yml‎

Lines changed: 60 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -31155,12 +31155,12 @@ paths:
3115531155
in: query
3115631156
required: false
3115731157
schema:
31158-
type:
31159-
- integer
31160-
- 'null'
31158+
type: integer
3116131159
format: int64
3116231160
minimum: 1
31163-
description: The maximum number of resources to return.
31161+
maximum: 100
31162+
default: 20
31163+
description: The maximum number of resources to return, between 1 and 100. Defaults to 20.
3116431164
- name: order
3116531165
in: query
3116631166
required: false
@@ -31964,35 +31964,35 @@ paths:
3196431964
in: query
3196531965
required: false
3196631966
schema:
31967-
type:
31968-
- integer
31969-
- 'null'
31967+
type: integer
3197031968
format: int64
3197131969
minimum: 1
31972-
description: The maximum number of resources to return.
31970+
maximum: 100
31971+
default: 20
31972+
description: The maximum number of resources to return, between 1 and 100. Defaults to 20.
3197331973
- name: order
3197431974
in: query
3197531975
required: false
3197631976
schema:
3197731977
$ref: '#/components/schemas/ListOrderParam'
3197831978
default: desc
31979-
description: Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`.
31980-
- name: agent_id
31979+
description: The order in which resources are returned. Defaults to `desc`.
31980+
- name: after
3198131981
in: query
3198231982
required: false
3198331983
schema:
3198431984
type: string
3198531985
minLength: 0
3198631986
maxLength: 1048576
31987-
description: Only return sessions whose root agent has this ID. Omit to return sessions for all agents.
31988-
- name: after
31987+
description: Return resources after this resource ID in the selected order.
31988+
- name: agent_id
3198931989
in: query
3199031990
required: false
3199131991
schema:
3199231992
type: string
3199331993
minLength: 0
3199431994
maxLength: 1048576
31995-
description: Return resources after this resource ID in the selected order.
31995+
description: Only return sessions whose root agent has this ID. Omit to return sessions for all agents.
3199631996
responses:
3199731997
'200':
3199831998
description: A page of sessions.
@@ -32329,34 +32329,32 @@ paths:
3232932329
minLength: 0
3233032330
maxLength: 1048576
3233132331
description: The ID of the session.
32332+
- name: limit
32333+
in: query
32334+
required: false
32335+
schema:
32336+
type: integer
32337+
format: int64
32338+
minimum: 1
32339+
maximum: 100
32340+
default: 20
32341+
description: The maximum number of resources to return, between 1 and 100. Defaults to 20.
3233232342
- name: order
3233332343
in: query
3233432344
required: false
3233532345
schema:
3233632346
$ref: '#/components/schemas/ListOrderParam'
32337-
description: Sort by creation time and ID. Defaults to descending.
32338-
- name: environment_id
32347+
default: desc
32348+
description: The order in which resources are returned. Defaults to `desc`.
32349+
- name: after
3233932350
in: query
3234032351
required: false
3234132352
schema:
32342-
type:
32343-
- string
32344-
- 'null'
32353+
type: string
3234532354
minLength: 0
3234632355
maxLength: 1048576
32347-
description: Restrict the listing to artifacts produced by this environment.
32348-
- name: limit
32349-
in: query
32350-
required: false
32351-
schema:
32352-
type:
32353-
- integer
32354-
- 'null'
32355-
format: int64
32356-
minimum: 1
32357-
maximum: 100
32358-
description: The maximum number of artifacts to return, between 1 and 100.
32359-
- name: after
32356+
description: Return resources after this resource ID in the selected order.
32357+
- name: environment_id
3236032358
in: query
3236132359
required: false
3236232360
schema:
@@ -32365,7 +32363,7 @@ paths:
3236532363
- 'null'
3236632364
minLength: 0
3236732365
maxLength: 1048576
32368-
description: Return artifacts after this immutable artifact ID.
32366+
description: Restrict the listing to artifacts produced by this environment.
3236932367
responses:
3237032368
'200':
3237132369
description: A page of durable session artifacts.
@@ -33227,29 +33225,23 @@ paths:
3322733225
tags:
3322833226
- Vaults
3322933227
parameters:
33230-
- name: order
33231-
in: query
33232-
required: false
33233-
schema:
33234-
$ref: '#/components/schemas/ListOrderParam'
33235-
default: desc
33236-
description: Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`.
3323733228
- name: limit
3323833229
in: query
3323933230
required: false
3324033231
schema:
33241-
type:
33242-
- integer
33243-
- 'null'
33232+
type: integer
3324433233
format: int64
33245-
minimum: 0
33246-
description: The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100.
33247-
- name: status
33234+
minimum: 1
33235+
maximum: 100
33236+
default: 20
33237+
description: The maximum number of resources to return, between 1 and 100. Defaults to 20.
33238+
- name: order
3324833239
in: query
3324933240
required: false
3325033241
schema:
33251-
$ref: '#/components/schemas/VaultStatusFilterParam'
33252-
description: Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default.
33242+
$ref: '#/components/schemas/ListOrderParam'
33243+
default: desc
33244+
description: The order in which resources are returned. Defaults to `desc`.
3325333245
- name: after
3325433246
in: query
3325533247
required: false
@@ -33276,6 +33268,12 @@ paths:
3327633268
description: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. Filtering is eventually consistent; metadata changes may take time to appear.
3327733269
style: deepObject
3327833270
explode: true
33271+
- name: status
33272+
in: query
33273+
required: false
33274+
schema:
33275+
$ref: '#/components/schemas/VaultStatusFilterParam'
33276+
description: Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default.
3327933277
responses:
3328033278
'200':
3328133279
description: A page of vaults.
@@ -33603,29 +33601,23 @@ paths:
3360333601
minLength: 0
3360433602
maxLength: 1048576
3360533603
description: The ID of the vault.
33606-
- name: order
33607-
in: query
33608-
required: false
33609-
schema:
33610-
$ref: '#/components/schemas/ListOrderParam'
33611-
default: desc
33612-
description: Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`.
3361333604
- name: limit
3361433605
in: query
3361533606
required: false
3361633607
schema:
33617-
type:
33618-
- integer
33619-
- 'null'
33608+
type: integer
3362033609
format: int64
33621-
minimum: 0
33622-
description: The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100.
33623-
- name: status
33610+
minimum: 1
33611+
maximum: 100
33612+
default: 20
33613+
description: The maximum number of resources to return, between 1 and 100. Defaults to 20.
33614+
- name: order
3362433615
in: query
3362533616
required: false
3362633617
schema:
33627-
$ref: '#/components/schemas/VaultStatusFilterParam'
33628-
description: Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default.
33618+
$ref: '#/components/schemas/ListOrderParam'
33619+
default: desc
33620+
description: The order in which resources are returned. Defaults to `desc`.
3362933621
- name: after
3363033622
in: query
3363133623
required: false
@@ -33652,6 +33644,12 @@ paths:
3365233644
description: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. Filtering is eventually consistent; metadata changes may take time to appear.
3365333645
style: deepObject
3365433646
explode: true
33647+
- name: status
33648+
in: query
33649+
required: false
33650+
schema:
33651+
$ref: '#/components/schemas/VaultStatusFilterParam'
33652+
description: Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default.
3365533653
responses:
3365633654
'200':
3365733655
description: A page of vault credentials.

‎src/openai/resources/beta/agents/agents.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -305,7 +305,7 @@ def list(
305305
self,
306306
*,
307307
after: str | Omit = omit,
308-
limit: Optional[int] | Omit = omit,
308+
limit: int | Omit = omit,
309309
order: Literal["asc", "desc"] | Omit = omit,
310310
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
311311
# The extra values given here take precedence over values defined on the client or passed to this method.
@@ -322,7 +322,7 @@ def list(
322322
Args:
323323
after: Return resources after this resource ID in the selected order.
324324
325-
limit: The maximum number of resources to return.
325+
limit: The maximum number of resources to return, between 1 and 100. Defaults to 20.
326326
327327
order: The order in which resources are returned. Defaults to `desc`.
328328
@@ -655,7 +655,7 @@ def list(
655655
self,
656656
*,
657657
after: str | Omit = omit,
658-
limit: Optional[int] | Omit = omit,
658+
limit: int | Omit = omit,
659659
order: Literal["asc", "desc"] | Omit = omit,
660660
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
661661
# The extra values given here take precedence over values defined on the client or passed to this method.
@@ -672,7 +672,7 @@ def list(
672672
Args:
673673
after: Return resources after this resource ID in the selected order.
674674
675-
limit: The maximum number of resources to return.
675+
limit: The maximum number of resources to return, between 1 and 100. Defaults to 20.
676676
677677
order: The order in which resources are returned. Defaults to `desc`.
678678

‎src/openai/resources/beta/agents/sessions/artifacts.py‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -104,9 +104,9 @@ def list(
104104
self,
105105
session_id: str,
106106
*,
107-
after: Optional[str] | Omit = omit,
107+
after: str | Omit = omit,
108108
environment_id: Optional[str] | Omit = omit,
109-
limit: Optional[int] | Omit = omit,
109+
limit: int | Omit = omit,
110110
order: Literal["asc", "desc"] | Omit = omit,
111111
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
112112
# The extra values given here take precedence over values defined on the client or passed to this method.
@@ -121,13 +121,13 @@ def list(
121121
[session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).
122122
123123
Args:
124-
after: Return artifacts after this immutable artifact ID.
124+
after: Return resources after this resource ID in the selected order.
125125
126126
environment_id: Restrict the listing to artifacts produced by this environment.
127127
128-
limit: The maximum number of artifacts to return, between 1 and 100.
128+
limit: The maximum number of resources to return, between 1 and 100. Defaults to 20.
129129
130-
order: Sort by creation time and ID. Defaults to descending.
130+
order: The order in which resources are returned. Defaults to `desc`.
131131
132132
- `asc` - Returns resources in ascending order.
133133
- `desc` - Returns resources in descending order.
@@ -332,9 +332,9 @@ def list(
332332
self,
333333
session_id: str,
334334
*,
335-
after: Optional[str] | Omit = omit,
335+
after: str | Omit = omit,
336336
environment_id: Optional[str] | Omit = omit,
337-
limit: Optional[int] | Omit = omit,
337+
limit: int | Omit = omit,
338338
order: Literal["asc", "desc"] | Omit = omit,
339339
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
340340
# The extra values given here take precedence over values defined on the client or passed to this method.
@@ -349,13 +349,13 @@ def list(
349349
[session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).
350350
351351
Args:
352-
after: Return artifacts after this immutable artifact ID.
352+
after: Return resources after this resource ID in the selected order.
353353
354354
environment_id: Restrict the listing to artifacts produced by this environment.
355355
356-
limit: The maximum number of artifacts to return, between 1 and 100.
356+
limit: The maximum number of resources to return, between 1 and 100. Defaults to 20.
357357
358-
order: Sort by creation time and ID. Defaults to descending.
358+
order: The order in which resources are returned. Defaults to `desc`.
359359
360360
- `asc` - Returns resources in ascending order.
361361
- `desc` - Returns resources in descending order.

‎src/openai/resources/beta/agents/sessions/sessions.py‎

Lines changed: 6 additions & 8 deletions

0 commit comments

Comments
 (0)