Guide

Responses API

The Responses API lets Cadreen handle the hard parts — governance, memory, tool execution — so you don't have to. It's the recommended endpoint for all new projects.

What is the Responses API?

A single endpoint that does what Chat Completions does — plus governance, memory, tool execution, and conversation state. You send a request, Cadreen decides which model to use, applies your policies, executes any tools, and returns a typed response.

Think of it as the difference between calling a model directly and calling an intelligence layer. The model is one component. Cadreen is the system around it.

Note

New to Cadreen? Start with How to Connect Cadreen for base URL and API key setup. Then come back here.

Quick start

POST/api/v1/cadreen/responses

Send a simple request. Cadreen handles the rest.

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cadreen.com/api/v1/cadreen",
    api_key="sk_cadreen_..."
)

response = client.responses.create(
    model="cadreen",
    input="What connectors do I have?",
    instructions="You are a helpful AI assistant."
)
print(response.output_text)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.cadreen.com/api/v1/cadreen",
  apiKey: "sk_cadreen_...",
});

const response = await client.responses.create({
  model: "cadreen",
  input: "What connectors do I have?",
  instructions: "You are a helpful AI assistant.",
});
console.log(response.output_text);

curl

curl -X POST https://api.cadreen.com/api/v1/cadreen/responses \
  -H "Authorization: Bearer sk_cadreen_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cadreen",
    "input": "What connectors do I have?",
    "instructions": "You are a helpful AI assistant."
  }'

Note

The model field is required but ignored. Cadreen decides which model to use based on your request, policies, and workspace configuration. You can pass any string — it won't affect the result.

How it compares to Chat Completions

Both endpoints generate text. The difference is what happens around it.

QuestionChat CompletionsResponses

How do you send a prompt?Build a messages[] array with role objectsSend a string or list. System guidance goes in instructions.

How do you read the answer?choices[0].message.content — one stringoutput_text — or iterate output[] for structured items

How do you have a conversation?You store and resend the full message history every timePass the previous response's ID. Cadreen loads the context.

What about tools?Tool calls come back inside the messageTool calls come back as typed items. Multiple tools in one request.

What about reasoning?BasicRich reasoning. Can be kept private with encrypted items.

Note

Use Responses for new projects. Chat Completions still works — your existing integrations won't break. But Responses gives you better performance, simpler state management, and built-in tools.

When to use which

Use Responses when

You're starting a new project

You need the AI to remember previous turns

You want Cadreen to use your tools (file access, databases, APIs)

You need structured JSON output

You want Cadreen to manage conversation state for you

Stick with Completions when

You have an existing integration that works

You need multiple parallel answers from the same prompt

You have strict data retention requirements

What you send

FieldTypeRequiredWhat it does

modelstringYesRequired by clients, ignored by Cadreen — it decides which model to use

inputstring | arrayYesThe user's message — a string or list of messages and tool results

instructionsstringNoSystem-level guidance. Becomes the system message.

toolsarrayNoTool definitions. Cadreen checks your policies before calling any of them.

tool_choicestring | objectNoControl which tool is called: auto, none, required, or a specific tool

previous_response_idstringNoContinue a conversation — pass the previous response's ID

storeboolNoSave the response. Defaults to true.

streamboolNoGet text as it's generated, not all at once

max_output_tokensintNoMax tokens in the response. Defaults to 4096.

textobjectNoStructured output config. Forces JSON matching a schema.

What you get back

Every response has a unique ID, an output array with structured items, and a ready-to-use text helper.

Response

{
  "id": "resp_68af4030592c81938ec0a5fbab4a3e9f",
  "object": "response",
  "output": [
    {
      "id": "msg_68af40337e58819392e935fb",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "You have 3 active connectors: GitHub, Slack, and Linear."
        }
      ],
      "role": "assistant"
    }
  ],
  "output_text": "You have 3 active connectors: GitHub, Slack, and Linear.",
  "usage": {
    "input_tokens": 42,
    "output_tokens": 18,
    "total_tokens": 60
  },
  "store": true
}

FieldWhat it tells you

idUnique ID for this response (resp_...)

outputStructured items — messages, tool calls, reasoning

output_textThe full text answer, ready to use

usageHow many tokens you used

storeWhether Cadreen saved this response

Get text as it arrives

Set stream: true to receive text in real time. Useful for chat UIs and long responses where you don't want the user staring at a blank screen.

Python

stream = client.responses.create(
    model="cadreen",
    input="Tell me about my workspace",
    stream=True
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Note

Cadreen sends keepalive pings every 15 seconds during long operations. You won't lose the connection.

Let it use your tools

Define tools just like Chat Completions. Cadreen checks your governance policies before calling any of them.

Python

response = client.responses.create(
    model="cadreen",
    input="Read main.go and summarize it",
    tools=[{
        "type": "function",
        "function": {
            "name": "read",
            "description": "Read a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "File path"}
                },
                "required": ["path"]
            }
        }
    }]
)

Note

Cadreen returns tool calls as structured items. You execute them and send the result back. See the Tool Calling guide for the full flow.

Remember conversations

Chat Completions requires you to store and resend the full message history. Responses gives you three options:

previous_response_id — Pass the previous response's ID. Cadreen loads the context automatically. Send instructions again on each request — they don't carry over.

Manual context — Pass prior output items back in the input array. You control exactly what the model sees.

Conversations API — Use a persistent conversation object. Cadreen manages the full history.

previous_response_id

# Turn 1
res1 = client.responses.create(
    model="cadreen",
    input="What is the capital of France?",
    instructions="You are a geography expert.",
    store=True
)
print(res1.output_text)  # "The capital of France is Paris."

# Turn 2 — Cadreen remembers the context
res2 = client.responses.create(
    model="cadreen",
    input="And its population?",
    instructions="You are a geography expert.",
    previous_response_id=res1.id,
    store=True
)
print(res2.output_text)  # "Paris has approximately 2.1 million people..."

What's different from OpenAI

Tool governance — Every tool call is checked against your rules before execution

Memory — 4 types of persistent memory — what it knows, what happened, how to do things, and past fixes

Intelligence traces — Full reasoning breakdown in every response — what it understood, what it checked, what it did

Model selection — Cadreen picks the best model for your request. The model field is required but ignored.

Self-healing — When tool calls fail, Cadreen figures out why, fixes the arguments, and retries

Note

Internal reasoning is stripped. You never see the model's chain-of-thought. The intelligence trace gives you a structured breakdown instead.

What doesn't work yet

The model field is required by clients but ignored — Cadreen decides which model to use

temperature, top_p, reasoning are accepted but not passed to the model — Cadreen controls generation internally

previous_response_id is defined but not wired — use manual context passing for now

Structured output (text.format) is accepted but not enforced — parse output defensively

Built-in tools (web search, file search, code interpreter) are not yet available

Note

Next: Responses API Cookbook — step-by-step recipes you can copy and paste.

from openai import OpenAI client = OpenAI( base_url="https://api.cadreen.com/api/v1/cadreen", api_key="sk_cadreen_..." ) response = client.responses.create( model="cadreen", input="What connectors do I have?", instructions="You are a helpful AI assistant." ) print(response.output_text)

import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.cadreen.com/api/v1/cadreen", apiKey: "sk_cadreen_...", }); const response = await client.responses.create({ model: "cadreen", input: "What connectors do I have?", instructions: "You are a helpful AI assistant.", }); console.log(response.output_text);

curl -X POST https://api.cadreen.com/api/v1/cadreen/responses \ -H "Authorization: Bearer sk_cadreen_..." \ -H "Content-Type: application/json" \ -d '{ "model": "cadreen", "input": "What connectors do I have?", "instructions": "You are a helpful AI assistant." }'

{ "id": "resp_68af4030592c81938ec0a5fbab4a3e9f", "object": "response", "output": [ { "id": "msg_68af40337e58819392e935fb", "type": "message", "status": "completed", "content": [ { "type": "output_text", "text": "You have 3 active connectors: GitHub, Slack, and Linear." } ], "role": "assistant" } ], "output_text": "You have 3 active connectors: GitHub, Slack, and Linear.", "usage": { "input_tokens": 42, "output_tokens": 18, "total_tokens": 60 }, "store": true }

stream = client.responses.create( model="cadreen", input="Tell me about my workspace", stream=True ) for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True)

response = client.responses.create( model="cadreen", input="Read main.go and summarize it", tools=[{ "type": "function", "function": { "name": "read", "description": "Read a file", "parameters": { "type": "object", "properties": { "path": {"type": "string", "description": "File path"} }, "required": ["path"] } } }] )

# Turn 1 res1 = client.responses.create( model="cadreen", input="What is the capital of France?", instructions="You are a geography expert.", store=True ) print(res1.output_text) # "The capital of France is Paris." # Turn 2 — Cadreen remembers the context res2 = client.responses.create( model="cadreen", input="And its population?", instructions="You are a geography expert.", previous_response_id=res1.id, store=True ) print(res2.output_text) # "Paris has approximately 2.1 million people..."