# Responses API

{% hint style="warning" %}
The Responses API is available exclusively on the **new gateway**. You must use the base URL below — it is not available on the standard `api.parasail.io` gateway.
{% endhint %}

## Base URL

```
https://api-webflux.saas.parasail.io/v1
```

Use your existing Parasail API key for authentication. The only difference from the standard API is the base URL.

## Requirements

| Requirement           | Details                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Base URL**          | `https://api-webflux.saas.parasail.io/v1` (new gateway only)                                                                         |
| **`store` parameter** | Must be set to `false` on every request. The gateway does not support server-side state storage. Omitting this will return an error. |
| **Authentication**    | `Authorization: Bearer <PARASAIL_API_KEY>` (same key as the standard API)                                                            |

## Compatibility

The table below shows which Responses API features are supported on the new gateway.

| Feature                                    | Supported | Notes                                                         |
| ------------------------------------------ | --------- | ------------------------------------------------------------- |
| Single-turn completions                    | ✅         |                                                               |
| Multi-turn conversations                   | ✅         | Pass full conversation history in `input`                     |
| Reasoning / thinking                       | ✅         | Reasoning content returned automatically for reasoning models |
| Function / tool calling                    | ✅         | Define tools with `tools` parameter                           |
| Parallel tool calls                        | ✅         | Model may issue multiple tool calls in one turn               |
| `tool_choice` (`auto`, `required`, `none`) | ✅         |                                                               |
| `store: true` (server-side state)          | ❌         | Must set `store: false`                                       |
| `previous_response_id` (stateful chaining) | ❌         | Not supported — pass full history in `input` instead          |
| Streaming                                  | ✅         | Use `stream: true`                                            |
| Web search tool                            | ❌         | Not currently available                                       |
| File search tool                           | ❌         | Not currently available                                       |
| Computer use tool                          | ❌         | Not currently available                                       |

## Quick Start

### Python (OpenAI SDK)

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api-webflux.saas.parasail.io/v1",
    api_key="<PARASAIL_API_KEY>"
)

response = client.responses.create(
    model="parasail-kimi-k25-elicit",
    store=False,
    input="Explain the difference between TCP and UDP in two sentences."
)

print(response.output_text)
```

### cURL

```bash
curl -s https://api-webflux.saas.parasail.io/v1/responses \
  -H "Authorization: Bearer $PARASAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "parasail-kimi-k25-elicit",
    "store": false,
    "input": "Explain the difference between TCP and UDP in two sentences."
  }'
```

## Multi-Turn Conversations

Since `previous_response_id` is not supported, you maintain conversation history by passing the full message array in `input`. Each turn appends the assistant's reply and the next user message.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api-webflux.saas.parasail.io/v1",
    api_key="<PARASAIL_API_KEY>"
)

# Turn 1
response = client.responses.create(
    model="parasail-kimi-k25-elicit",
    store=False,
    input=[
        {"role": "user", "content": "I'm planning a trip to Tokyo. What should I see on day 1?"}
    ]
)
turn1_text = response.output_text
print("Turn 1:", turn1_text)

# Turn 2 — pass the full history
response = client.responses.create(
    model="parasail-kimi-k25-elicit",
    store=False,
    input=[
        {"role": "user", "content": "I'm planning a trip to Tokyo. What should I see on day 1?"},
        {"role": "assistant", "content": turn1_text},
        {"role": "user", "content": "What about day 2? Suggest different areas."}
    ]
)
print("Turn 2:", response.output_text)
```

## Function Calling (Agentic)

The Responses API supports tool definitions and multi-step agentic loops where the model calls functions and you return results.

### Define Tools

```python
tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "default": "celsius"
                }
            },
            "required": ["city"]
        }
    }
]
```

### Agentic Loop

```python
from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api-webflux.saas.parasail.io/v1",
    api_key="<PARASAIL_API_KEY>"
)

tools = [...]  # as defined above

def handle_tool_call(name, arguments):
    """Your application logic — call real APIs, databases, etc."""
    args = json.loads(arguments)
    if name == "get_weather":
        return json.dumps({"city": args["city"], "temperature": 22, "condition": "sunny"})
    return json.dumps({"error": "unknown function"})

# Initial request
response = client.responses.create(
    model="parasail-kimi-k25-elicit",
    store=False,
    tools=tools,
    input=[{"role": "user", "content": "What's the weather in Tokyo?"}]
)

# Agentic loop — keep going until the model stops calling tools
while response.output:
    tool_calls = [item for item in response.output if item.type == "function_call"]
    if not tool_calls:
        break  # Model produced a final text response

    # Build input for next turn: previous output + tool results
    next_input = list(response.output)
    for tool_call in tool_calls:
        result = handle_tool_call(tool_call.name, tool_call.arguments)
        next_input.append({
            "type": "function_call_output",
            "call_id": tool_call.call_id,
            "output": result
        })

    response = client.responses.create(
        model="parasail-kimi-k25-elicit",
        store=False,
        tools=tools,
        input=next_input
    )

# Print final response
print(response.output_text)
```

The model may call multiple tools in parallel within a single turn. Always provide results for every `function_call` before sending the next request.

## Important Notes

* **Always set `store: false`.** Every request must include `"store": false`. The new gateway does not support server-side response storage, and omitting this parameter will result in an error.
* **No stateful chaining.** The `previous_response_id` field is not supported. Manage conversation history client-side by passing the full `input` array each turn.
* **Same API key.** Your existing Parasail API key works on both gateways. No separate key is needed.
* **Model availability.** Not all models are available on the new gateway. Use the `/v1/models` endpoint to check:

```bash
curl -s https://api-webflux.saas.parasail.io/v1/models \
  -H "Authorization: Bearer $PARASAIL_API_KEY"
```