Skip to main content
POST
Python (SDK)

Authorizations

Authorization
string
header
required

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Headers

X-On-Behalf-Of
string

Optional external end-user identifier forwarded by the API gateway.

Path Parameters

response_id
string
required

The unique identifier of the response, formatted as 'resp_' or 'resp-' followed by alphanumeric characters.

Pattern: ^resp[-_][a-zA-Z0-9]+$

Body

application/json

Request schema for updating a response's metadata.

metadata
object
required

Set of 16 key-value pairs to update. Keys must be strings up to 64 characters, values must be strings up to 512 characters.

Response

200 - application/json

The updated response object.

id
string
required
object
any
required
created_at
number
required
completed_at
number | null
required
status
enum<string>
required

The overall status of the response generation. 'completed' means successfully finished, 'failed' means error occurred, 'in_progress' means currently processing, 'cancelled' means user-cancelled, 'queued' means waiting to start, 'incomplete' means partial completion.

Available options:
completed,
failed,
in_progress,
cancelled,
queued,
incomplete
error
object | null
required
incomplete_details
object | null
required
background
boolean
required
instructions
required
max_output_tokens
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
Example:

null

max_tool_calls
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
metadata
object
required
model
string
required
output
(Input message item · object | Output message item · object | Output audio item · object | File search call item · object | Computer call item · object | Computer call output item · object | Web search call item · object | Function call item · object | Function call output item · object | Reasoning item · object | Image generation call item · object | Code interpreter call item · object | Local shell call item · object | Local shell call output item · object | Shell call item · object | Shell call output item · object | MCP list tools item · object | MCP approval request item · object | MCP approval response item · object | MCP call item · object | Custom tool call item · object | Custom tool call output item · object | Item reference item · object | Compaction item · object)[]
required

Input message item: A message with role and content. Use this for user, assistant, system, or developer turns in structured inputs.

parallel_tool_calls
boolean
required
previous_response_id
string | null
required
store
boolean
required
text
object
required
tool_choice
required

Tool choice mode: Selects how the model decides tool usage. Use none, auto, or required.

Available options:
none,
auto,
required
tools
(Function tool definition · object | File search tool definition · object | Computer use tool definition · object | Web search tool definition · object | any | Code interpreter tool definition · object | Image generation tool definition · object | Local shell tool definition · object | Shell tool definition · object | Custom tool definition · object | Web search preview tool definition · object | Hosted tool definition · object | Sleep tool definition · object | History tool definition · object | null)[]
required

Function tool definition: Defines a callable function tool. Provide a tool name and parameters schema, with optional description and deferred loading.

truncation
enum<string>
required
Available options:
auto,
disabled
usage
object
required
user
string | null
required
conversation
object
output_text
string
prompt
object
prompt_cache_key
string
reasoning
object
safety_identifier
string
service_tier
enum<string>
Available options:
auto,
default,
flex,
priority
temperature
number
Required range: 0 <= x <= 2
presence_penalty
number
frequency_penalty
number
top_logprobs
integer
Required range: 0 <= x <= 20
top_p
number
Required range: 0 <= x <= 1
context_management
object[]