SambaNova Systems Responses API
The Responses API from SambaNova Systems — 1 operation(s) for responses.
The Responses API from SambaNova Systems — 1 operation(s) for responses.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/sambanova-systems-responses-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: SambaNova cloud Responses API
description: SambaNova cloud API Specification
version: 1.2.0
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://api.sambanova.ai/v1
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:
ResponseContentPartDoneEvent:
title: Response Content Part Done Event
type: object
description: Emitted when a content part has been fully generated. The `part` field contains the complete content for this part (equivalent to the state after accumulating all preceding delta events). Structural mirror of `response.content_part.added`.
properties:
type:
type: string
enum:
- response.content_part.done
sequence_number:
type: integer
description: Monotonically increasing counter for ordering events within a streaming response.
item_id:
type: string
description: ID of the output item this content part belongs to.
output_index:
type: integer
description: Index of the parent output item in the response `output` array.
content_index:
type: integer
description: Index of this content part within the output item's `content` array.
part:
$ref: '#/components/schemas/ResponseStreamContentPart'
required:
- type
- sequence_number
- item_id
- output_index
- content_index
- part
examples:
- type: response.content_part.done
sequence_number: 6
item_id: rs_d608e0328e6340a69919f808ee38df6c
output_index: 0
content_index: 0
part:
type: reasoning_text
text: User wants a three-sentence bedtime story about a unicorn. Provide three sentences, gentle, bedtime. Should be concise.
- type: response.content_part.done
sequence_number: 16
item_id: msg_c1eb06dccbc64f469533bb51be664a9e
output_index: 1
content_index: 0
part:
type: output_text
annotations: []
logprobs: []
text: Under a moonlit canopy of twinkling stars, a silver-mane unicorn tiptoed into the meadow, leaving a trail of soft, glowing stardust behind each gentle step. She whispered a lullaby to the sleepy flowers, and they swayed in rhythm, their petals folding like tiny blankets around the night. As the world hushed, the unicorn curled around a sleepy child's dream, gifting them a night of sweet, sparkling adventures until sunrise.
ResponseOutputTextDoneEvent:
title: Response Output Text Done Event
type: object
description: Emitted when an output text content part has been fully generated. The `text` field contains the complete accumulated output text (equivalent to concatenating all preceding `response.output_text.delta` values). Structural mirror of `response.output_text.delta` with `text` instead of `delta`.
properties:
type:
type: string
enum:
- response.output_text.done
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 content 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.
text:
type: string
description: The full accumulated output text for this content part.
annotations:
type: array
items:
$ref: '#/components/schemas/ResponseAnnotation'
description: All annotations attached to this text part.
logprobs:
type: array
items:
$ref: '#/components/schemas/LogProbsContent'
description: Log probability information for all tokens, if requested.
required:
- type
- sequence_number
- item_id
- output_index
- content_index
- text
- annotations
- logprobs
example:
type: response.output_text.done
sequence_number: 15
item_id: msg_c1eb06dccbc64f469533bb51be664a9e
output_index: 1
content_index: 0
annotations: []
logprobs: []
text: Under a moonlit canopy of twinkling stars, a silver-mane unicorn tiptoed into the meadow, leaving a trail of soft, glowing stardust behind each gentle step. She whispered a lullaby to the sleepy flowers, and they swayed in rhythm, their petals folding like tiny blankets around the night. As the world hushed, the unicorn curled around a sleepy child's dream, gifting them a night of sweet, sparkling adventures until sunrise.
ResponseOutputItemDoneEvent:
title: Response Output Item Done Event
type: object
description: Emitted when an output item has been fully generated and its status transitions to `completed`. The `item` field contains the complete output item including all accumulated content. Structural mirror of `response.output_item.added`.
properties:
type:
type: string
enum:
- response.output_item.done
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.done
sequence_number: 7
output_index: 0
item:
id: rs_d608e0328e6340a69919f808ee38df6c
type: reasoning
status: completed
summary: []
content:
- type: reasoning_text
text: User wants a three-sentence bedtime story about a unicorn. Provide three sentences, gentle, bedtime. Should be concise.
- type: response.output_item.done
sequence_number: 17
output_index: 1
item:
id: msg_c1eb06dccbc64f469533bb51be664a9e
type: message
role: assistant
status: completed
content:
- type: output_text
annotations: []
logprobs: []
text: Under a moonlit canopy of twinkling stars, a silver-mane unicorn tiptoed into the meadow, leaving a trail of soft, glowing stardust behind each gentle step. She whispered a lullaby to the sleepy flowers, and they swayed in rhythm, their petals folding like tiny blankets around the night. As the world hushed, the unicorn curled around a sleepy child's dream, gifting them a night of sweet, sparkling adventures until sunrise.
- type: response.output_item.done
sequence_number: 11
output_index: 1
item:
id: fc_c839dacb61a54c10b6560ad8d161f004
type: function_call
call_id: call_e52f086a16c94fa796
name: get_weather
arguments: '{"city":"Bogotá"}'
status: completed
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'
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
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
TopLogProbs:
title: TopLogProbs
type: object
additionalProperties: true
properties:
bytes:
title: Bytes
anyOf:
- items:
type: integer
type: array
- type: 'null'
logprob:
title: Logprob
type: number
token:
title: Token
type: string
required:
- token
- logprob
examples:
- token: ' Hello'
logprob: -0.00012340000000000002
bytes:
- 32
- 72
- 101
- 108
- 108
- 111
- token: ' Hi'
logprob: -8.243
bytes:
- 32
- 72
- 105
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: []
ResponseContent:
title: Response Content
description: A typed content part used in both input and output message content arrays. Discriminated by the "type" field.
oneOf:
- $ref: '#/components/schemas/ResponseTextContent'
- $ref: '#/components/schemas/ResponseImageContent'
- $ref: '#/components/schemas/ResponseAudioContent'
- $ref: '#/components/schemas/ResponseVideoContent'
discriminator:
propertyName: type
mapping:
input_text: '#/components/schemas/ResponseTextContent'
output_text: '#/components/schemas/ResponseTextContent'
input_image: '#/components/schemas/ResponseImageContent'
input_audio: '#/components/schemas/ResponseAudioContent'
input_video: '#/components/schemas/ResponseVideoContent'
ResponseUrlCitation:
title: Response URL Citation
type: object
description: A URL citation annotation on an output text span. Not currently implemented by SambaNova — included for OpenAI API compatibility.
properties:
type:
title: Type
type: string
description: The annotation type. Always "url_citation".
enum:
- url_citation
url:
title: URL
type: string
description: The URL being cited.
title:
title: Title
type: string
description: The title of the cited page.
nullable: true
start_index:
title: Start Index
type: integer
description: Character offset in the output text where the citation starts.
end_index:
title: End Index
type: integer
description: Character offset in the output text where the citation ends.
required:
- type
- url
- start_index
- end_index
ResponseCompletedEvent:
title: Response Completed Event
type: object
description: 'Emitted as the final SSE event when a streaming response has been fully generated. The embedded response object has `status: completed`, a fully populated `output` array, and a populated `usage` object. Structural mirror of `response.created`.'
properties:
type:
type: string
enum:
- response.completed
x-stainless-const: true
sequence_number:
type: integer
description: Monotonically increasing counter for ordering events within a streaming response.
response:
$ref: '#/components/schemas/ResponseResponse'
required:
- type
- sequence_number
- response
examples:
- type: response.completed
sequence_number: 18
response:
id: resp_18cb0a9a457241f5b0383ebeee31b80d
object: response
created_at: 1775853213
completed_at: 1775853214
status: completed
model: gpt-oss-120b
output:
- id: rs_d608e0328e6340a69919f808ee38df6c
type: reasoning
status: completed
summary: []
content:
- type: reasoning_text
text: User wants a three-sentence bedtime story about a unicorn. Provide three sentences, gentle, bedtime. Should be concise.
- id: msg_c1eb06dccbc64f469533bb51be664a9e
type: message
role: assistant
status: completed
content:
- type: output_text
annotations: []
logprobs: []
text: Under a moonlit canopy of twinkling stars, a silver-mane unicorn tiptoed into the meadow, leaving a trail of soft, glowing stardust behind each gentle step.
usage:
input_tokens: 78
output_tokens: 126
total_tokens: 204
input_tokens_details:
cached_tokens: 0
tool_choice: auto
tools: []
temperature: 1
top_p: 1
reasoning:
effort: medium
summary: null
text:
format:
type: text
- type: response.completed
sequence_number: 12
response:
id: resp_e8e3ad78db7546ce969f79b0828f3be3
object: response
created_at: 1775856350
completed_at: 1775856350
status: completed
model: gpt-oss-120b
output:
- id: rs_c512ec8087b247b0962b64b7595c92d2
type: reasoning
status: completed
summary: []
content:
- type: reasoning_text
text: 'User asks: "What is the weather in Bogotá?" Need to fetch current weather using function get_weather.'
- id: fc_c839dacb61a54c10b6560ad8d161f004
type: function_call
call_id: call_e52f086a16c94fa796
name: get_weather
arguments: '{"city":"Bogotá"}'
status: completed
usage:
input_tokens: 128
output_tokens: 59
total_tokens: 187
input_tokens_details:
cached_tokens: 0
output_tokens_details:
reasoning_tokens: 43
tools:
- type: function
name: get_weather
description: Get the current weather for a city
parameters:
type: object
properties:
city:
type: string
required:
- city
strict: null
- type: response.completed
sequence_number: 14
response:
id: resp_673393d2de28449581eb6190a8168f84
object: response
created_at: 1775517028
completed_at: 1775517028
status: completed
model: gpt-oss-120b
output:
- id: rs_0c34dec41df941b2bce83e11a7614d31
type: reasoning
status: completed
summary: []
content:
- type: reasoning_text
text: The user wants to extract event info from a sentence. We need to output a JSON in the prescribed format.
- id: msg_3b1e13019bd84ebcbcf0c15f45f91dfe
type: message
role: assistant
status: completed
content:
- type: output_text
annotations: []
logprobs: []
text: "{\n \"title\": \"SambaNova demo\",\n \"date\": \"2026-04-18\",\n \"time\": \"15:30\",\n \"location\": \"San Francisco\"\n}\n"
usage:
input_tokens: 131
output_tokens: 280
total_tokens: 411
input_tokens_details:
cached_tokens: 0
text:
format:
type: json_schema
name: event_extraction
schema:
type: object
additionalProperties: false
properties:
title:
type: string
date:
type: string
time:
type: string
location:
type: string
required:
- title
- date
- time
- location
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
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: in_progress
model: gpt-oss-120b
output: []
usage: null
error: null
incomplete_details: null
instructions: null
metadata: {}
parallel_tool_calls: true
tool_choice: auto
tools: []
temperature: 1
top_p: 1
frequency_penalty: 0
presence_penalty: 0
reasoning:
effort: medium
summary: null
text:
format:
type: text
truncation: disabled
store: false
background: false
service_tier: free
ResponseRequest:
title: Response Request
type: object
description: responses request object
additionalProperties: true
properties:
model:
title: Model
description: The model ID to use (e.g. gpt-oss-120b). See available [models](https://docs.sambanova.ai/docs/en/models/sambacloud-models)
anyOf:
- type: string
- enum:
- gpt-oss-120b
- MiniMax-M2.5
- MiniMax-M2.7
input:
title: Input
description: Text input to the model, or a structured list of input items representing the full conversation turn. A plain string is equivalent to a sin
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sambanova-systems/refs/heads/main/openapi/sambanova-systems-responses-api-openapi.yml