Responses API

The Responses API is designed for grounded answers, tool use, and rich streaming. It supports annotations you can use to render citations and tool outputs in your UI.

Endpoint

• URL: https://api.nouswise.ai/v1/responses
• Auth: Bearer API key in Authorization header
• Streaming: Supported via Server‑Sent Events (SSE)

Request shape

At minimum provide a model, input messages.

cURL

curl --request POST \
  --url https://api.nouswise.ai/v1/responses \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "standard",
    "input": [
      {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "Summarize the attached files"}]}
    ],
    "stream": false,
  }'

Python

from openai import OpenAI
import os

client = OpenAI(api_key=os.environ.get("NW_API_KEY"), base_url="https://api.nouswise.ai/v1")

resp = client.responses.create(
    model="standard",
    input=[
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Give a concise, referenced answer about quarterly revenue.",
                }
            ],
        }
    ],
    stream=False
)

print(resp)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.NW_API_KEY, baseURL: "https://api.nouswise.ai/v1" });

const resp = await client.responses.create({
  model: "standard",
  input: [
    { type: "message", role: "user", content: [{ type: "input_text", text: "Summarize the attached files" }] },
  ],
  stream: false
});

console.log(resp);

Streaming (SSE)

Set stream=true to receive a stream of events you can render progressively.

cURL

curl --request POST \
  --url https://api.nouswise.ai/v1/responses \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "standard",
    "input": [
      { "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "Outline the key risks and their mitigations." }] }
    ],
    "stream": true
  }'

Python

from openai import OpenAI
import os

client = OpenAI(api_key=os.environ.get("NW_API_KEY"), base_url="https://api.nouswise.ai/v1")

with client.responses.stream(
    model="standard",
    input=[
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Outline the key risks and their mitigations.",
                }
            ],
        }
    ]
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="")
    final = stream.get_final_response()

JavaScript

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.NW_API_KEY, baseURL: "https://api.nouswise.ai/v1" });

const stream = await client.responses.stream({
  model: "standard",
  input: [
    { type: "message", role: "user", content: [{ type: "input_text", text: "Outline the key risks and their mitigations." }] },
  ]
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}
const final = await stream.finalResponse();

Common event types include:

• response.output_item.added, response.content_part.added
• response.output_text.delta, response.output_text.done
• response.reasoning_text.delta, response.reasoning_text.done
• response.file_search_call.* and response.mcp_call.* when tools are in use
• response.completed or response.failed

Context messages

You can pass background material as input_text with name set to "context". This hints that the content is a reference material and enables annotations to help you highlight where facts came from.

Model will then base its response on the content you marked as context and cites them back using annotations.

Example message:

{
  "type": "message",
  "role": "user",
  "name": "context",
  "content": [
    { "type": "input_text", "text": "Excerpt from Q2 report...", "name": "context" }
  ]
}

You can also include file urls as context. Nouswise will ground the response based on the files provided.

{
    "role": "user",
    "content": [
        {
            "type": "input_text",
            "text": "Analyze the letter and provide a summary of the key points."
        },
        {
            "type": "input_file",
            "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf"
        }
    ]
}

or the file in base64 format as follows:

{
    "role": "user",
    "content": [
        {
            "type": "input_text",
            "text": "Analyze the letter and provide a summary of the key points."
        },
        {
            "type": "input_file",
            "file_data": "data:application/pdf;base64,JVB..."
        }
    ]
}

Structured JSON output

Request structured responses using a JSON Schema. The model will attempt to follow the schema in its output.

{
  "model": "standard",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "KPIReport",
      "description": "Quarterly KPI summary",
      "schema": {
        "type": "object",
        "properties": {
          "kpis": {
            "type": "array",
            "items": { "type": "object", "properties": { "name": {"type":"string"}, "value": {"type":"number"} }, "required": ["name", "value"] }
          }
        },
        "required": ["kpis"]
      },
      "strict": false
    }
  },
  "input": [ { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "Produce a short KPI list."}] } ],
  "stream": false
}

Errors

• 401 Unauthorized: missing or invalid API key
• 400 Bad Request: invalid input shape or parameters
• 429 Rate limited: retry with backoff
• 5xx: transient errors; retry with jitter