SambaNova Systems Responses API
The Responses API from SambaNova Systems — 1 operation(s) for responses.
OpenAPI Specification
openapi: 3.1.0
info:
title: Sambanova Agents Service Audio Responses API
description: Service for Sambanova agents
version: 0.0.1
termsOfService: https://sambanova.ai/cloud-end-user-license-agreement
contact:
email: info@sambanova.ai
name: SambaNova information
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://chat.sambanova.ai/api
security:
- api_key: []
tags:
- name: Responses
paths:
/responses:
post:
operationId: createResponse
tags:
- Responses
summary: Create a model response
description: 'Creates a model response for the given input. Only `type: "function"` tools are supported; other tool types are filtered server-side. SambaNova is stateless, conversation history must be supplied in full via `input[]` on each request.'
security:
- api_key: []
requestBody:
required: true
description: Response creation parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseRequest'
responses:
'200':
description: 'Successful response. Returns a ResponseResponse object (non-streaming), or a stream of server-sent ResponseStreamEvent object events ending with a response.completed event (when stream: true).'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResponseResponse'
- $ref: '#/components/schemas/ResponseStreamEvent'
'400':
description: Bad Request — missing or invalid parameters
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/GeneralError'
- $ref: '#/components/schemas/SimpleError'
examples:
missing_input:
summary: Required field missing
value:
error:
message: 'Missing required field: ''input''.'
type: invalid_request_error
param: input
code: missing_required_field
request_id: abc123
invalid_role:
summary: Invalid role on input item
value:
error:
message: 'Invalid value: ''foo''. Supported values are: ''user'', ''assistant'', ''system'', ''developer''.'
type: invalid_request_error
param: input[1].role
code: invalid_value
request_id: abc124
empty_input:
summary: Empty input array
value:
error:
message: 'Invalid value for ''input'': expected a non-empty array or string.'
type: invalid_request_error
param: input
code: invalid_value
request_id: abc125
invalid_json:
summary: Malformed JSON body
value:
error:
code: null
message: 'We could not parse the JSON body of your request. (HINT: This likely means you aren''t using your HTTP library correctly. A JSON payload is expected, but what was sent was not valid JSON.)'
param: null
type: invalid_request_error
request_id: 3f7db127
adapter_mapping_failed:
summary: Server failed to parse model tool call output
value:
error:
code: adapter_mapping_failed
error_model_output: "{\n \"name\": \"get_weather\",\n \"arguments\": {\n city: \"Bogotá\"\n }\n}"
message: 'Failed to parse tool call from GPT OSS output: Expecting property name enclosed in double quotes: line 4 column 5 (char 48)'
param: null
type: server_error
request_id: 494e734dc82b4b37bd914238c79c3e6c
simple:
summary: Simple error (unhandled cases)
value:
error: Unhandled error
'401':
description: Unauthorized — invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralError'
examples:
invalid_api_key:
summary: Invalid API key
value:
error:
message: 'Incorrect API key provided: *****. You can find your API key at https://cloud.sambanova.ai/apis.'
type: invalid_request_error
param: null
code: invalid_api_key
request_id: abc126
missing_api_key:
summary: No API key provided
value:
error:
message: 'You didn''t provide an API key. You need to provide your API key in an Authorization header using Bearer auth (i.e. Authorization: Bearer YOUR_KEY).'
type: invalid_request_error
param: null
code: null
request_id: abc127
'404':
description: Not found — model does not exist or is not accessible
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralError'
examples:
model_not_found:
summary: Model does not exist or is not accessible
value:
error:
message: The model `abc` does not exist or you do not have access to it.
type: invalid_request_error
param: model
code: model_not_found
request_id: abc128
simple:
summary: Simple error (unhandled cases e.g. wrong endpoint)
value:
error: Not found
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'410':
description: Gone — model is no longer available (deprecated or removed)
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'429':
description: Too Many Requests — rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralError'
'500':
description: Internal Server Error — unexpected issue on server side
content:
text/plain:
schema:
type: string
'503':
description: Service Temporarily Unavailable
content:
text/plain:
schema:
type: string
example: Service Temporarily Unavailable
x-codeSamples:
- lang: JavaScript
source: "import SambaNova from 'sambanova';\n\nconst client = new SambaNova({\n apiKey: process.env['SAMBANOVA_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.responses.create({\n input: [\n {\n content: 'What is the weather in San Francisco?',\n role: 'user',\n type: 'message',\n },\n {\n content: [\n { text: 'The weather in San Francisco is 65°F and partly cloudy.', type: 'output_text' },\n ],\n role: 'assistant',\n type: 'message',\n },\n {\n content: 'What should I wear?',\n role: 'user',\n type: 'message',\n },\n ],\n model: 'gpt-oss-120b',\n});\n\nconsole.log(response);"
- lang: Python
source: "import os\nfrom sambanova import SambaNova\n\nclient = SambaNova(\n api_key=os.environ.get(\"SAMBANOVA_API_KEY\"), # This is the default and can be omitted\n)\nfor response in client.responses.create(\n input=[{\n \"content\": \"What is the weather in San Francisco?\",\n \"role\": \"user\",\n \"type\": \"message\",\n }, {\n \"content\": [{\n \"text\": \"The weather in San Francisco is 65°F and partly cloudy.\",\n \"type\": \"output_text\",\n }],\n \"role\": \"assistant\",\n \"type\": \"message\",\n }, {\n \"content\": \"What should I wear?\",\n \"role\": \"user\",\n \"type\": \"message\",\n }],\n model=\"gpt-oss-120b\",\n):\n print(response)"
components:
schemas:
ResponseStreamEvent:
title: Response Stream Event
description: 'Top-level discriminated union of all Server-Sent Events emitted during a streaming `POST /responses` call. Discriminated by the `type` field. Events arrive in `sequence_number` order and cover the full lifecycle of a response: creation, content generation (text, reasoning, function call arguments), and completion.'
oneOf:
- $ref: '#/components/schemas/ResponseCreatedEvent'
- $ref: '#/components/schemas/ResponseInProgressEvent'
- $ref: '#/components/schemas/ResponseOutputItemAddedEvent'
- $ref: '#/components/schemas/ResponseContentPartAddedEvent'
- $ref: '#/components/schemas/ResponseReasoningTextDeltaEvent'
- $ref: '#/components/schemas/ResponseReasoningTextDoneEvent'
- $ref: '#/components/schemas/ResponseOutputTextDeltaEvent'
- $ref: '#/components/schemas/ResponseOutputTextDoneEvent'
- $ref: '#/components/schemas/ResponseFunctionCallArgumentsDeltaEvent'
- $ref: '#/components/schemas/ResponseFunctionCallArgumentsDoneEvent'
- $ref: '#/components/schemas/ResponseContentPartDoneEvent'
- $ref: '#/components/schemas/ResponseOutputItemDoneEvent'
- $ref: '#/components/schemas/ResponseCompletedEvent'
discriminator:
propertyName: type
mapping:
response.created: '#/components/schemas/ResponseCreatedEvent'
response.in_progress: '#/components/schemas/ResponseInProgressEvent'
response.output_item.added: '#/components/schemas/ResponseOutputItemAddedEvent'
response.content_part.added: '#/components/schemas/ResponseContentPartAddedEvent'
response.reasoning_text.delta: '#/components/schemas/ResponseReasoningTextDeltaEvent'
response.reasoning_text.done: '#/components/schemas/ResponseReasoningTextDoneEvent'
response.output_text.delta: '#/components/schemas/ResponseOutputTextDeltaEvent'
response.output_text.done: '#/components/schemas/ResponseOutputTextDoneEvent'
response.function_call_arguments.delta: '#/components/schemas/ResponseFunctionCallArgumentsDeltaEvent'
response.function_call_arguments.done: '#/components/schemas/ResponseFunctionCallArgumentsDoneEvent'
response.content_part.done: '#/components/schemas/ResponseContentPartDoneEvent'
response.output_item.done: '#/components/schemas/ResponseOutputItemDoneEvent'
response.completed: '#/components/schemas/ResponseCompletedEvent'
SimpleError:
title: SimpleError
type: object
description: other kind of simple schema errors
properties:
error:
title: error
type: string
description: error detail.
nullable: true
required:
- error
ResponseOutputItemAddedEvent:
title: Response Output Item Added Event
type: object
description: 'Emitted when a new output item (message, function call, or reasoning) is added to the response output array. The item has `status: in_progress` and may have empty content at this point.'
properties:
type:
type: string
enum:
- response.output_item.added
sequence_number:
type: integer
description: Monotonically increasing counter for ordering events within a streaming response.
output_index:
type: integer
description: Index of the output item in the response `output` array.
item:
$ref: '#/components/schemas/ResponseOutputItem'
required:
- type
- sequence_number
- output_index
- item
examples:
- type: response.output_item.added
sequence_number: 2
output_index: 0
item:
id: rs_d608e0328e6340a69919f808ee38df6c
type: reasoning
status: in_progress
summary: []
content: []
- type: response.output_item.added
sequence_number: 8
output_index: 1
item:
id: msg_c1eb06dccbc64f469533bb51be664a9e
type: message
role: assistant
status: in_progress
content: []
- type: response.output_item.added
sequence_number: 8
output_index: 1
item:
id: fc_c839dacb61a54c10b6560ad8d161f004
type: function_call
call_id: call_e52f086a16c94fa796
name: get_weather
arguments: ''
status: in_progress
ResponseOutputTextDeltaEvent:
title: Response Output Text Delta Event
type: object
description: Emitted for each incremental chunk of assistant message text. Accumulate `delta` values in order to reconstruct the full output text.
properties:
type:
type: string
enum:
- response.output_text.delta
sequence_number:
type: integer
description: Monotonically increasing counter for ordering events within a streaming response.
item_id:
type: string
description: ID of the message output item this delta belongs to.
output_index:
type: integer
description: Index of the message output item in the response `output` array.
content_index:
type: integer
description: Index of the content part within the output item's `content` array.
delta:
type: string
description: The incremental chunk of output text.
annotations:
type: array
items:
$ref: '#/components/schemas/ResponseAnnotation'
description: Annotations attached to this delta chunk, if any.
logprobs:
type: array
items:
$ref: '#/components/schemas/LogProbsContent'
description: Log probability information for the tokens in this delta, if requested.
required:
- type
- sequence_number
- item_id
- output_index
- content_index
- delta
- annotations
- logprobs
example:
type: response.output_text.delta
sequence_number: 10
item_id: msg_c1eb06dccbc64f469533bb51be664a9e
output_index: 1
content_index: 0
delta: Under a moonlit canopy of twinkling stars, a silver-mane unicorn tiptoed into the meadow, leaving a trail of soft
annotations: []
logprobs: []
ResponseUsage:
title: Response Usage
type: object
description: Token usage statistics for this response.
properties:
input_tokens:
title: Input Tokens
type: integer
description: Number of tokens in the input, including conversation history and any system instructions.
output_tokens:
title: Output Tokens
type: integer
description: Number of tokens generated in the output, including visible text and any reasoning tokens.
total_tokens:
title: Total Tokens
type: integer
description: Total tokens consumed by this request (input + output).
input_tokens_details:
title: Input Tokens Details
type: object
description: Breakdown of input token consumption.
properties:
cached_tokens:
title: Cached Tokens
type: integer
description: Number of input tokens served from the prompt cache. Cached tokens are billed at a reduced rate.
nullable: true
output_tokens_details:
title: Output Tokens Details
type: object
description: Breakdown of output token consumption.
properties:
reasoning_tokens:
title: Reasoning Tokens
type: integer
description: Number of tokens consumed by the model's internal reasoning process. Only present on reasoning-capable models.
nullable: true
start_time:
title: Start Time
type: number
description: Unix timestamp (seconds) of when generation started.
nullable: true
end_time:
title: End Time
type: number
description: Unix timestamp (seconds) of when generation finished.
nullable: true
time_to_first_token:
title: Time To First Token
type: number
description: Time in seconds from request receipt to first output token (TTFT).
nullable: true
total_latency:
title: Total Latency
type: number
description: Total time in seconds taken to generate the full response.
nullable: true
output_tokens_per_sec:
title: Output Tokens Per Sec
type: number
description: Output token throughput (tokens/second) for this response.
nullable: true
output_tokens_after_first_per_sec:
title: Output Tokens After First Per Sec
type: number
description: Output token throughput measured after the first token was emitted. Excludes the time-to-first-token latency from the rate calculation.
nullable: true
total_tokens_per_sec:
title: Total Tokens Per Sec
type: number
description: Total token throughput (input + output tokens/second).
nullable: true
acceptance_rate:
title: Acceptance Rate
type: number
description: Speculative decoding acceptance rate. Ratio of draft tokens accepted by the verifier model. Higher values indicate better speculation efficiency.
nullable: true
is_last_response:
title: Is Last Response
type: boolean
description: Always true for non-streaming responses. For streaming, true only on the final chunk that carries usage.
nullable: true
required:
- input_tokens
- output_tokens
- total_tokens
example:
input_tokens: 248
output_tokens: 72
total_tokens: 320
input_tokens_details:
cached_tokens: 0
output_tokens_details:
reasoning_tokens: 18
start_time: 1737642515.445
end_time: 1737642515.904
time_to_first_token: 0.084
total_latency: 0.459
output_tokens_per_sec: 156.8
output_tokens_after_first_per_sec: 161.2
total_tokens_per_sec: 311.6
acceptance_rate: 4.06
is_last_response: true
ResponseReasoningTextDoneEvent:
title: Response Reasoning Text Done Event
type: object
description: Emitted when a reasoning content part has been fully generated. The `text` field contains the complete accumulated reasoning text (equivalent to concatenating all preceding `response.reasoning_text.delta` values). Structural mirror of `response.reasoning_text.delta` with `text` instead of `delta`.
properties:
type:
type: string
enum:
- response.reasoning_text.done
x-stainless-const: true
sequence_number:
type: integer
description: Monotonically increasing counter for ordering events within a streaming response.
item_id:
type: string
description: ID of the reasoning output item this content belongs to.
output_index:
type: integer
description: Index of the reasoning output item in the response `output` array.
text:
type: string
description: The full accumulated reasoning text for this content part.
required:
- type
- sequence_number
- item_id
- output_index
- text
example:
type: response.reasoning_text.done
sequence_number: 5
item_id: rs_d608e0328e6340a69919f808ee38df6c
output_index: 0
text: User wants a three-sentence bedtime story about a unicorn. Provide three sentences, gentle, bedtime. Should be concise.
ResponseOutputItem:
title: Response Output Item
description: A single item in the output[] array returned by the model. Can be a message (with text or tool call content), a function call request, or a reasoning trace. Discriminated by the "type" field.
oneOf:
- $ref: '#/components/schemas/ResponseMessage'
- $ref: '#/components/schemas/ResponseFunctionCall'
- $ref: '#/components/schemas/ResponseOutputReasoning'
discriminator:
propertyName: type
mapping:
message: '#/components/schemas/ResponseMessage'
function_call: '#/components/schemas/ResponseFunctionCall'
reasoning: '#/components/schemas/ResponseOutputReasoning'
ResponseReasoningContent:
title: Response Reasoning Content
type: object
description: A single content part within a reasoning item's content[]. Contains the raw reasoning text produced by the model during its internal thinking process.
properties:
type:
title: Type
type: string
description: The type of this reasoning content part. Always "reasoning_text".
enum:
- reasoning_text
text:
title: Text
type: string
description: The raw reasoning text generated by the model.
required:
- type
- text
example:
type: reasoning_text
text: The user is asking about the weather. I should call the get_weather function with the location extracted from the message.
ResponseToolChoiceOption:
title: Response Tool Choice Option
description: 'Controls which tool (if any) the model calls. String values: "none" disables tool calls; "auto" lets the model decide; "required" forces at least one tool call. To force a specific function, provide a ResponseNamedToolChoice object.'
oneOf:
- type: string
title: Tool choice mode
description: String shorthand for tool selection behavior.
enum:
- none
- auto
- required
- $ref: '#/components/schemas/ResponseNamedToolChoice'
ResponseImageContent:
title: Response Image Content
type: object
description: An image content part for use inside a ResponseMessage. Supported in input messages (user role). Provide a base64-encoded image as a data URL. external URLs not supported.
properties:
type:
title: Type
type: string
description: The type of this content part. Always "input_image".
enum:
- input_image
image_url:
title: Image URL
type: string
description: A base64-encoded image in data URL format or fully qualified URL (e.g. "data:image/png;base64,..."). Currently only base64-encoded image data is supported.
nullable: true
detail:
title: Detail
type: string
description: The detail level for image processing. "auto" lets the model decide. "low" uses a fixed low-res tile. "high" enables high-res tiling.
enum:
- auto
- low
- high
default: auto
nullable: true
required:
- type
- image_url
ResponseInputItem:
title: Response Input Item
description: A single item in the input[] array. Can be a message, a function call, a function call result, or a reasoning trace replayed from a prior turn. When building multi-turn conversations, pass all items from the previous response output[] back as input[] items (including reasoning items) so the model has full context. Discriminated by the "type" field.
oneOf:
- $ref: '#/components/schemas/ResponseMessage'
- $ref: '#/components/schemas/ResponseFunctionCall'
- $ref: '#/components/schemas/ResponseFunctionCallOutput'
- $ref: '#/components/schemas/ResponseOutputReasoning'
discriminator:
propertyName: type
mapping:
message: '#/components/schemas/ResponseMessage'
function_call: '#/components/schemas/ResponseFunctionCall'
function_call_output: '#/components/schemas/ResponseFunctionCallOutput'
reasoning: '#/components/schemas/ResponseOutputReasoning'
ResponseOutputReasoning:
title: Response Output Reasoning
type: object
description: A reasoning item emitted in output[] by models that expose their internal chain-of-thought. Contains the raw reasoning text the model produced before generating its final answer.
properties:
type:
title: Type
type: string
description: The type of this output item. Always "reasoning".
enum:
- reasoning
id:
title: ID
type: string
description: Unique identifier for this reasoning item, assigned by the server.
nullable: true
status:
title: Status
type: string
description: Processing state of this item. "in_progress" while streaming; "completed" when the full reasoning text has been emitted.
enum:
- in_progress
- completed
- incomplete
nullable: true
content:
title: Content
type: array
description: The reasoning content parts. Each part has type "reasoning_text" and carries the raw thinking text. Absent when the item is first added (`response.output_item.added`); populated by `response.output_item.done`.
items:
$ref: '#/components/schemas/ResponseReasoningContent'
nullable: true
summary:
title: Summary
type: array
description: A condensed summary of the reasoning content. Always returned as an empty array. Included for OpenAI API compatibility.
items:
type: object
additionalProperties: true
nullable: true
required:
- type
example:
type: reasoning
id: rs_msg_5dc0dc6fca844a20885869634cd3014a
status: completed
summary: []
content:
- type: reasoning_text
text: The user wants weather information for San Francisco. I'll call get_weather with location "San Francisco, CA".
ResponseFunctionCall:
title: Response Function Call
type: object
description: A function call item used in both input[] and output[]. When present in output[], the model is requesting a tool call — id and status are always set by the server. When used in input[], it replays a prior function call from the conversation history for multi-turn tool loops.
properties:
type:
title: Type
type: string
description: The type of this item. Always "function_call".
enum:
- function_call
id:
title: ID
type: string
description: Unique identifier for this function call item. Always present on output items returned by the server. Required when replaying this item in a subsequent input[].
nullable: true
call_id:
title: Call ID
type: string
description: The call ID generated by the model for this tool invocation. Used to correlate the function call with its corresponding function_call_output result.
name:
title: Name
type: string
description: The name of the function the model wants to call.
arguments:
title: Arguments
type: string
description: A JSON string of the arguments to pass to the function, as generated by the model. Validate the arguments in your code before calling the function — the model may hallucinate parameters not defined in the schema.
status:
title: Status
type: string
description: Processing state of this item. Always set on output items returned by the server. Not required when constructing input items.
enum:
- in_progress
- completed
- incomplete
nullable: true
required:
- type
- call_id
- name
- arguments
example:
type: function_call
id: fc_abc123
call_id: call_abc123
name: get_weather
arguments: '{"location":"San Francisco, CA"}'
status: completed
ResponseFunctionCallArgumentsDeltaEvent:
title: Response Function Call Arguments Delta Event
type: object
description: Emitted for each incremental chunk of function call arguments JSON generated by the model. Accumulate `delta` values in order to reconstruct the full arguments string. The accumulated result will be a valid JSON string once the corresponding `response.function_call_arguments.done` event is received.
properties:
type:
type: string
enum:
- response.function_call_arguments.delta
sequence_number:
type: integer
description: Monotonically increasing counter for ordering events within a streaming response.
item_id:
type: string
description: ID of the function call output item this delta belongs to.
output_index:
type: integer
description: Index of the function call output item in the response `output` array.
delta:
type: string
description: The incremental chunk of the function call arguments JSON string.
required:
- type
- sequence_number
- item_id
- output_index
- delta
example:
type: response.function_call_arguments.delta
sequence_number: 9
item_id: fc_c839dacb61a54c10b6560ad8d161f004
output_index: 1
delta: '{"city":"Bogotá"}'
ResponseAudioContent:
title: Response Audio Content
type: object
description: An audio content part for use inside a ResponseMessage. Supported in input messages (user role). Provide base64-encoded audio data with the format.
properties:
type:
title: Type
type: string
description: The type of this content part. Always "input_audio".
enum:
- input_audio
input_audio:
title: Input Audio
type: object
description: The audio data and format.
properties:
data:
title: Data
type: string
description: Base64-encoded audio data.
format:
title: Format
type: string
enum:
- mp3
- wav
description: The format of the audio data.
required:
- data
- format
required:
- type
- input_audio
ResponseCreatedEvent:
title: Response Created Event
type: object
description: Emitted as the first SSE event when a streaming response begins. The embedded response object has status `in_progress` and an empty `output` array. Clients can use this event to capture the response `id` for later correlation.
properties:
type:
type: string
enum:
- response.created
sequence_number:
type: integer
description: Monotonically increasing counter for ordering events within a streaming response. Starts at 0 for `response.created`.
response:
$ref: '#/components/schemas/ResponseResponse'
required:
- type
- sequence_number
- response
example:
type: response.created
sequence_number: 0
response:
id: resp_18cb0a9a457241f5b0383ebeee31b80d
object: response
created_at: 1775853213
status:
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sambanova-systems/refs/heads/main/openapi/sambanova-systems-responses-api-openapi.yml