Skip to main content
Clients must send a single initialize request per transport connection before invoking any other method, then acknowledge with an initialized notification.

​
Initialization Handshake

The server returns the user agent string it will present to upstream services. Subsequent requests issued before initialization receive a "Not initialized" error, and repeated initialize calls on the same connection receive an "Already initialized" error.
1

Send initialize request

Send an initialize request with your client metadata.
2

Receive response

The server responds with initialization details.
3

Send initialized notification

Acknowledge with an initialized notification.

​
Request

​
Method

initialize

​
Parameters

​
clientInfo
object
required
Client identification information
​
capabilities
object
Client capability flags

​
Response

​
userAgent
string
User agent string the server will present to upstream services

​
Examples

​
Basic Initialization

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

​
With Experimental API & Notification Opt-out

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true,
      "optOutNotificationMethods": [
        "codex/event/session_configured",
        "item/agentMessage/delta"
      ]
    }
  }
}

​
Experimental API

Some app-server methods and fields are gated behind an experimental capability with no backwards-compatible guarantees.
Stable surface only (default): No opt-in, no experimental methods/fields exposed.Experimental surface: Set capabilities.experimentalApi: true during initialization.

​
Without Opt-in

If a request uses an experimental method or field without opting in, the server rejects it with a JSON-RPC error: 
<descriptor> requires experimentalApi capability
Examples:
  • mock/experimentalMethod (method-level gate)
  • thread/start.mockExperimentalField (field-level gate)

​
Schema Generation

Generate stable vs experimental schemas: 
# Stable-only output (default)
codex app-server generate-ts --out DIR
codex app-server generate-json-schema --out DIR

# Include experimental API surface
codex app-server generate-ts --out DIR --experimental
codex app-server generate-json-schema --out DIR --experimental

​
Notification Opt-out

Clients can suppress specific notifications per connection by sending exact method names in capabilities.optOutNotificationMethods. Behavior:
  • Exact-match only: item/agentMessage/delta suppresses only that method
  • Unknown method names are ignored
  • Applies to both legacy (codex/event/*) and v2 (thread/*, turn/*, item/*) notifications
  • Does not apply to requests/responses/errors
Examples:
  • Opt out of legacy session setup event: codex/event/session_configured
  • Opt out of streamed agent text deltas: item/agentMessage/delta

​
Next Steps

Threads

Start or resume a conversation thread