OpenAI Responses API
Create stateless model responses for Codex, SDKs, and other OpenAI-compatible clients.
Create a model response with POST /openai/{region}/v1/responses. ajan implements the OpenAI Responses request and response shape for the fields listed below, so you can use the OpenAI SDK responses.create method and other Responses-compatible clients with a ajan API key.
Use this endpoint for Codex and other clients that send Responses input items and read Responses output items. For integrations that send messages and read choices, use OpenAI Chat Completions.
Before You Start
- API key: To use the API, create a personal API key or ask your workspace admin for a workspace API key with the Completion API scope. Personal keys only include the Completion API scope.
Base URL
https://api.ajan.io/openai/{region}/v1/responsesParameters
Pass a string, message items, or tool results in input. ajan forwards supported values for instructions, max_output_tokens, temperature, top_p, reasoning, text, metadata, include, truncation, service_tier, tools, tool_choice, and parallel_tool_calls. The endpoint supports native server-sent event streaming and function tools, including parallel function calls. Which settings apply depends on the selected model.
The {region} path value must be eu, us, or global, and must match a region where your model is available. Call GET /openai/{region}/v1/models with the same region to list models available in your workspace. The list may differ when your workspace uses Bring your own key (BYOK).
Differences from the OpenAI API
- Omit
storeor set it tofalse.store=trueis rejected. previous_response_idis not supported and is rejected. Pass previous messages and tool results ininput.- Background responses are not supported. Omit
backgroundor set it tofalse. - Hosted tools such as web search, file search, code interpreter, image generation, computer use, and MCP are not supported.
- Function tools are supported, including parallel function calls.
Using the OpenAI Python library
Set ajan as the base URL and use responses.create:
python
from openai import OpenAI
client = OpenAI(
base_url="https://api.ajan.io/openai/eu/v1",
api_key="<YOUR_AJAN_API_KEY>",
)
response = client.responses.create(
model="gpt-5-mini",
input="Write a short poem about cats.",
store=False,
)
print(response.output_text)Stream a response
Set stream=True to receive native Responses API events:
python
stream = client.responses.create(
model="gpt-5-mini",
input="Write a short poem about cats.",
store=False,
stream=True,
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="")Continue a stateless tool conversation
Append the returned output items and the matching function_call_output to the next request:
python
import json
conversation = [
{"role": "user", "content": "What is the weather in Berlin?"}
]
tools = [{
"type": "function",
"name": "lookup_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
"additionalProperties": False,
},
}]
response = client.responses.create(
model="gpt-5-mini",
input=conversation,
tools=tools,
store=False,
)
conversation.extend(response.output)
tool_call = next(item for item in response.output if item.type == "function_call")
conversation.append({
"type": "function_call_output",
"call_id": tool_call.call_id,
"output": json.dumps({"temperature_c": 18, "condition": "sunny"}),
})
final_response = client.responses.create(
model="gpt-5-mini",
input=conversation,
tools=tools,
store=False,
)
print(final_response.output_text)Connect Codex
Create a personal API key, then open Connect your tools > Codex on Settings > Account > API keys. Choose an available OpenAI-compatible model and follow the generated setup steps for your operating system. The setup points Codex at ajan's Responses endpoint (wire_api = "responses") and your selected model.
Rate limits
The default limits are 500 RPM (requests per minute) and 150,000 TPM (tokens per minute).
- RPM is enforced per workspace, model, and API key.
- TPM is shared by all API keys using the same model in a workspace.
- On dedicated deployments, admins can configure custom limits per model in Settings > Workspace > Products > API.
A rate-limited request returns 429 Too Many Requests. Successful and rate-limited responses include x-ratelimit-limit-requests, x-ratelimit-limit-tokens, x-ratelimit-remaining-requests, and x-ratelimit-remaining-tokens.
Personal API key usage counts toward the member's effective personal budget and the workspace spend limit together with chat and agent usage. Workspace API key usage counts toward the workspace API spend limit. See Personal API keys and Pricing.
OpenAPI
openapi: 3.0.0
info:
title: ajan API
version: 3.0.0
servers:
- url: https://api.ajan.io
description: Production
security:
- bearerAuth: []
paths:
/openai/{region}/v1/responses:
post:
tags:
- Responses
summary: Creates a stateless model response.
description: >-
Creates a stateless OpenAI-compatible response. Supports text
generation, streaming, and function tools. Do not send store=true,
previous_response_id, background=true, or hosted tools.
operationId: createResponse
parameters:
- name: region
in: path
required: true
description: The region of the API to use.
schema:
type: string
enum:
- eu
- us
- global
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
description: >-
The model ID. Use the models endpoint to list models
available in your workspace.
input:
description: The input text or full conversation state to process.
oneOf:
- type: string
- type: array
items: {}
- type: object
additionalProperties: true
instructions:
type: string
nullable: true
description: Instructions added to the model context.
max_output_tokens:
type: integer
minimum: 1
nullable: true
description: The maximum number of output tokens.
temperature:
type: number
nullable: true
description: Controls response randomness.
top_p:
type: number
nullable: true
description: Controls nucleus sampling.
stream:
type: boolean
nullable: true
default: false
description: Whether to return native Responses API server sent events.
tools:
type: array
description: Function tool definitions. Hosted tools are not supported.
items:
type: object
required:
- type
- name
properties:
type:
type: string
enum:
- function
name:
type: string
minLength: 1
description:
type: string
nullable: true
parameters:
type: object
nullable: true
additionalProperties: true
strict:
type: boolean
nullable: true
tool_choice:
description: Controls whether the model can call a function.
oneOf:
- type: string
enum:
- none
- auto
- required
- type: object
required:
- type
- name
properties:
type:
type: string
enum:
- function
name:
type: string
minLength: 1
parallel_tool_calls:
type: boolean
nullable: true
description: Whether the model can return multiple function calls.
reasoning:
type: object
description: OpenAI Responses reasoning configuration.
additionalProperties: true
text:
type: object
description: OpenAI Responses text output configuration.
additionalProperties: true
metadata:
type: object
nullable: true
description: String metadata attached to the request.
additionalProperties:
type: string
store:
type: boolean
nullable: true
enum:
- false
description: >-
Responses are not persisted. Omit this field or set it to
false.
background:
type: boolean
nullable: true
enum:
- false
description: Background responses are not supported.
include:
type: array
nullable: true
items:
type: string
description: Additional response fields to include.
truncation:
type: string
nullable: true
enum:
- auto
- disabled
service_tier:
type: string
nullable: true
description: The OpenAI service tier forwarded to the model provider.
example:
model: gpt-5-mini
input: Write a short poem about cats.
store: false
responses:
'200':
description: Successful response or event stream.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResponseResponse'
example:
id: resp_09e99d1f7f163d10016a678387353481
object: response
created_at: 1785168775
status: completed
model: gpt-5-mini-2025-08-07
output:
- id: rs_09e99d1f7f163d10016a678387f47881
type: reasoning
content: []
summary: []
- id: msg_09e99d1f7f163d10016a67838935a881
type: message
status: completed
role: assistant
content:
- type: output_text
annotations: []
logprobs: []
text: |-
Whiskers sketch moonlight on the sill,
paws treading silence, soft and still.
Eyes like lanterns, sly and bright,
turning midnight into light.
A velvet sigh, a sudden purr—
the world made small, the heart made her.
usage:
input_tokens: 13
input_tokens_details:
cached_tokens: 0
output_tokens: 154
output_tokens_details:
reasoning_tokens: 64
total_tokens: 167
text/event-stream:
schema:
type: string
description: Native OpenAI Responses API server sent events.
'400':
description: Invalid fields, unsupported features, or an unavailable model.
'401':
description: Missing, invalid, or expired API key.
'403':
description: API key without the Completion API scope.
'413':
description: Request body exceeds 20 MB.
'429':
description: Usage or rate limit exceeded.
'500':
description: Internal server or upstream provider error.
default:
description: Error returned by the upstream model provider.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- message
- type
properties:
message:
type: string
type:
type: string
code:
type: string
nullable: true
param:
type: string
nullable: true
security:
- bearerAuth: []
components:
schemas:
CreateResponseResponse:
type: object
description: A response returned by the OpenAI-compatible Responses endpoint.
required:
- id
- object
- created_at
- status
- model
- output
properties:
id:
type: string
description: Unique identifier for the response.
example: resp_09e99d1f7f163d10016a678387353481
object:
type: string
enum:
- response
description: The object type, which is always `response`.
created_at:
type: integer
description: Unix timestamp in seconds when the response was created.
example: 1785168775
completed_at:
type: integer
nullable: true
description: Unix timestamp in seconds when the response completed.
example: 1785168778
background:
type: boolean
enum:
- false
description: ajan does not support background responses.
status:
type: string
enum:
- completed
- failed
- in_progress
- cancelled
- queued
- incomplete
description: Current response status.
example: completed
model:
type: string
description: Model used to generate the response.
example: gpt-5-mini-2025-08-07
output:
type: array
description: Output items generated by the model.
items:
oneOf:
- $ref: '#/components/schemas/ResponseReasoningItem'
- $ref: '#/components/schemas/ResponseOutputMessage'
- $ref: '#/components/schemas/ResponseFunctionToolCall'
output_text:
type: string
description: Aggregated text from all `output_text` items.
error:
type: object
nullable: true
description: Error information when the response failed.
properties:
code:
type: string
nullable: true
message:
type: string
incomplete_details:
type: object
nullable: true
description: Details explaining why the response is incomplete.
properties:
reason:
type: string
enum:
- max_output_tokens
- content_filter
instructions:
type: string
nullable: true
description: Instructions used for the response.
max_output_tokens:
type: integer
nullable: true
description: Maximum number of output tokens configured for the response.
parallel_tool_calls:
type: boolean
description: Whether the model can return multiple function calls.
reasoning:
type: object
nullable: true
description: Reasoning configuration used for the response.
additionalProperties: true
store:
type: boolean
enum:
- false
description: ajan Responses are never persisted.
temperature:
type: number
nullable: true
description: Sampling temperature used for the response.
text:
type: object
nullable: true
description: Text output configuration used for the response.
additionalProperties: true
service_tier:
type: string
nullable: true
description: Service tier used to process the response.
tool_choice:
description: Tool choice used for the response.
oneOf:
- type: string
- type: object
additionalProperties: true
tools:
type: array
description: Function tools available to the model.
items:
type: object
additionalProperties: true
top_p:
type: number
nullable: true
description: Nucleus sampling value used for the response.
truncation:
type: string
enum:
- auto
- disabled
description: Truncation strategy used for the response.
usage:
$ref: '#/components/schemas/ResponseUsage'
metadata:
type: object
nullable: true
description: Metadata attached to the request.
additionalProperties:
type: string
additionalProperties: true
ResponseReasoningItem:
type: object
description: Reasoning information generated by a reasoning model.
required:
- id
- type
- summary
properties:
id:
type: string
example: rs_123
type:
type: string
enum:
- reasoning
summary:
type: array
items:
type: object
additionalProperties: true
content:
type: array
items:
type: object
additionalProperties: true
encrypted_content:
type: string
nullable: true
description: Encrypted reasoning content when requested.
status:
type: string
nullable: true
enum:
- in_progress
- completed
- incomplete
additionalProperties: true
ResponseOutputMessage:
type: object
description: A message generated by the model.
required:
- id
- type
- status
- role
- content
properties:
id:
type: string
example: msg_09e99d1f7f163d10016a67838935a881
type:
type: string
enum:
- message
status:
type: string
enum:
- in_progress
- completed
- incomplete
role:
type: string
enum:
- assistant
content:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ResponseOutputText'
- $ref: '#/components/schemas/ResponseOutputRefusal'
additionalProperties: true
ResponseFunctionToolCall:
type: object
description: A function call requested by the model.
required:
- id
- type
- call_id
- name
- arguments
properties:
id:
type: string
example: fc_123
type:
type: string
enum:
- function_call
status:
type: string
enum:
- in_progress
- completed
- incomplete
call_id:
type: string
example: call_123
name:
type: string
example: lookup_weather
arguments:
type: string
description: JSON-encoded arguments for the function.
example: '{"city":"Berlin"}'
additionalProperties: true
ResponseUsage:
type: object
description: Token usage for the response.
required:
- input_tokens
- output_tokens
- total_tokens
properties:
input_tokens:
type: integer
example: 13
input_tokens_details:
type: object
properties:
cached_tokens:
type: integer
example: 0
additionalProperties: true
output_tokens:
type: integer
example: 154
output_tokens_details:
type: object
properties:
reasoning_tokens:
type: integer
example: 64
additionalProperties: true
total_tokens:
type: integer
example: 167
additionalProperties: true
ResponseOutputText:
type: object
description: Text generated by the model.
required:
- type
- text
- annotations
properties:
type:
type: string
enum:
- output_text
text:
type: string
example: |-
Whiskers sketch moonlight on the sill,
paws treading silence, soft and still.
annotations:
type: array
items:
type: object
additionalProperties: true
logprobs:
type: array
items:
type: object
additionalProperties: true
additionalProperties: true
ResponseOutputRefusal:
type: object
description: A refusal returned by the model.
required:
- type
- refusal
properties:
type:
type: string
enum:
- refusal
refusal:
type: string
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"