Codex Search capability
The Codex Search transport capability in the Responses workflow.
A Responses capability, not a new API family
When Codex uses the OpenAI Responses entry, it may trigger Search as needed. 8788 exposes a thin transport operation for client compatibility, but does not add a top-level protocol, a separate model product, or a separate billing system.
When it is used
Users normally should not call this endpoint directly. Codex starts Search when it needs retrieval, then continues the original Responses session. The Search request depends on client-generated session context and call identifiers; do not hand-build a Search response or function_call_output outside that session.
Transport entry
| Purpose | Method and path | Authentication |
|---|---|---|
| Codex Search capability | POST /v1/alpha/search or POST /v1/alpha/search/ | Authorization: Bearer <user API key> |
The bare /alpha/search path is not public. Keep the Base URL as https://dingjiai.com/v1; the client sends the request according to its own path rules.
Request and response boundaries
- The gateway reads
modelto reuse the Responses model product and upstream candidates; it does not maintain a separate Search capability switch. - Current Codex requests commonly contain
id,model,input,commands.search_query,settings, andmax_output_tokens; query text is incommands.search_query[].q. - The request body is forwarded according to the upstream contract. The gateway does not remove
prompt_cache_*or unknown fields and does not translate it into a Responses request. - Upstream status, Content-Type, and body are returned transparently; Alpha responses do not use the normal Responses
usageparser. - Search reuses Responses upstream candidates by default; parameter support remains an upstream contract. A clear upstream 404/405 triggers failover within the Search operation only and does not affect ordinary Responses.
Billing
Search is a capability call inside a Responses workflow. It does not create separate usage, a reservation, or a ledger charge. The following Responses request is settled by the normal Responses usage rules. Upstream resource consumption does not change 8788's user billing contract; do not invent Search token estimates or fixed fees.
Common results
| Symptom | Meaning |
|---|---|
404 (bare /alpha/search) | The path is outside the public contract; use /v1/alpha/search. |
400 upstream_invalid_request | The upstream rejected the body or session context; let Codex manage the call instead of translating it into another protocol. |
Upstream 404/405, then another candidate is tried | The candidate may not expose the Alpha endpoint; this failover is scoped to Search and does not mark ordinary Responses unavailable. |
502 upstream_not_configured | No eligible upstream candidate is enabled for the Responses model. |
| Search succeeds without a separate charge | Expected; the following Responses request is settled by normal Responses usage. |
Keep the X-Request-Id response header when troubleshooting, then use request_id troubleshooting to inspect the operation, attempts, and subsequent Responses settlement.
The admin upstream test runs the normal probe for the selected Responses entry/model; it is not a Search acceptance test. Validate Search with a real Codex request and its recorded attempts.
Last updated on