SambaNova Systems Messages API
The Messages API from SambaNova Systems — 2 operation(s) for messages.
OpenAPI Specification
openapi: 3.1.0
info:
title: Sambanova Agents Service Audio Messages 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: Messages
paths:
/messages:
post:
operationId: createMessage
tags:
- Messages
summary: Create a message
description: 'Anthropic Messages API compatible endpoint. Generates a model response for the supplied conversation. Authentication accepts either the bearer `Authorization: Bearer <key>` header (SambaNova SDK default) or the `x-api-key` header (Anthropic SDK default); the same API key is used in both cases. When `stream: true` is set, the response is a sequence of Server-Sent Events whose payloads conform to `MessageStreamEvent`; otherwise the response is a single `Message` object.'
security:
- api_key: []
- x_api_key: []
parameters:
- in: header
name: anthropic-version
required: false
description: Anthropic API version header sent by the official `anthropic` SDK. Accepted (any value) but currently has no effect on response shape — included for drop-in SDK compatibility.
schema:
title: Anthropic Version
type: string
example: '2023-06-01'
requestBody:
required: true
description: Message creation parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCreateRequest'
responses:
'200':
description: 'Successful response. Returns a `Message` object (non-streaming), or a stream of Server-Sent Events whose payloads conform to `MessageStreamEvent` ending with a `message_stop` event (when `stream: true`).'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Message'
- $ref: '#/components/schemas/MessageStreamEvent'
'400':
description: Bad Request — `invalid_request_error`. Returned for missing or invalid parameters, unsupported feature flags (e.g. `thinking` with `type:"enabled"` or `"adaptive"`), unsupported tool types (`web_search`, `code_execution`, `bash`, `text_editor`, `memory`, `tool_search` variants), image source `type:"url"`, `document` content blocks, or non-object request bodies.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'401':
description: Unauthorized — `authentication_error`. Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'403':
description: Forbidden — `permission_error`. API key lacks access to the requested resource.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'404':
description: Not Found — `not_found_error`. Model does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'413':
description: Payload Too Large — `request_too_large`. Request exceeds the maximum allowed size.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'429':
description: Too Many Requests — `rate_limit_error`. Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'500':
description: Internal Server Error — `api_error`. Unexpected issue on the server side.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'501':
description: 'Not Implemented — `not_implemented_error`. Currently returned when `stream: true` is set, until streaming support lands (PRD Phase 4).'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'503':
description: Service Unavailable — `overloaded_error`. Backend is temporarily over capacity.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
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 message = await client.messages.create({\n max_tokens: 1024,\n messages: [{ content: 'Hello, Claude!', role: 'user' }],\n model: 'DeepSeek-V3.1',\n});\n\nconsole.log(message);"
- 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 message in client.messages.create(\n max_tokens=1024,\n messages=[{\n \"content\": \"Hello, Claude!\",\n \"role\": \"user\",\n }],\n model=\"DeepSeek-V3.1\",\n):\n print(message)"
/messages/count_tokens:
post:
operationId: countMessageTokens
tags:
- Messages
summary: Count tokens for a message request
description: 'Anthropic `count_tokens` compatible endpoint. Returns the number of input tokens that would be consumed by a `POST /messages` call with the same prompt content (system, messages, tools, tool_choice). Authentication accepts either the bearer `Authorization: Bearer <key>` header (SambaNova SDK default) or the `x-api-key` header (Anthropic SDK default); the same API key is used in both cases.'
security:
- api_key: []
- x_api_key: []
parameters:
- in: header
name: anthropic-version
required: false
description: Anthropic API version header sent by the official `anthropic` SDK. Accepted (any value) but currently has no effect on response shape - included for drop-in SDK compatibility.
schema:
title: Anthropic Version
type: string
example: '2023-06-01'
requestBody:
required: true
description: Token counting parameters (subset of message creation parameters).
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCountTokensRequest'
responses:
'200':
description: Successful response. Returns the input token count.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCountTokensResponse'
'400':
description: Bad Request — `invalid_request_error`. Returned for missing or invalid parameters, unsupported feature flags, unsupported tool types, image source `type:"url"`, `document` content blocks, or non-object request bodies.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'401':
description: Unauthorized — `authentication_error`. Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'403':
description: Forbidden — `permission_error`. API key lacks access to the requested resource.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'404':
description: Not Found — `not_found_error`. Model does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'413':
description: Payload Too Large — `request_too_large`. Request exceeds the maximum allowed size.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'429':
description: Too Many Requests — `rate_limit_error`. Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'500':
description: Internal Server Error — `api_error`. Unexpected issue on the server side.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'503':
description: Service Unavailable — `overloaded_error`. Backend is temporarily over capacity.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
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 messageCountTokensResponse = await client.messages.countTokens({\n messages: [{ content: 'Hello, Claude!', role: 'user' }],\n model: 'DeepSeek-V3.1',\n});\n\nconsole.log(messageCountTokensResponse.input_tokens);"
- 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)\nmessage_count_tokens_response = client.messages.count_tokens(\n messages=[{\n \"content\": \"Hello, Claude!\",\n \"role\": \"user\",\n }],\n model=\"DeepSeek-V3.1\",\n)\nprint(message_count_tokens_response.input_tokens)"
components:
schemas:
MessageThinkingConfig:
title: Message Thinking Config
description: 'Controls Anthropic-style extended thinking. **In v1**: only `type:"disabled"` is silently accepted as a no-op; `type:"enabled"` and `type:"adaptive"` return a 400 `invalid_request_error` (`unsupported_parameter`).'
oneOf:
- $ref: '#/components/schemas/MessageThinkingDisabled'
- $ref: '#/components/schemas/MessageThinkingEnabled'
- $ref: '#/components/schemas/MessageThinkingAdaptive'
discriminator:
propertyName: type
mapping:
disabled: '#/components/schemas/MessageThinkingDisabled'
enabled: '#/components/schemas/MessageThinkingEnabled'
adaptive: '#/components/schemas/MessageThinkingAdaptive'
MessageThinkingDisabled:
title: Message Thinking Disabled
type: object
description: 'Disables Anthropic-style extended thinking. **In v1**: silently accepted as a no-op'
properties:
type:
title: Type
type: string
enum:
- disabled
const: disabled
required:
- type
MessageCountTokensRequest:
title: Message Count Tokens Request
type: object
description: Request body for `POST /messages/count_tokens`. Returns the input token count for a prompt without generating output. Same prompt shape as `MessageCreateRequest` minus generation-time parameters (`max_tokens`, `stream`, sampling, `stop_sequences`, `metadata`, `service_tier`, etc.).
additionalProperties: true
properties:
model:
title: Model
type: string
description: Model identifier.
example: gpt-oss-120b
messages:
title: Messages
type: array
minItems: 1
items:
$ref: '#/components/schemas/MessageInputMessage'
description: Conversation turns.
system:
$ref: '#/components/schemas/MessageSystemPrompt'
thinking:
$ref: '#/components/schemas/MessageThinkingConfig'
tools:
title: Tools
type: array
items:
$ref: '#/components/schemas/MessageTool'
nullable: true
description: Tool definitions the model may call.
tool_choice:
allOf:
- $ref: '#/components/schemas/MessageToolChoice'
nullable: true
description: Controls how the model selects from `tools`.
required:
- model
- messages
example:
model: DeepSeek-V3.1
messages:
- role: user
content: Hello, Claude!
MessageOutputTextEditorCodeExecutionToolResultBlock:
title: Message Output Text Editor Code Execution Tool Result Block
type: object
description: Anthropic compatibility only — SambaNova does not run server-side text-editor code execution. Never emitted in responses.
properties:
type:
type: string
enum:
- text_editor_code_execution_tool_result
const: text_editor_code_execution_tool_result
tool_use_id:
type: string
content:
type: object
additionalProperties: true
required:
- type
- tool_use_id
- content
MessageInputVideoSourceUrl:
title: Message Input Video Source (URL)
type: object
description: HTTPS URL pointing to a video.
properties:
type:
type: string
enum:
- url
const: url
url:
type: string
format: uri
required:
- type
- url
MessageOutputToolUseBlock:
title: Message Output Tool Use Block
type: object
description: Tool call generated by the model.
properties:
type:
type: string
enum:
- tool_use
const: tool_use
id:
type: string
description: Unique identifier for this tool call.
name:
type: string
description: Name of the tool being called.
input:
type: object
additionalProperties: true
description: Tool inputs as a JSON object.
caller:
type: object
additionalProperties: true
nullable: true
description: Anthropic routing metadata. Always `null` in SambaNova responses.
required:
- type
- id
- name
- input
MessageOutputCodeExecutionToolResultBlock:
title: Message Output Code Execution Tool Result Block
type: object
description: Anthropic compatibility only — SambaNova does not run server-side `code_execution`. Never emitted in responses.
properties:
type:
type: string
enum:
- code_execution_tool_result
const: code_execution_tool_result
tool_use_id:
type: string
content:
type: object
additionalProperties: true
required:
- type
- tool_use_id
- content
MessageInputCodeExecutionToolResultBlock:
title: Message Input Code Execution Tool Result Block
type: object
description: Anthropic compatibility only — SambaNova does not run server-side `code_execution`. Echo of a prior Anthropic-served `code_execution` tool call; accepted in conversation history but never originates from a SambaNova response. When present, only `stdout`, `stderr`, and `return_code` are extracted; image output is dropped.
properties:
type:
type: string
enum:
- code_execution_tool_result
const: code_execution_tool_result
tool_use_id:
type: string
content:
type: object
additionalProperties: true
cache_control:
$ref: '#/components/schemas/MessageCacheControl'
required:
- type
- tool_use_id
- content
MessageError:
title: Message Error
type: object
description: Inner error object carried inside a `MessageErrorResponse`. The `type` value follows Anthropic's published error taxonomy.
properties:
type:
title: Type
type: string
description: Error category. Values follow Anthropic's taxonomy.
enum:
- invalid_request_error
- authentication_error
- permission_error
- not_found_error
- request_too_large
- rate_limit_error
- api_error
- overloaded_error
- not_implemented_error
message:
title: Message
type: string
description: Human-readable explanation of the error.
required:
- type
- message
MessageInputTextBlock:
title: Message Input Text Block
type: object
description: Plain-text segment of a message.
properties:
type:
type: string
enum:
- text
const: text
text:
type: string
cache_control:
$ref: '#/components/schemas/MessageCacheControl'
citations:
title: Citations
type: array
items:
type: object
additionalProperties: true
nullable: true
required:
- type
- text
MessageOutputRedactedThinkingBlock:
title: Message Output Redacted Thinking Block
type: object
description: Anthropic compatibility only — SambaNova does not produce encrypted thinking output. Never emitted in responses.
properties:
type:
type: string
enum:
- redacted_thinking
const: redacted_thinking
data:
type: string
required:
- type
- data
MessageThinkingEnabled:
title: Message Thinking Enabled
type: object
description: 'Enables Anthropic-style extended thinking with a fixed budget. **In v1**: returns a 400 `invalid_request_error` (`unsupported_parameter`).'
properties:
type:
title: Type
type: string
enum:
- enabled
const: enabled
budget_tokens:
title: Budget Tokens
type: integer
minimum: 1024
description: Maximum tokens the model may spend on extended thinking before producing the final answer.
required:
- type
- budget_tokens
MessageContentBlockStopEvent:
title: Content Block Stop Event
type: object
description: Closes the current content block.
properties:
type:
type: string
enum:
- content_block_stop
const: content_block_stop
index:
type: integer
description: Zero-based index of the block within `content[]`.
required:
- type
- index
MessageCacheControl:
title: Message Cache Control
type: object
description: 'Marks the preceding content block (or system text block) as a prompt- cache breakpoint. Marker positions are collected by the adapter; their wiring into the router''s longest-prefix matching **In v1**: position is recorded; the `ttl` value is ignored.'
properties:
type:
title: Type
type: string
enum:
- ephemeral
const: ephemeral
description: Cache breakpoint type. Only `ephemeral` is supported by Anthropic.
ttl:
title: TTL
type: string
description: Optional time-to-live hint (e.g. `"5m"`, `"1h"`). **Currently ignored** in v1
nullable: true
required:
- type
Message:
title: Message
type: object
description: Non-streaming response from `POST /messages`. Wire-compatible with the official Anthropic Messages API.
properties:
id:
type: string
description: Unique identifier for this message.
type:
type: string
enum:
- message
const: message
role:
type: string
enum:
- assistant
const: assistant
content:
type: array
items:
$ref: '#/components/schemas/MessageOutputContentBlock'
model:
type: string
description: Model that produced the response.
stop_reason:
allOf:
- $ref: '#/components/schemas/MessageStopReason'
nullable: true
stop_sequence:
type: string
nullable: true
description: The matched stop sequence that triggered termination. Present when `stop_reason` is `stop_sequence`; `null` otherwise.
stop_details:
allOf:
- $ref: '#/components/schemas/MessageStopDetails'
nullable: true
usage:
$ref: '#/components/schemas/MessageUsage'
container:
allOf:
- $ref: '#/components/schemas/MessageContainer'
nullable: true
required:
- id
- type
- role
- content
- model
- stop_reason
- usage
MessageOutputWebFetchToolResultBlock:
title: Message Output Web Fetch Tool Result Block
type: object
description: Anthropic compatibility only — SambaNova does not run server-side `web_fetch`. Never emitted in responses.
properties:
type:
type: string
enum:
- web_fetch_tool_result
const: web_fetch_tool_result
tool_use_id:
type: string
content:
type: object
additionalProperties: true
required:
- type
- tool_use_id
- content
MessageInputServerToolUseBlock:
title: Message Input Server Tool Use Block
type: object
description: Anthropic compatibility only — SambaNova does not run server-side tools. A prior assistant turn that invoked an Anthropic-hosted tool (web_search, code_execution, etc.). Accepted in conversation history (e.g. replaying an Anthropic-served session) but never originates from a SambaNova response. New `server_tool_use`-type tool definitions on outgoing requests are rejected with 400 `unsupported_tool_type`.
properties:
type:
type: string
enum:
- server_tool_use
const: server_tool_use
id:
type: string
name:
type: string
input:
type: object
additionalProperties: true
cache_control:
$ref: '#/components/schemas/MessageCacheControl'
required:
- type
- id
- name
- input
MessageContentBlockTextDelta:
title: Content Block Text Delta
type: object
description: Incremental text chunk for an open text content block.
properties:
type:
type: string
enum:
- text_delta
const: text_delta
text:
type: string
required:
- type
- text
MessageInputImageBlock:
title: Message Input Image Block
type: object
description: Image content. Only `source.type:"base64"` is supported in v1; URL sources return 400.
properties:
type:
type: string
enum:
- image
const: image
source:
oneOf:
- $ref: '#/components/schemas/MessageInputImageSourceBase64'
- $ref: '#/components/schemas/MessageInputImageSourceUrl'
discriminator:
propertyName: type
mapping:
base64: '#/components/schemas/MessageInputImageSourceBase64'
url: '#/components/schemas/MessageInputImageSourceUrl'
cache_control:
$ref: '#/components/schemas/MessageCacheControl'
required:
- type
- source
MessageInputRedactedThinkingBlock:
title: Message Input Redacted Thinking Block
type: object
description: Anthropic compatibility only — SambaNova does not produce encrypted thinking output. Echo of a prior Anthropic-served response where `thinking.display:"omitted"` was set. Accepted in conversation history but never originates from a SambaNova response. Silently dropped on input.
properties:
type:
type: string
enum:
- redacted_thinking
const: redacted_thinking
data:
type: string
required:
- type
- data
MessageOutputTextBlock:
title: Message Output Text Block
type: object
description: Plain-text segment of the model's response.
properties:
type:
type: string
enum:
- text
const: text
text:
type: string
citations:
type: array
items:
type: object
additionalProperties: true
nullable: true
description: Not emitted in v1.
required:
- type
- text
MessageOutputContainerUploadBlock:
title: Message Output Container Upload Block
type: object
description: Anthropic compatibility only — SambaNova does not produce container_upload blocks (these come from Anthropic's server-side `code_execution` tool). Never emitted in responses.
properties:
type:
type: string
enum:
- container_upload
const: container_upload
file_id:
type: string
required:
- type
- file_id
MessageContainer:
title: Message Container
type: object
description: Code-execution container reference. Anthropic compatibility only — SambaNova does not run server-side code execution, so this field is never emitted on responses.
properties:
id:
type: string
expires_at:
type: string
description: ISO-8601 timestamp.
required:
- id
- expires_at
MessageToolChoiceNone:
title: Message Tool Choice (None)
type: object
description: Forbid the model from calling any tool.
properties:
type:
type: string
enum:
- none
const: none
required:
- type
MessageStopEvent:
title: Message Stop Event
type: object
description: Final event of the stream. No fields beyond `type`.
properties:
type:
type: string
enum:
- message_stop
const: message_stop
required:
- type
MessageUsage:
title: Message Usage
type: object
description: Token accounting for the request.
properties:
input_tokens:
type: integer
description: Total tokens in the prompt (system + messages + tools).
output_tokens:
type: integer
description: Total tokens generated by the model.
cache_creation_input_tokens:
type: integer
nullable: true
description: Tokens written to prompt cache. Absent in v1; emitted once prompt caching wiring lands (CP-2897).
cache_read_input_tokens:
type: integer
nullable: true
description: Tokens read from prompt cache. Absent in v1; emitted once prompt caching wiring lands (CP-2897).
server_tool_use:
type: object
additionalProperties: true
nullable: true
description: Server-tool usage metrics (e.g. `web_search_requests`). Anthropic compatibility only — SambaNova does not run server tools, so this field is never emitted.
service_tier:
type: string
nullable: true
description: Service tier that processed the request. Anthropic compatibility only — SambaNova is single-tier and never emits this field.
cache_creation:
type: object
additionalProperties: true
nullable: true
description: Anthropic SDK alias for cache write metrics. Always `null` in SambaNova responses; use `cache_creation_input_tokens` instead.
inference_geo:
type: string
nullable: true
description: Geographic region that served the request. Anthropic compatibility only - SambaNova does not expose geo routing, always `null`.
required:
- input_tokens
- output_tokens
MessageOutputToolSearchToolResultBlock:
title: Message Output Tool Search Tool Result Block
type: object
description: Anthropic compatibility only — SambaNova does not run server-side `tool_search`. Never emitted in responses.
properties:
type:
type: string
enum:
- tool_search_tool_result
const: tool_search_tool_result
tool_use_id:
type: string
content:
type: object
additionalProperties: true
required:
- type
- tool_use_id
- content
MessageInputToolSearchToolResultBlock:
title: Message Input Tool Search Tool Result Block
type: object
description: Anthropic compatibility only — SambaNova does not run server-side `tool_search`. Echo of a prior Anthropic-served `tool_search` tool call; accepted in conversation history but never originates from a SambaNova response. When present, an empty string is emitted to the tool message (no plain-text fields).
properties:
type:
type: string
enum:
- tool_search_tool_result
const: tool_search_tool_result
tool_use_id:
type: string
content:
type: object
additionalProperties: true
cache_control:
$ref: '#/components/schemas/MessageCacheControl'
required:
- type
- tool_use_id
- content
MessageInputToolResultContent:
title: Message Input Tool Result Content
description: Content of a `tool_result` block. only text is forwarded.
oneOf:
- $ref: '#/components/schemas/MessageInputTextBlock'
- $ref: '#/components/schemas/MessageInputImageBlock'
discriminator:
propertyName: type
mapping:
text: '#/components/schemas/MessageInputTextBlock'
image: '#/components/schemas/MessageInputImageBlock'
MessageContentBlockInputJsonDelta:
title: Content Block Input JSON Delta
type: object
description: Incremental fragment of a tool_use block's `input` JSON. Concatenate successive `partial_json` strings to reconstruct the full input object.
properties:
type:
type: string
enum:
- input_json_delta
const: input_json_delta
partial_json:
type: string
required:
- type
- partial_json
MessageStartEvent:
title: Message Start Event
type: object
description: 'First event of a stream. Carries the initial Message envelope (empty `content[]`, `stop_reason: null`) and token usage from prompt processing.'
properties:
type:
type: string
enum:
- message_start
const: message_start
message:
$ref: '#/components/schemas/Message'
required:
- type
- message
MessageErrorResponse:
title: Message Error Response
type: object
description: Top-level error envelope returned by the Messages API on any non-2xx response. Shape matches Anthropic's wire format. This envelope is used ONLY on `/messages` and `/messages/count_tokens`
properties:
type:
title: Type
type: string
description: Always `error` for error envelopes.
enum:
- error
const: error
error:
$ref: '#/components/schemas/MessageError'
request_id:
title: Request Id
type: string
description: Opaque request identifier echoed by the server, useful for correlating client-side failures with server-side logs.
nullable: true
required:
- type
- error
MessageOutputThinkingBlock:
title: Message Output Thinking Block
type: object
description: Extended-reasoning trace from the model. Emitted by reasoning models.
properties:
type:
type: string
enum:
- thinking
const: thinking
thinking:
type: string
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sambanova-systems/refs/heads/main/openapi/sambanova-systems-messages-api-openapi.yml