Responses API Integration

Responses API is suitable for Agents, tool calling, structured input, and applications requiring unified event streams. Coding tools like Codex typically also rely on this type of interface.

In CoreRouter, /v1/responses is not a universal entry point for all chat models. It requires the current Model ID to be bound to models or channels that support the Responses protocol. Regular /v1/chat/completions availability does not guarantee /v1/responses availability.

Interface Information

Configuration	Value
Endpoint	https://api.corerouter.cloud/v1/responses
Header	Authorization: Bearer sk-...
Required Fields	model, input
Common Capabilities	Text generation, streaming, tool calling, background response querying
Model Requirement	Model ID from console that explicitly supports Responses / Coding Agent

Before integrating Codex or Agents, validate /v1/responses separately with the same Model ID. If it returns 404, model not found, or protocol not supported, switch to a model that supports Responses.

Minimal Request

export COREROUTER_API_KEY="sk-xxxxxxxxxxxxxxxx"

curl https://api.corerouter.cloud/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "responses-model-id",
    "input": "Introduce CoreRouter in three sentences."
  }'

Streaming Output

curl https://api.corerouter.cloud/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "responses-model-id",
    "input": "Explain what HTTP streaming responses are step by step.",
    "stream": true
  }'

Streaming typically returns Server-Sent Events. Different SDKs parse events differently; when troubleshooting, use curl first to observe raw events.

Structured Input

curl https://api.corerouter.cloud/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "responses-model-id",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Rewrite this to be more suitable for product documentation: configure key and you can use it."
          }
        ]
      }
    ]
  }'

Tool Calling

curl https://api.corerouter.cloud/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "responses-model-id",
    "input": "What should I wear in Beijing right now?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Query city weather",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

Tool calling availability depends on model capabilities. For Agents, prioritize models marked as supporting Tool Calling, Streaming, and Coding Agent in the console.

Query Background Response

If your calling pattern returns a background task ID, query with:

curl https://api.corerouter.cloud/v1/responses/resp_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $COREROUTER_API_KEY"

Responses Context Compression

/v1/responses/compact is an advanced interface for Agents or coding tools to compress historical context, not a regular chat replacement. It requires the current channel to support Responses compression capability; regular Chat Completions availability does not guarantee this interface works.

curl https://api.corerouter.cloud/v1/responses/compact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "responses-model-id",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "Please compress this conversation context."}
        ]
      }
    ],
    "instructions": "Retain task objectives, constraints, and incomplete items.",
    "previous_response_id": "resp_xxxxxxxxxxxxxxxx",
    "service_tier": "auto"
  }'

Field	Required	Description
model	Yes	Model ID from console that supports Responses compression.
input	No	Input to compress, can be string or Responses input array.
instructions	No	Specify focus points to retain during compression.
previous_response_id	No	Associate with previous Responses response.
prompt_cache_key	No	Cache key when client uses prompt caching.
prompt_cache_options	No	Prompt cache options; effectiveness depends on channel.
prompt_cache_retention	No	Prompt cache retention policy.
service_tier	No	Service tier option; effectiveness depends on channel.

Some clients may also send compatible fields like tools, reasoning, text. The gateway can parse these fields for client compatibility but won't guarantee they're all forwarded upstream; don't use the compression interface as a full Responses creation interface.

Common Issues

• 404: Confirm Base URL is https://api.corerouter.cloud/v1 and current Model ID is bound to models or channels that support Responses.
• 400: Confirm request body includes model and input, and input format meets current SDK requirements.
• /v1/responses/compact returns not supported: Current channel doesn't have Responses compression capability; switch to a Model ID or channel that supports it.
• 401: Check API Key and Authorization: Bearer ....
• Agent has no tool calling: Switch to a model that supports Tool Calling / Coding Agent and test again.