Skip to content

docs: add README guidance for experimental APIs #1123

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

Open
Rohan5commit wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add README guidance for experimental APIs #1123

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
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,25 @@ It is generated from our [OpenAPI specification](https://github.com/openai/opena

To call the OpenAI REST API, you will need an API key. To obtain one, first [create a new OpenAI account](https://platform.openai.com/signup) or [log in](https://platform.openai.com/login). Next, navigate to the [API key page](https://platform.openai.com/account/api-keys) and select "Create new secret key", optionally naming the key. Make sure to save your API key somewhere safe and do not share it with anyone.

### Experimental APIs

Comment on lines +44 to +45

Copilot AI Apr 25, 2026

Copy link

Choose a reason for hiding this comment

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

The README Table of Contents includes “Prerequisites” and then “Install the NuGet package”, but this new “Experimental APIs” subsection isn’t listed. Consider adding it under “Getting started” in the TOC so the new guidance is discoverable.

Copilot uses AI. Check for mistakes.
Some APIs in this library are marked with `[Experimental]` while the corresponding service surface is still evolving. When you use one of these types or members, the compiler emits a warning code so you can opt in deliberately.

@jsquire jsquire Apr 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

... service surface is still evolving is not quite correct. The intent of [Experimental] is to denote that the client API surface is evolving. It has no connection to the state of the service.

If you'd be so kind, can we revise a bit to something like:

What's Experimental used for?

Experimental is used to designate that the client API surface is still undergoing iteration and should be expected to change, potentially in ways that are breaking. This may include both compile-time and behavioral changes in the client API. To acknowledge this risk, .NET requires that you opt-into experimental features by suppressing the warning in whatever way you prefer.

Once a client API reaches a stable state (no longer tagged experimental) then it is covered by a strong backwards compatibility guarantee. We will not make binary breaking changes and will only make disruptive behavioral changes when there is a critical need, such as patching a security vulnerability.

What Experimental isn't

  • Client use of Experimental does not communicate any message about the feature in the REST API. The OpenAI platform docs are the authoritative source for that information.

  • Client use of Experimental does not communicate any message about the quality or reliability of the feature. We believe that all client features that we release meet our quality bar and are safe and reliable to use in production environments.

  • Client use of Experimental does not communicate any message about supportability of the feature. We support all released client features when used with the official OpenAI service.

Additional context


| Warning code | Examples of affected API areas |
| --- | --- |
| `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area |
| `OPENAI002` | Realtime session types and session options |
Comment thread
jsquire marked this conversation as resolved.
Comment on lines +50 to +51

Copilot AI Apr 25, 2026

Copy link

Choose a reason for hiding this comment

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

The OPENAI001 row lists “realtime client entry points”, but RealtimeClient/OpenAIClient.GetRealtimeClient() are tagged [Experimental("OPENAI002")] (e.g., src/Generated/RealtimeClient.cs:15, src/Custom/OpenAIClient.cs:327). This is likely to mislead users about which warning they need to suppress; consider moving realtime client/entry points to the OPENAI002 row (or removing realtime from OPENAI001).

Suggested change
| `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area |
| `OPENAI002` | Realtime session types and session options |
| `OPENAI001` | Assistants, vector stores, batches, evals, and other preview client surface area |
| `OPENAI002` | Realtime client entry points, realtime session types, and session options |

Copilot uses AI. Check for mistakes.

If your project treats warnings as errors, experimental APIs can fail the build until you suppress the relevant warning in the narrowest possible scope:
Comment on lines +48 to +53

Copilot AI Apr 25, 2026

Copy link

Choose a reason for hiding this comment

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

This section enumerates experimental warning codes, but the public API also uses other [Experimental] diagnostic IDs like SCME0002 (e.g., settings/DI entry points in src/Custom/*ClientSettings.cs). Either include these in the table or clarify that the table is specifically for OpenAI-defined OPENAI### warnings so users aren’t confused when they encounter SCME0002.

Suggested change
| Warning code | Examples of affected API areas |
| --- | --- |
| `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area |
| `OPENAI002` | Realtime session types and session options |
If your project treats warnings as errors, experimental APIs can fail the build until you suppress the relevant warning in the narrowest possible scope:
The table below lists the OpenAI-defined experimental warning codes (`OPENAI###`) used by this library. Some public APIs may also carry other `[Experimental]` diagnostic IDs from shared infrastructure or supporting packages, such as `SCME0002`.
| Warning code | Examples of affected API areas |
| --- | --- |
| `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area |
| `OPENAI002` | Realtime session types and session options |
If your project treats warnings as errors, experimental APIs can fail the build until you suppress the relevant warning code for the API you are using in the narrowest possible scope:

Copilot uses AI. Check for mistakes.

```csharp
#pragma warning disable OPENAI001
AssistantClient assistantClient = new(Environment.GetEnvironmentVariable("OPENAI_API_KEY"));
#pragma warning restore OPENAI001
```

Prefer suppressing only the specific warning code around the experimental call site so stable APIs continue surfacing new warnings normally.

### Install the NuGet package

Add the client library to your .NET project by installing the [NuGet](https://www.nuget.org/) package via your IDE or by running the following command in the .NET CLI:
Expand Down
Loading