Public API request and transport schemas

This file does not contain the API logic itself. Instead, it acts like the reception desk for the whole codex-api crate, which is Rust’s name for a library package. First, it declares the internal modules, such as authentication, endpoints, files, images, search, streaming events, and telemetry. These modules contain the real code for talking to API services and shaping requests and responses.

Then it re-exports selected items from those modules. A re-export means outside code can import important pieces from codex_api directly, without needing to know the exact internal file where each one lives. For example, callers can get clients like ResponsesClient, authentication types like AuthProvider, request and response data types, image and search types, telemetry helpers, and transport errors from this single public surface.

This matters because it keeps the rest of the project from depending on the library’s private folder layout. If the internal modules are like rooms in a building, this file is the signboard in the lobby: it tells users which doors are available and gives them stable names to use. Without it, callers would either be unable to reach these API tools or would need to know too much about the library’s internals.

This file is mostly a set of plain data shapes for conversations with the model service. Think of it like a stack of standard forms: one form for creating a response, one for summarizing memory, one for describing reasoning settings, one for text-output controls, and one for events that can arrive while a streamed answer is in progress. Without these shared shapes, different parts of the code would have to guess how to format requests and interpret replies, which would make API calls fragile.

The file defines request bodies for normal HTTP-style Responses API calls and for WebSocket response creation. A WebSocket is a long-lived connection where client and server can keep sending messages to each other. It also defines ResponseEvent, which is the set of meaningful things the server can report during a response: text arriving in pieces, tool-call input arriving in pieces, completion, token usage, rate limits, server-selected model details, and moderation or verification information.

A few helper pieces turn local configuration into API-ready fields. For example, verbosity settings are converted into OpenAI’s expected names, optional JSON schema output formatting is packaged into the text field, and trace headers are copied into client metadata so a request can be followed across systems. Finally, ResponseStream wraps an internal message receiver and exposes it as a standard asynchronous stream, so callers can consume model events one at a time as they arrive.

fn from(v: VerbosityConfig) -> Self

fn from(request: &ResponsesApiRequest) -> Self

fn response_create_client_metadata(
    client_metadata: Option<HashMap<String, String>>,
    trace: Option<&W3cTraceContext>,
) -> Option<HashMap<String, String>>

fn create_text_param_for_request(
    verbosity: Option<VerbosityConfig>,
    output_schema: &Option<Value>,
    output_schema_strict: bool,
) -> Option<TextControls>

fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>

When software talks to an external API, many different failures can happen. The network might fail, the server might reject the request, the user might run out of quota, or the response stream might break halfway through. This file gathers those possibilities into one enum called ApiError, which is like a labeled set of possible failure reasons.

That matters because callers do not need to juggle many unrelated error shapes. They can receive one ApiError and then decide what to do: retry later, show a clear message, stop because the request is invalid, or report that the context window was too large. Some variants carry extra detail, such as an HTTP status code, a human-readable message, or an optional retry delay. An HTTP status code is the numeric result code from a web server, such as 404 or 500.

The file also connects lower-level errors to this API-level error. For example, a TransportError from the HTTP client can automatically become an ApiError::Transport, and a RateLimitError can become ApiError::RateLimit. In everyday terms, this file is the translation table that turns many kinds of trouble into a common language the API layer understands.

fn from(err: RateLimitError) -> Self

A realtime WebSocket session is a live back-and-forth connection, often carrying audio, text, session settings, and tool results. This file is the local “dictionary” for that conversation: it names the kinds of messages the server can send, the session options it can describe, and the event types it can receive from the shared protocol crate.

Most of the file is made of Rust structs and enums that are turned into JSON with serde, a library that converts Rust data into JSON and back. For example, it describes messages like “append this audio,” “create a response,” “update the session,” or “add this conversation item.” It also describes session details such as the model, instructions, voice, audio format, transcription settings, noise reduction, turn detection, and function tools. The serde annotations make sure the JSON field names match what the realtime API expects.

The file also supports two incoming event formats: an older v1 parser and a newer realtime v2 parser. The small parsing function acts like a switchboard. Given raw text from the WebSocket and the chosen protocol version, it forwards the text to the matching parser. Without this file, other realtime WebSocket code would lack a clear, consistent set of message shapes and would have to duplicate version-selection logic.

fn parse_realtime_event(
    payload: &str,
    event_parser: RealtimeEventParser,
) -> Option<RealtimeEvent>

This file is a collection of data types for working with images through an API. It does not perform the network call itself. Instead, it defines exactly what information must be packaged up before sending a request, and what information the program should expect back afterward.

There are two main request types. ImageGenerationRequest is used when asking the API to create a new image from a text prompt. ImageEditRequest is used when asking the API to edit one or more existing images, so it includes a list of image URLs as well as a prompt. Both request types include options such as background style, model name, number of images, quality, and size.

Several fields are optional. The serde(skip_serializing_if = "Option::is_none") setting means those fields are left out of the outgoing message when they are not set. In everyday terms, the program does not send blank boxes on the form.

The response types describe what comes back: when the image was created, the returned image data, and optional details such as background, quality, and size. The image itself is represented as base64 text, which is a way of safely carrying binary image data inside plain text formats like JSON.

This file is mostly a set of data definitions. It does not perform searches itself. Instead, it describes the exact messages that other parts of the system can send to a search service, and the exact form of the answer they expect back. Think of it like a standardized order form: one part of the program fills it out, another part reads it, and both sides avoid guessing what each field means.

The central type is SearchRequest. It includes an id, the model to use, optional reasoning settings, optional input, optional commands, optional search settings, and an optional output limit. The input can be either plain text or a list of previous response items. The commands section is broad: it can ask for normal search queries, image searches, opening pages, clicking links, finding text, taking PDF screenshots, looking up finance data, weather, sports, or time.

The file also defines settings that guide how search should behave, such as approximate user location, how much search context to gather, allowed or blocked domains, image result limits, and whether outside web access is allowed. Many fields are optional and are skipped when converted to JSON if they are not set, which keeps API messages small and clear.

Without this file, the rest of the project would lack a clear, typed agreement for search-related API traffic. That would make it much easier to send malformed requests or misunderstand responses.