Responses

POST /v1/responses is the OpenAI Responses API — the format behind Codex and the newer OpenAI SDK methods. Every text model in the catalogue answers on it.

A request

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.cloakray.com/v1",
  apiKey: process.env.CLOAKRAY_API_KEY,
});

const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: "Answer in one sentence.",
  input: "Why is the sky blue?",
});

console.log(response.output_text);

curl https://api.cloakray.com/v1/responses \
  -H "Authorization: Bearer $CLOAKRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "Answer in one sentence.",
    "input": "Why is the sky blue?"
  }'

input is a string, or an array of input items (messages with text, image and file parts, earlier outputs, and function call results). instructions plays the part of a system message. max_output_tokens, tools, text.format for structured outputs and reasoning for reasoning effort work as they do in the OpenAI API.

Stored responses and conversations

Responses are stored by default, so you can continue a conversation without resending it:

const first = await client.responses.create({
  model: "gpt-5.5",
  input: "Pick a random fruit.",
});

const second = await client.responses.create({
  model: "gpt-5.5",
  previous_response_id: first.id,
  input: "What colour is it?",
});

• A stored response is kept for 30 days.
• Only keys from the same project can read it or continue from it.
• Set store: false when you don't want the response kept. You then send the history yourself, as you would with Chat Completions.

Retrieve a stored response by ID:

curl https://api.cloakray.com/v1/responses/$RESPONSE_ID \
  -H "Authorization: Bearer $CLOAKRAY_API_KEY"

Reading a stored response is not charged again.

Compaction

POST /v1/responses/compact shortens a long conversation into a compact form you can keep going from, which saves input tokens on agents that run for many turns. Send a model and either the input to compact or a previous_response_id.

Streaming

With stream: true the reply arrives as typed server-sent events — response.output_text.delta for text, ending with response.completed, which carries the final usage. See streaming.

Not offered

Cancelling and deleting a response are not offered, even where an SDK has methods for them. Realtime sessions are not offered yet.