Skip to content

feat(api): update usage APIs and documentation #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
apcha-oai merged 1 commit into from
Sep 2, 2026
Merged

feat(api): update usage APIs and documentation #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .castiron.stats.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
schema_version: 1
generation_id: 50dd6550-6431-44db-811b-c05e5a06336b
openapi_spec_hash: 4af7018ff56446e0398fc7946a92680f
openapi_transformed_spec_hash: b2689771e08c3fdc6ae8f0433dc2c784
config_hash: 5c00fe18ea913ed0186f9894adc02a70
codegen_sha: aff7e70b6efde6a886219ec2200b35e29d8d5691
codegen_hash: c70f5adea80c1c0a55a1baa900e0d1b426fe7eab7b3f784e1f8fa618d55d636f
public_codegen_sha: dba43bacaa8e42c8f8935a785824e36534d96d26
generation_id: d6280972-fd10-4e52-951a-35080fbf6da5
openapi_spec_hash: 0ba3e4acd88b521d832e2a42d5471e00
openapi_transformed_spec_hash: 0a6002520553b981f4c0bf6555a0a623
config_hash: d8813efd847d1966dd7f03bb648c41dc
codegen_sha: 7c221fa0157ba1ca4c061f121c9ab68fecb95745
codegen_hash: fcbbb1cc7d53e250efb293da8ac2f9bd37374f94b72217d0a41443583c9e5d53
public_codegen_sha: ae17fe79e7dfa36a1cc573f2757f3be7258929e9
733 changes: 351 additions & 382 deletions api_reference/openapi.transformed.yml
View file
Open in desktop

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions pkg/cmd/adminorganizationusage.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,6 +290,11 @@ var adminOrganizationUsageCosts = cli.Command{
Default: 7,
QueryPath: "limit",
},
&requestflag.Flag[[]string]{
Name: "line-item",
Usage: "Return only costs for these exact line item names. Each value must match the complete `line_item` value, for example `gpt-5.6-sol, input_tokens`.",
QueryPath: "line_items",

@HAYDEN-OAI HAYDEN-OAI Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Preserve line_items array elements from stdin

In the existing JSON/YAML stdin mode, with no explicit --line-item, input such as {"start_time":1,"line_items":["gpt-5.6-sol, input_tokens"]} sends the JSON text of the whole array as one line_items[] value. The stdin adapter JSON-marshals the array before calling Flag[[]string].Set, whose slice setter parses and appends one string. The resulting value includes the brackets and quotes instead of the exact line-item name, so the new filter requests a different name than the caller supplied. Please preserve individual array elements when populating this query flag from stdin. Explicit quoted or repeated --line-item arguments are unaffected.

@apcha-oai apcha-oai Sep 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

valid but existing bug; affects all arrays similarly

},
Comment on lines +293 to +297
&requestflag.Flag[string]{
Name: "page",
Usage: "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.",
Expand Down
1 change: 1 addition & 0 deletions pkg/cmd/adminorganizationusage_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ func TestAdminOrganizationUsageCosts(t *testing.T) {
"--end-time", "0",
"--group-by", "project_id",
"--limit", "0",
"--line-item", "string",
"--page", "page",
"--project-id", "string",
)
Expand Down
6 changes: 3 additions & 3 deletions pkg/cmd/betaassistant_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ func TestBetaAssistantsCreate(t *testing.T) {
"--api-key", "string",
"--admin-api-key", "string",
"beta:assistants", "create",
"--model", "gpt-4o",
"--model", "gpt-5",
"--description", "description",
"--instructions", "instructions",
"--metadata", "{foo: string}",
Expand All @@ -40,7 +40,7 @@ func TestBetaAssistantsCreate(t *testing.T) {
"--api-key", "string",
"--admin-api-key", "string",
"beta:assistants", "create",
"--model", "gpt-4o",
"--model", "gpt-5",
"--description", "description",
"--instructions", "instructions",
"--metadata", "{foo: string}",
Expand All @@ -58,7 +58,7 @@ func TestBetaAssistantsCreate(t *testing.T) {
t.Run("piping data", func(t *testing.T) {
// Test piping YAML data over stdin
pipeData := []byte("" +
"model: gpt-4o\n" +
"model: gpt-5\n" +
"description: description\n" +
"instructions: instructions\n" +
"metadata:\n" +
Expand Down
6 changes: 3 additions & 3 deletions pkg/cmd/betaresponse.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ var betaResponsesCreate = requestflag.WithInnerFlags(cli.Command{
},
&requestflag.Flag[string]{
Name: "model",
Usage: "Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)\nto browse and compare available models.\n",
Usage: "Model ID used to generate the response, like `gpt-5.6-sol`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)\nto browse and compare available models.\n",
BodyPath: "model",
},
&requestflag.Flag[map[string]any]{
Expand Down Expand Up @@ -113,7 +113,7 @@ var betaResponsesCreate = requestflag.WithInnerFlags(cli.Command{
},
&requestflag.Flag[map[string]any]{
Name: "reasoning",
Usage: "**gpt-5 and o-series models only**\n\nConfiguration options for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n",
Usage: "Configuration options for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n",
BodyPath: "reasoning",
},
&requestflag.Flag[*string]{
Expand Down Expand Up @@ -402,7 +402,7 @@ var betaResponsesCompact = requestflag.WithInnerFlags(cli.Command{
Flags: []cli.Flag{
&requestflag.Flag[*string]{
Name: "model",
Usage: "Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models.",
Usage: "Model ID used to generate the response, like `gpt-5.6-sol`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models.",
Required: true,
BodyPath: "model",
},
Expand Down
6 changes: 3 additions & 3 deletions pkg/cmd/betaresponse_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ func TestBetaResponsesCreate(t *testing.T) {
"--max-output-tokens", "16",
"--max-tool-calls", "0",
"--metadata", "{foo: string}",
"--model", "gpt-5.1",
"--model", "gpt-5.6-sol",
"--moderation", "{model: model, policy: {input: {mode: score}, output: {mode: score}}}",
"--multi-agent", "{enabled: true, max_concurrent_subagents: 1}",
"--parallel-tool-calls=true",
Expand Down Expand Up @@ -74,7 +74,7 @@ func TestBetaResponsesCreate(t *testing.T) {
"--max-output-tokens", "16",
"--max-tool-calls", "0",
"--metadata", "{foo: string}",
"--model", "gpt-5.1",
"--model", "gpt-5.6-sol",
"--moderation.model", "model",
"--moderation.policy", "{input: {mode: score}, output: {mode: score}}",
"--multi-agent.enabled=true",
Expand Down Expand Up @@ -127,7 +127,7 @@ func TestBetaResponsesCreate(t *testing.T) {
"max_tool_calls: 0\n" +
"metadata:\n" +
" foo: string\n" +
"model: gpt-5.1\n" +
"model: gpt-5.6-sol\n" +
"moderation:\n" +
" model: model\n" +
" policy:\n" +
Expand Down
2 changes: 1 addition & 1 deletion pkg/cmd/chatcompletion.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ var chatCompletionsCreate = requestflag.WithInnerFlags(cli.Command{
},
&requestflag.Flag[string]{
Name: "model",
Usage: "Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)\nto browse and compare available models.\n",
Usage: "Model ID used to generate the response, like `gpt-5.6-sol` or `o3`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)\nto browse and compare available models.\n",
Required: true,
BodyPath: "model",
},
Expand Down
6 changes: 3 additions & 3 deletions pkg/cmd/chatcompletion_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ func TestChatCompletionsCreate(t *testing.T) {
"chat:completions", "create",
"--max-items", "10",
"--message", "{content: string, role: developer, name: name}",
"--model", "gpt-5.4",
"--model", "gpt-5.6-sol",
"--audio", "{format: wav, voice: alloy}",
"--frequency-penalty", "-2",
"--function-call", "none",
Expand Down Expand Up @@ -69,7 +69,7 @@ func TestChatCompletionsCreate(t *testing.T) {
"chat:completions", "create",
"--max-items", "10",
"--message", "{content: string, role: developer, name: name}",
"--model", "gpt-5.4",
"--model", "gpt-5.6-sol",
"--audio.format", "wav",
"--audio.voice", "alloy",
"--frequency-penalty", "-2",
Expand Down Expand Up @@ -123,7 +123,7 @@ func TestChatCompletionsCreate(t *testing.T) {
" - content: string\n" +
" role: developer\n" +
" name: name\n" +
"model: gpt-5.4\n" +
"model: gpt-5.6-sol\n" +
"audio:\n" +
" format: wav\n" +
" voice: alloy\n" +
Expand Down
2 changes: 1 addition & 1 deletion pkg/cmd/inputtoken.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ var responsesInputTokensCount = requestflag.WithInnerFlags(cli.Command{
},
&requestflag.Flag[map[string]any]{
Name: "reasoning",
Usage: "**gpt-5 and o-series models only**\n\nConfiguration options for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n",
Usage: "Configuration options for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n",
BodyPath: "reasoning",
},
&requestflag.Flag[map[string]any]{
Expand Down
2 changes: 1 addition & 1 deletion pkg/cmd/model_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ func TestModelsRetrieve(t *testing.T) {
"--api-key", "string",
"--admin-api-key", "string",
"models", "retrieve",
"--model", "gpt-4o-mini",
"--model", "gpt-5.6-sol",
)
})
}
Expand Down
4 changes: 2 additions & 2 deletions pkg/cmd/response.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ var responsesCreate = requestflag.WithInnerFlags(cli.Command{
},
&requestflag.Flag[map[string]any]{
Name: "reasoning",
Usage: "**gpt-5 and o-series models only**\n\nConfiguration options for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n",
Usage: "Configuration options for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n",
BodyPath: "reasoning",
},
&requestflag.Flag[*string]{
Expand Down Expand Up @@ -369,7 +369,7 @@ var responsesCompact = requestflag.WithInnerFlags(cli.Command{
Flags: []cli.Flag{
&requestflag.Flag[*string]{
Name: "model",
Usage: "Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models.",
Usage: "Model ID used to generate the response, like `gpt-5.6-sol`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models.",
Required: true,
BodyPath: "model",
},
Expand Down
6 changes: 3 additions & 3 deletions pkg/cmd/response_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ func TestResponsesCreate(t *testing.T) {
"--max-output-tokens", "16",
"--max-tool-calls", "0",
"--metadata", "{foo: string}",
"--model", "gpt-5.1",
"--model", "gpt-5.6-sol",
"--moderation", "{model: model, policy: {input: {mode: score}, output: {mode: score}}}",
"--parallel-tool-calls=true",
"--previous-response-id", "previous_response_id",
Expand Down Expand Up @@ -72,7 +72,7 @@ func TestResponsesCreate(t *testing.T) {
"--max-output-tokens", "16",
"--max-tool-calls", "0",
"--metadata", "{foo: string}",
"--model", "gpt-5.1",
"--model", "gpt-5.6-sol",
"--moderation.model", "model",
"--moderation.policy", "{input: {mode: score}, output: {mode: score}}",
"--parallel-tool-calls=true",
Expand Down Expand Up @@ -122,7 +122,7 @@ func TestResponsesCreate(t *testing.T) {
"max_tool_calls: 0\n" +
"metadata:\n" +
" foo: string\n" +
"model: gpt-5.1\n" +
"model: gpt-5.6-sol\n" +
"moderation:\n" +
" model: model\n" +
" policy:\n" +
Expand Down