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

string

required

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

string | array

required

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

string

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

string

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

integer

Maximum number of tokens to generate.

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.

string

Always "response".

integer

Unix timestamp of when the response was created.

string

The model that generated the response.

array

Array of output objects produced by the model.

Show output item properties

string

The output type. "message" for text responses.

string

Always "assistant" for generated output.

array

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

object

Token counts for billing.

Show usage properties

integer

Number of input tokens processed.

integer

Number of output tokens generated.

integer

Sum of input and output tokens.

Overview

Endpoints

Responses API — POST /v1/responses

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

Endpoint

When to use this endpoint

Request

Headers

Body parameters

Example request

Multi-turn with previous_response_id

Response

Response fields