Responses API — POST /v1/responses

The /v1/responses endpoint implements the OpenAI Responses API, which supports stateful multi-turn conversations with built-in conversation history management. It is an alternative to /v1/chat/completions for workflows that require OpenAI’s newer response format. Pass a previous_response_id to continue a conversation without resending full message history.

Endpoint

POST https://router.flatkey.ai/v1/responses

When to use this endpoint

Use /v1/responses if:

Your application is built on the OpenAI Responses API
You need stateful conversation management
You use the previous_response_id parameter for multi-turn conversations

For most new integrations, /v1/chat/completions is the recommended endpoint and has broader model support.

Request

Headers

Header	Value
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Body parameters

model

string

required

Model ID to use. Only models that support the Responses API format are valid here.

input

string | array

required

The user input for this turn. Can be a string or an array of content objects.

instructions

string

System-level instructions for the model (equivalent to the system message in chat completions).

previous_response_id

string

The id of a previous response. When provided, the model continues the conversation from that point without the client needing to send history.

max_output_tokens

integer

Maximum number of tokens to generate.

stream

boolean

If true, returns a stream of server-sent events. Default: false.

Example request

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.responses.create(
    model="gpt-4o",
    input="What is the capital of Japan?",
    instructions="Answer concisely.",
)

print(response.output_text)

Multi-turn with previous_response_id

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

# First turn
response1 = client.responses.create(
    model="gpt-4o",
    input="My name is Alice.",
)

# Second turn — continue from the first
response2 = client.responses.create(
    model="gpt-4o",
    input="What is my name?",
    previous_response_id=response1.id,
)

print(response2.output_text)  # "Your name is Alice."

Response

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1710000000,
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "The capital of Japan is Tokyo."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 9,
    "total_tokens": 24
  }
}

Response fields

string

Unique identifier for this response. Pass it as previous_response_id to continue the conversation.

object

string

Always "response".

created_at

integer

Unix timestamp of when the response was created.

model

string

The model that generated the response.

output

array

Array of output objects produced by the model.

Show output item properties

type

string

The output type. "message" for text responses.

role

string

Always "assistant" for generated output.

content

array

Array of content blocks. Each block has a type ("output_text") and a text string.

usage

object

Token counts for billing.

Show usage properties

input_tokens

integer

Number of input tokens processed.

output_tokens

integer

Number of output tokens generated.

total_tokens

integer

Sum of input and output tokens.

​Endpoint

​When to use this endpoint

​Request

​Headers

​Body parameters

​Example request

​Multi-turn with previous_response_id

​Response

​Response fields

Endpoint

When to use this endpoint

Request

Headers

Body parameters

Example request

Multi-turn with previous_response_id

Response

Response fields