APIs / OpenAI

OpenAI API changes

Breaking changes, deprecations and new fields in the OpenAI API, as they ship.

OpenAI2026-10-19 · 33248a632 additive

2 new response fields

UsageCompletionsResult.input_cache_write_30m_tokens
DecisionsUsageResult.input_cache_write_30m_tokens

OpenAI2026-10-16 · 6ca9cb2b2 breaking

Breakingdirection flip: their tools call this safe
spend_control is no longer accepted
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
2 places: CreateAgentSessionParams.spend_control, UpdateAgentSessionParams.spend_control
Code that breaks
```
await client.post("/…", {
  // spend_control is now ignored, not rejected
  spend_control: value,
});
```
Breaking
Response field spend_control removed
Reads of this field return undefined, and the failure surfaces wherever that value is used rather than at the call.
SessionResource.spend_control · reachable from 5 operations
Code that breaks
```
// response.spend_control is now undefined
const spend_control = response.spend_control;
```

OpenAI2026-10-16 · 35060f5b1 breaking1 additive

Breakingdirection flip: their tools call this safe
type can now return "prompt"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
VoiceResource.type · reachable from 1 operation
Code that breaks
```
switch (response.type) {
  // existing branches …
  // no branch for "prompt"
  default:
    throw new Error("unexpected type");
}
```
Additive
Response field prompt added
No action needed unless you validate responses against a closed schema.
VoiceResource.prompt · reachable from 1 operation

OpenAI2026-10-16 · ee5b185a1 breaking

Breakingdirection flip: their tools call this safe
value can now return "degraded"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
ExternalStorageStatus · reachable from 4 operations
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "degraded"
  default:
    throw new Error("unexpected value");
}
```

OpenAI2026-10-15 · f192b5781 breaking2 additive

Breakingdirection flip: their tools call this safe
Response field url is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
no longer guaranteed present; can now be null
2 places: BetaWebSearchActionFind.url, WebSearchActionFind.url
Code that breaks
```
// response.url may now be absent or null
const url = response.url ?? fallback;
```

2 request fields now accept null

WebSearchActionFind.url
BetaWebSearchActionFind.url

OpenAI2026-10-15 · f601a4406 additive

3 new response fields

ImagesResponse.safety_identifier
ImageGenCompletedEvent.safety_identifier
ImageEditCompletedEvent.safety_identifier

3 new request properties

CreateImageEditRequest.safety_identifier
CreateImageRequest.safety_identifier
EditImageBodyJsonParam.safety_identifier

OpenAI2026-10-15 · 2cc9e14c1 additive

Additive
Request property phase added
No action needed unless it is required.
DecisionInputMessage.phase · reachable from 1 operation

OpenAI2026-10-15 · 08c348188 additive

8 new response fields

Error-2.param
Error-2.type
VideoResource.error.param
VideoResource.error.type
BetaResponseError.param
BetaResponseError.type
ResponseError.param
ResponseError.type

OpenAI2026-10-14 · 0fce13ce1 breaking1 additive

Breakingdirection flip: their tools call this safe
value can now return "AU_STORAGE_PROCESSING", "IN_STORAGE_PROCESSING", "JP_STORAGE_PROCESSING"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
PublicProjectResidency · reachable from 5 operations
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "AU_STORAGE_PROCESSING"
  // no branch for "IN_STORAGE_PROCESSING"
  // no branch for "JP_STORAGE_PROCESSING"
  default:
    throw new Error("unexpected value");
}
```
Additive
Request property scopes added
No action needed unless it is required.
UpdateProjectApiKeyBody.scopes · reachable from 1 operation

OpenAI2026-10-13 · 803527044 additive

2 new response fields

ImageGenToolCall.error
BetaImageGenToolCall.error

2 new request properties

ImageGenToolCall.error
BetaImageGenToolCall.error

OpenAI2026-10-13 · 77618e641 additive

Additive
POST /organization/projects/{project_id}/api_keys/{api_key_id} added
No action needed.
POST /organization/projects/{project_id}/api_keys/{api_key_id}

OpenAI2026-10-09 · e95c0fe61 additive

Additive
/organization/usage/decisions added
No action needed.
/organization/usage/decisions

OpenAI2026-10-08 · 05dbd4252 breaking

Breakingdirection flip: their tools call this safe
value can now return "suspended"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
EnvironmentStatusResource · reachable from 3 operations
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "suspended"
  default:
    throw new Error("unexpected value");
}
```
Breakingdirection flip: their tools call this safe
value can now return "expired", "suspended"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
SessionEnvironmentStatusResource · reachable from 2 operations
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "expired"
  // no branch for "suspended"
  default:
    throw new Error("unexpected value");
}
```

OpenAI2026-10-08 · fd15e7a81 additive

Additive
Response field detailed_explanation added
No action needed unless you validate responses against a closed schema.
SafetyAlertResource.detailed_explanation · reachable from 1 operation

OpenAI2026-10-08 · 978d05711 breaking2 additive

Breakingdirection flip: their tools call this safe
value can now return "ready"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
EnvironmentStatusResource · reachable from 3 operations
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "ready"
  default:
    throw new Error("unexpected value");
}
```
Additive
/agents/environments added
No action needed.
/agents/environments
Additive
Request property environment_id added
No action needed unless it is required.
EnvironmentParamOpenaiHosted.environment_id · reachable from 1 operation

OpenAI2026-10-08 · 35b0d4eb3 additive

Additive
Response field spend_control added
No action needed unless you validate responses against a closed schema.
SessionResource.spend_control · reachable from 5 operations

2 new request properties

CreateAgentSessionParams.spend_control
UpdateAgentSessionParams.spend_control

OpenAI2026-10-08 · 506aff0a2 breaking

Breaking
limit changed type
Serialization mismatch. Integer-to-string moves are the usual cause and the usual outage.
GET /agents · limit · 5 call sites
Code that breaks
```
// payload.limit
// was: integer|null
// now: integer
```
Breaking
after changed type
Serialization mismatch. Integer-to-string moves are the usual cause and the usual outage.
GET /agents/sessions/{session_id}/artifacts · after
Code that breaks
```
// payload.after
// was: null|string
// now: string
```

OpenAI2026-10-08 · 3c4759c11 breaking

Breakingdirection flip: their tools call this safe
Response values are no longer constrained
The documented set of values is gone, so anything can appear. Every exhaustive switch and generated enum over this field is now incomplete.
VoiceResource.type · reachable from 1 operation

OpenAI2026-10-07 · ee483b4b1 breaking

Breaking
voice no longer accepts "shitan"
A value you may have hardcoded is now rejected.
LiveInitialSessionAudioOutputParam.voice · reachable from 2 operations
Code that breaks
```
// sending "shitan" for voice is now rejected
```

OpenAI2026-10-06 · 4a4020d81 breaking

Breakingdirection flip: their tools call this safe
value can now return "billing_not_active"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
SessionTurnErrorCodeResource · reachable from 6 operations
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "billing_not_active"
  default:
    throw new Error("unexpected value");
}
```

OpenAI2026-10-06 · 55ec4ae41 behavioral

Behavioral
429 is now documented on /agents/environments/{environment_id}/files
An unhandled branch in your error handling.
POST /agents/environments/{environment_id}/files · 2 call sites

OpenAI2026-10-06 · af7f56431 breaking

Breaking
Response field compute_units removed
Reads of this field return undefined, and the failure surfaces wherever that value is used rather than at the call.
ResponseUsageResource.compute_units · reachable from 1 operation
Code that breaks
```
// response.compute_units is now undefined
const compute_units = response.compute_units;
```

OpenAI2026-10-06 · bc009d6d2 additive

Additive
metadata is now optional
No action needed.
GET /vaults · metadata · 2 call sites
Additive
POST /vaults/{vault_id} added
No action needed.
POST /vaults/{vault_id}

OpenAI2026-10-06 · 1f3dba722 additive

Additive
/decisions added
No action needed.
/decisions
Additive
Response field cache_write_tokens added
No action needed unless you validate responses against a closed schema.
InputTokensDetailsResource.cache_write_tokens · reachable from 1 operation

OpenAI2026-10-06 · 451c025c1 breaking

Breaking
environment changed type
Serialization mismatch. Integer-to-string moves are the usual cause and the usual outage.
LiveHostedShellToolInputParam.environment · reachable from 3 operations
Code that breaks
```
// payload.environment
// was: null|object
// now: null
```

OpenAI2026-10-06 · 00747d3c2 additive

2 new response fields

MisalignmentErrorDetailsResource.review_target
BetaMisalignmentErrorDetailsResource.review_target

OpenAI2026-10-06 · 9b144ec91 additive

Additive
Request field now accepts null
A relaxation. Existing payloads are unaffected.
LiveHostedShellToolInputParam.environment · reachable from 3 operations

OpenAI2026-10-06 · 008a26972 breaking1 additive

Breakingdirection flip: their tools call this safe
Response field bytes is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
can now be null
2 places: OpenAIFile.bytes, Upload.file.bytes
Code that breaks
```
// response.bytes may now be absent or null
const bytes = response.bytes ?? fallback;
```
Breakingdirection flip: their tools call this safe
Response field finish_reason is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
CreateChatCompletionStreamResponse.choices[].finish_reason · reachable from 1 operation
Code that breaks
```
// response.choices[0].finish_reason may now be absent or null
const finish_reason = response.choices[0].finish_reason ?? fallback;
```
Additive
Response field audio added
No action needed unless you validate responses against a closed schema.
ChatCompletionStreamResponseDelta.audio · reachable from 1 operation

OpenAI2026-10-05 · 8f5077ae1 breaking

Breaking
voice no longer accepts "aube"
A value you may have hardcoded is now rejected.
LiveInitialSessionAudioOutputParam.voice · reachable from 2 operations
Code that breaks
```
// sending "aube" for voice is now rejected
```

OpenAI2026-10-03 · 69be979f1 behavioral

Behavioral
201 is now documented on /organization/invites
An unhandled branch in your error handling.
POST /organization/invites · 4 call sites

OpenAI2026-10-02 · a646991c1 breaking

Breakingdirection flip: their tools call this safe
value can now return "organization_spend_limit_exceeded", "organization_usage_limit_exceeded", "project_spend_limit_exceeded"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
SessionTurnErrorCodeResource · reachable from 6 operations
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "organization_spend_limit_exceeded"
  // no branch for "organization_usage_limit_exceeded"
  // no branch for "project_spend_limit_exceeded"
  default:
    throw new Error("unexpected value");
}
```

OpenAI2026-10-02 · b1dc20ef1 additive

Additive
Response field user_id added
No action needed unless you validate responses against a closed schema.
CostsResult.user_id · reachable from 11 operations

OpenAI2026-10-02 · 237b87781 additive

Additive
/agents/sessions/{session_id}/turns/{turn_id}/items added
No action needed.
/agents/sessions/{session_id}/turns/{turn_id}/items

OpenAI2026-10-02 · f0f75fa23 additive

3 new response fields

UsageWebSearchCallsResult.api_source
CostsResult.api_source
UsageCompletionsResult.api_source

OpenAI2026-10-01 · a9380e1e1 breaking1 behavioral1 additive

Breaking
type no longer accepts "consent"
A value you may have hardcoded is now rejected.
CreateVoiceFromConsentRequest.type · reachable from 1 operation
Code that breaks
```
// sending "consent" for type is now rejected
```
Behavioral
Default value changed
Behavior shifts for every call that omits the field.
CreateVoiceFromConsentRequest.type · reachable from 1 operation
Additive
Response field type added
No action needed unless you validate responses against a closed schema.
VoiceResource.type · reachable from 1 operation

OpenAI2026-10-01 · c300cf283 breaking

Breakingdirection flip: their tools call this safe
Response field refusal is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
ChatCompletionResponseMessage.refusal · reachable from 4 operations
Code that breaks
```
// response.refusal may now be absent or null
const refusal = response.refusal ?? fallback;
```
Breakingdirection flip: their tools call this safe
Response field first_id is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
ChatCompletionList.first_id · reachable from 1 operation
Code that breaks
```
// response.first_id may now be absent or null
const first_id = response.first_id ?? fallback;
```
Breakingdirection flip: their tools call this safe
Response field last_id is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
ChatCompletionList.last_id · reachable from 1 operation
Code that breaks
```
// response.last_id may now be absent or null
const last_id = response.last_id ?? fallback;
```

OpenAI2026-10-01 · 40496dbd3 breaking

Breakingdirection flip: their tools call this safe
audio_sample is no longer accepted
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
CreateVoiceRequest.audio_sample · reachable from 1 operation
Code that breaks
```
await client.post("/…", {
  // audio_sample is now ignored, not rejected
  audio_sample: value,
});
```
Breakingdirection flip: their tools call this safe
consent is no longer accepted
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
CreateVoiceRequest.consent · reachable from 1 operation
Code that breaks
```
await client.post("/…", {
  // consent is now ignored, not rejected
  consent: value,
});
```
Breakingdirection flip: their tools call this safe
name is no longer accepted
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
CreateVoiceRequest.name · reachable from 1 operation
Code that breaks
```
await client.post("/…", {
  // name is now ignored, not rejected
  name: value,
});
```

OpenAI2026-10-01 · 9615b2521 breaking

Breaking
value no longer accepts "ultrafast"
A value you may have hardcoded is now rejected.
no longer accepts "ultrafast"
5 places: ServiceTierParam, CreateAgentParams.service_tier, SessionAgentConfigParam.service_tier, UpdateAgentParams.service_tier, UpdateSessionAgentParam.service_tier
Code that breaks
```
// sending "ultrafast" for undefined is now rejected
```

OpenAI2026-09-30 · cc501ffc1 breaking1 deprecation2 behavioral

Breaking
model is now required
Partial payloads are rejected.
2 places: CreateImageEditRequest.model, CreateImageRequest.model
Code that breaks
```
await client.post("/…", {
  // …
  model: /* now required */,
});
```
Deprecation
POST /images/variations deprecated
Still works today. This is the earliest warning you will get before it is removed.
POST /images/variations
Behavioral
Default value changed
Behavior shifts for every call that omits the field.
CreateImageEditRequest.size · reachable from 1 operation
Behavioral
Default value changed
Behavior shifts for every call that omits the field.
EditImageBodyJsonParam.model · reachable from 1 operation

OpenAI2026-09-30 · 19fa5b491 breaking1 additive

Breaking
POST /evals/{eval_id}/runs/{run_id} removed
This verb now 405s. The path still resolves, so a health check on the URL will not catch it.
POST /evals/{eval_id}/runs/{run_id}
Code that breaks
```
// Was:
await client.request("POST", "/evals/{eval_id}/runs/{run_id}");
// Now: 405
```
Additive
/evals/{eval_id}/runs/{run_id}/cancel added
No action needed.
/evals/{eval_id}/runs/{run_id}/cancel

OpenAI2026-09-30 · 36a1ed5e2 behavioral

Behavioral
502 is now documented on /live/sessions
An unhandled branch in your error handling.
POST /live/sessions
Behavioral
504 is now documented on /live/sessions
POST /live/sessions

OpenAI2026-09-30 · 0e8a1e051 additive

Additive
Response field input_cache_write_12h_tokens added
No action needed unless you validate responses against a closed schema.
UsageCompletionsResult.input_cache_write_12h_tokens · reachable from 11 operations

OpenAI2026-09-30 · a36ff95b1 additive

Additive
/agents/sessions/{session_id}/traces added
No action needed.
/agents/sessions/{session_id}/traces

OpenAI2026-09-29 · fe524f2c4 breaking

Breakingdirection flip: their tools call this safe
Response field model is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
EvalRun.model · reachable from 4 operations
Code that breaks
```
// response.model may now be absent or null
const model = response.model ?? fallback;
```
Breakingdirection flip: their tools call this safe
Response field name is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
EvalRun.name · reachable from 4 operations
Code that breaks
```
// response.name may now be absent or null
const name = response.name ?? fallback;
```
Breakingdirection flip: their tools call this safe
Response field per_model_usage is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
EvalRun.per_model_usage · reachable from 4 operations
Code that breaks
```
// response.per_model_usage may now be absent or null
const per_model_usage = response.per_model_usage ?? fallback;
```
Breakingdirection flip: their tools call this safe
Response field per_testing_criteria_results is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
EvalRun.per_testing_criteria_results · reachable from 4 operations
Code that breaks
```
// response.per_testing_criteria_results may now be absent or null
const per_testing_criteria_results = response.per_testing_criteria_results ?? fallback;
```

OpenAI2026-09-29 · b4c297d92 breaking4 additive

Breaking
token_usage changed type
Parse failure, or silent coercion depending on your client.
RunGraderResponse.metadata.token_usage · reachable from 1 operation
Code that breaks
```
// payload.metadata.token_usage
// was: integer|null
// now: null|object
```
Breakingdirection flip: their tools call this safe
Response field finish_reason is no longer guaranteed
Producer-side tools call this non-breaking. For a consumer it is a null dereference on an unknown future date.
CreateCompletionResponse.choices[].finish_reason · reachable from 1 operation
Code that breaks
```
// response.choices[0].finish_reason may now be absent or null
const finish_reason = response.choices[0].finish_reason ?? fallback;
```

4 new response fields

RunGraderResponse.metadata.token_usage.completion_tokens
RunGraderResponse.metadata.token_usage.cached_tokens
RunGraderResponse.metadata.token_usage.total_tokens
RunGraderResponse.metadata.token_usage.prompt_tokens

OpenAI2026-09-29 · c25ff3f09 additive

2 new response fields

EnvironmentResourceOpenaiHosted.desktop
EnvironmentTemplateResource.desktop

7 new request properties

NetworkPolicyParam.blocked_domains
EnvironmentParamOpenaiHosted.network.blocked_domains
CreateEnvironmentTemplateParams.desktop
UpdateEnvironmentTemplateParams.network.blocked_domains
UpdateEnvironmentTemplateParams.desktop
CreateEnvironmentTemplateParams.network.blocked_domains
EnvironmentParamOpenaiHosted.desktop

OpenAI2026-09-29 · a810627e1 breaking

Breakingdirection flip: their tools call this safe
value can now return "gpt-6.1-sol"
Producer-side tools call this additive. It breaks exhaustive switches, strict parsers and generated client enums.
can now return "gpt-6.1-sol"
2 places: BetaModelIdsShared, ModelIdsShared
Code that breaks
```
switch (response) {
  // existing branches …
  // no branch for "gpt-6.1-sol"
  default:
    throw new Error("unexpected value");
}
```

OpenAI2026-09-29 · a1514fba2 additive

Additive
Response field container_size added
No action needed unless you validate responses against a closed schema.
EnvironmentResourceOpenaiHosted.container_size · reachable from 5 operations
Additive
Request property container_size added
No action needed unless it is required.
EnvironmentParamOpenaiHosted.container_size · reachable from 1 operation