> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grounded Completions
> Generate grounded completions with intelligent routing and retrieval-augmented generation (RAG).
Common errors: retrieval/source failures, no relevant content retrieved, plus all Completions V2 errors.
## OpenAPI
````yaml post /ai/v2/chat/completions/grounded
openapi: 3.1.0
info:
title: AI API
description: |-
Optimized for high-speed inference and scalability by Gloo AI
[Swagger UI](./docs) | [ReDoc UI](./redoc)
version: 1.0.0
servers:
- url: https://platform.ai.gloo.com
security:
- bearerAuth: []
tags:
- name: Content Controls
- name: Data Engine
- name: Ingestion & Enrichment
- name: answers
- name: chat
- name: completions
- name: content
- name: core
- name: data
- name: get-models
- name: ingestion
- name: sotc
paths:
/ai/v2/chat/completions/grounded:
post:
tags:
- completions
summary: Post grounded completions
description: >-
Generate grounded completions with intelligent routing and
retrieval-augmented generation (RAG).
operationId: post-completions-grounded
parameters:
- name: X-Cache-TTL
in: header
required: false
schema:
type: string
enum:
- 5m
- 1h
description: >-
Enables Anthropic prompt caching. When set, system messages are
automatically wrapped with cache_control blocks. '5m' bills cache
writes at 1.25x input rate, '1h' bills at 2x input rate. Only
effective for Anthropic models.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompletionsGroundedRequestBody'
examples:
auto_routing_grounded:
summary: Auto Routing with Grounded Sources
description: >-
Let the system select a model and ground the response with
retrieved sources
value:
messages:
- role: user
content: >-
What are practical ways to build stronger community in a
local church?
auto_routing: true
sources_limit: 3
tradition: evangelical
custom_publisher:
summary: Custom Publisher Grounding
description: Retrieve sources from a specific publisher before generation
value:
messages:
- role: user
content: What resources do you have on family counseling?
auto_routing: true
rag_publisher: YourPublisherName
sources_limit: 5
required: true
responses:
'200':
description: >-
Successful grounded completion response. If stream is false or
omitted, the response is JSON. If stream=true, the response is a
Server-Sent Events stream. Once streaming has started, failures are
delivered as stream events rather than non-2xx HTTP responses.
Content moderation ends the stream with a content_filter event. When
include_citations=true and citations are available, the first stream
event contains citations.
headers:
X-Sources-Returned:
description: Whether RAG was used to retrieve and ground the response.
schema:
type: string
enum:
- 'true'
- 'false'
content:
application/json:
schema:
$ref: '#/components/schemas/CompletionsGroundedResponse'
example:
id: gen-1769792268-xTKWyq7A9HmEhxzDsAJj
object: chat.completion
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.5
provider: Gloo AI
model_family: Anthropic
auto_routing: true
routing_mechanism: auto_routing
routing_tier: tier_3
routing_confidence: 0.782
tradition: evangelical
sources_returned: true
citations:
- item_title: Daily Prayer
item_url: https://www.studio.ai.gloo.com
author:
- John Doe
publisher: The Publisher
publication_date: Apr 08 2017
snippets:
- Daily prayer is an essential part of life as...
- Making time to spend with the Lord is...
choices:
- finish_reason: stop
index: 0
message:
content: >-
Based on the retrieved sources, here are practical ways
to build stronger community...
role: assistant
usage:
completion_tokens: 592
prompt_tokens: 2137
total_tokens: 2729
text/event-stream:
schema:
description: >-
JSON payloads sent in Server-Sent Events `data:` lines. A
stream can include content chunks, usage chunks, error chunks,
content-filter terminal chunks, and grounded citation events.
anyOf:
- $ref: '#/components/schemas/ChatCompletionStreamChunk'
- $ref: '#/components/schemas/AiStreamErrorChunk'
- $ref: '#/components/schemas/AiStreamContentFilterChunk'
- $ref: '#/components/schemas/GroundedCitationsStreamEvent'
x-event-payload-schemas:
- '#/components/schemas/ChatCompletionStreamChunk'
- '#/components/schemas/AiStreamErrorChunk'
- '#/components/schemas/AiStreamContentFilterChunk'
- '#/components/schemas/GroundedCitationsStreamEvent'
examples:
citations_event:
summary: Grounded citations event
description: >-
First SSE payload when stream=true, include_citations=true,
and citations are available.
value:
citations:
- item_title: Daily Prayer
item_url: https://www.studio.ai.gloo.com
author:
- John Doe
publisher: The Publisher
publication_date: Apr 08 2017
snippets:
- Daily prayer is an essential part of life as...
- Making time to spend with the Lord is...
normal_chunk:
summary: Streaming content chunk
description: >-
Normal chat completion SSE payload emitted while
stream=true.
value:
id: chatcmpl-stream-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: 'Grace and peace '
role: null
function_call: null
refusal: null
tool_calls: null
finish_reason: null
index: 0
logprobs: null
service_tier: null
usage: null
usage_chunk:
summary: Streaming usage chunk
description: >-
Optional usage payload emitted when
stream_options.include_usage=true.
value:
id: chatcmpl-usage-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices: []
service_tier: null
usage:
prompt_tokens: 25
completion_tokens: 150
total_tokens: 175
completion_tokens_details: null
prompt_tokens_details: null
provider_timeout:
summary: Provider timeout after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: The provider did not respond in time. Please try again.
type: timeout_error
code: 2001
name: PROVIDER_TIMEOUT
category: provider_error
description: >-
The upstream model provider did not respond within the
allowed time window.
fault: provider
retryable: true
trace_id: trace-id
connection_drop:
summary: Connection dropped after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Stream connection dropped
type: connection_error
code: 2003
name: CONNECTION_ERROR
category: provider_error
description: >-
The connection to the upstream model provider was lost
or could not be established.
fault: provider
retryable: true
trace_id: trace-id
rate_limit:
summary: Provider rate limit after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Rate limit reached. Please try again later.
type: rate_limit_error
code: 2004
name: RATE_LIMIT
category: provider_error
description: >-
The upstream model provider's rate limit was reached for
this request.
fault: provider
retryable: true
trace_id: trace-id
provider_5xx:
summary: Provider error after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Provider error occurred mid-stream.
type: connection_error
code: 2003
name: CONNECTION_ERROR
category: provider_error
description: >-
The connection to the upstream model provider was lost
or could not be established.
fault: provider
retryable: true
trace_id: trace-id
provider_bad_request:
summary: Provider rejected request after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Streaming error occurred
type: internal_error
code: 2008
name: PROVIDER_BAD_REQUEST
category: provider_error
description: >-
The upstream provider rejected the request with a 400
error.
fault: provider
retryable: false
trace_id: trace-id
provider_auth_error:
summary: Provider auth error after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Streaming error occurred
type: internal_error
code: 3003
name: PROVIDER_AUTH_ERROR
category: platform_error
description: Service temporarily unavailable.
fault: internal
retryable: false
trace_id: trace-id
routing_error:
summary: Provider routing error after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Streaming error occurred
type: internal_error
code: 3004
name: ROUTING_ERROR
category: platform_error
description: >-
The platform routed the request to an endpoint that does
not recognize the model.
fault: internal
retryable: false
trace_id: trace-id
unsupported_model:
summary: Unsupported model after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: The requested model is not supported.
type: invalid_request_error
code: 1003
name: UNSUPPORTED_MODEL
category: client_error
description: >-
The requested model is not recognized or not available
in this environment.
fault: client
retryable: false
trace_id: trace-id
empty_stream:
summary: Provider opened an empty stream
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Stream returned no content
type: internal_error
code: 2007
name: EMPTY_STREAM
category: provider_error
description: >-
The upstream provider opened a stream but delivered no
content chunks.
fault: provider
retryable: true
trace_id: trace-id
provider_unavailable:
summary: Provider unavailable after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: The provider is currently unavailable.
type: service_unavailable_error
code: 2002
name: PROVIDER_UNAVAILABLE
category: provider_error
description: The upstream model provider is temporarily unavailable.
fault: provider
retryable: true
trace_id: trace-id
malformed_sse:
summary: Malformed provider SSE
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Streaming error occurred
type: internal_error
code: 2011
name: MALFORMED_SSE
category: provider_error
description: >-
The upstream provider sent a malformed SSE frame that
could not be parsed.
fault: provider
retryable: true
trace_id: trace-id
internal_error:
summary: Unexpected platform error after stream start
value:
id: chatcmpl-error-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: null
role: null
finish_reason: error
index: 0
service_tier: null
usage: null
error:
message: Streaming error occurred
type: internal_error
code: 3001
name: INTERNAL_ERROR
category: platform_error
description: An unexpected internal error occurred on the platform.
fault: internal
retryable: false
trace_id: trace-id
content_filter_message:
summary: Content filter termination message
description: >-
Provider/output moderation sends a final assistant message
rather than a top-level error object.
value:
id: chatcmpl-stream-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: >-
The response was stopped because it may violate
content safety policies.
role: null
finish_reason: null
index: 0
service_tier: null
usage: null
content_filter_stop:
summary: Content filter terminal chunk
description: >-
Terminal chunk following the localized content-filter
termination message.
value:
id: chatcmpl-stream-abc123
object: chat.completion.chunk
created: 1769792268
model: gloo-anthropic-claude-sonnet-4.6
choices:
- delta:
content: ''
finish_reason: content_filter
index: 0
service_tier: null
usage: null
'400':
description: >-
Bad Request - Invalid routing configuration or missing required
fields
content:
application/json:
schema:
oneOf:
- type: object
required:
- detail
properties:
detail:
description: Plain validation or routing error detail.
additionalProperties: false
- $ref: '#/components/schemas/AiErrorResponse'
examples:
routing_configuration:
summary: Invalid routing configuration
value:
detail: >-
Exactly one routing mechanism (auto_routing, model, or
model_family) must be specified.
invalid_request:
summary: Invalid request
value:
detail: No user message found in the request.
error:
message: No user message found in the request.
type: invalid_request_error
code: 1001
name: INVALID_REQUEST
category: client_error
description: The request is malformed or contains invalid parameters.
fault: client
retryable: false
trace_id: trace-id
'401':
description: Unauthorized - Invalid or missing authentication token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: Invalid or expired access token.
'403':
description: Forbidden - Request blocked by policy or authorization
content:
application/json:
schema:
additionalProperties: true
type: object
example:
detail:
message: Your request was rejected as it violates content policies.
type: content_policy_violation
code: content_policy_violation
retryable: false
'408':
description: Request Timeout - Provider did not respond in time
content:
application/json:
schema:
$ref: '#/components/schemas/AiErrorResponse'
example:
detail: The provider did not respond in time. Please try again.
error:
message: The provider did not respond in time. Please try again.
type: timeout_error
code: 2001
name: PROVIDER_TIMEOUT
category: provider_error
description: >-
The upstream model provider did not respond within the
allowed time window.
fault: provider
retryable: true
trace_id: trace-id
'422':
description: Validation Error or provider response moderation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/HTTPValidationError'
- $ref: '#/components/schemas/AiErrorResponse'
examples:
validation_error:
summary: Request validation error
value:
detail:
- type: missing
loc:
- body
- model
msg: Field required
input: {}
response_moderated:
summary: Provider moderated the response
value:
detail: The provider moderated the response.
error:
message: The provider moderated the response.
type: content_filter_error
code: 2005
name: PROVIDER_CONTENT_FILTER
category: provider_error
description: >-
The response was blocked by the upstream provider's
content filter.
fault: provider
retryable: false
trace_id: trace-id
'429':
description: Too Many Requests - Spending limit reached
content:
application/json:
schema:
$ref: '#/components/schemas/AiErrorResponse'
example:
detail:
message: Spending limit reached
code: SPENDING_LIMIT_EXCEEDED
error:
message: Spending limit reached
type: billing_error
code: 1005
name: SPENDING_LIMIT_EXCEEDED
category: client_error
description: The account's spending limit has been reached.
fault: client
retryable: false
trace_id: trace-id
'500':
description: >-
Internal Server Error - Provider authentication, inference, RAG, or
unexpected server failure
content:
application/json:
schema:
$ref: '#/components/schemas/AiErrorResponse'
example:
detail: >-
An unexpected error occurred during model inference. Please
try again.
error:
message: >-
An unexpected error occurred during model inference. Please
try again.
type: internal_error
code: 2013
name: PROVIDER_INFERENCE_ERROR
category: provider_error
description: >-
An unexpected error occurred during model inference at the
upstream provider.
fault: provider
retryable: true
trace_id: trace-id
'503':
description: Service Unavailable - Provider or backing service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/AiErrorResponse'
example:
detail: The provider is currently unavailable. Please try again later.
error:
message: >-
The provider is currently unavailable. Please try again
later.
type: service_unavailable_error
code: 2002
name: PROVIDER_UNAVAILABLE
category: provider_error
description: The upstream model provider is temporarily unavailable.
fault: provider
retryable: true
trace_id: trace-id
components:
schemas:
CompletionsGroundedRequestBody:
type: object
title: CompletionsGroundedRequestBody
description: >-
Request body for the grounded completions endpoint. Exactly one routing
mechanism (auto_routing, model, or model_family) must be specified.
Messages are optional when omitted and default to a single user message
of "Hello world!". An explicit empty messages array is invalid and
returns 400.
required: []
properties:
messages:
type: array
items:
$ref: '#/components/schemas/LlmMessage'
title: Messages
description: >-
Chat message history with role and content fields. If omitted, the
current service defaults to one user message with content "Hello
world!". Explicitly passing an empty array is invalid.
default:
- role: user
content: Hello world!
auto_routing:
type: boolean
title: Auto Routing
description: >-
Enables intelligent model selection. Mutually exclusive with model
and model_family.
model:
type: string
title: Model
description: >-
Specific Gloo model identifier. Mutually exclusive with auto_routing
and model_family.
model_family:
$ref: '#/components/schemas/ModelFamily'
description: >-
Provider family for model selection. Mutually exclusive with
auto_routing and model.
rag_publisher:
type: string
title: RAG Publisher
description: >-
Publisher name to retrieve sources from. Defaults to GlooGrounded
when omitted.
default: GlooGrounded
sources_limit:
type: integer
minimum: 1
maximum: 10
title: Sources Limit
description: Number of sources to retrieve for grounding (1-10).
default: 3
tradition:
$ref: '#/components/schemas/Tradition'
description: >-
Theological perspective to apply. Options: evangelical, catholic,
mainline, not_faith_specific.
stream:
type: boolean
title: Stream
description: Enables streaming responses via server-sent events.
default: false
temperature:
type: number
minimum: 0
maximum: 2
title: Temperature
description: Sampling temperature controlling randomness.
default: 0.7
max_tokens:
type: integer
minimum: 1
title: Max Tokens
description: Maximum number of tokens to generate in the response.
tools:
type: array
items:
$ref: '#/components/schemas/Tool'
title: Tools
description: Function calling definitions.
tool_choice:
anyOf:
- type: string
enum:
- none
- auto
- required
- $ref: '#/components/schemas/ToolChoiceFunctionOption'
title: Tool Choice
description: Controls which tool (if any) the model should use.
default: none
prompt_cache_key:
type: string
title: Prompt Cache Key
description: >-
OpenAI Responses API cache key for persistent prompt caching. When
set, the prompt prefix is cached and reused across requests with the
same key, reducing cost and latency. Cache TTL is 5 minutes
(server-side). Only effective for OpenAI models. Ignored for other
providers.
parallel_tool_calls:
type: boolean
title: Parallel Tool Calls
description: Allow parallel tool execution.
default: true
include_citations:
type: boolean
title: Include Citations
description: >-
Include citation metadata for sources utilized by RAG. For streaming
responses, citations are prepended as the first SSE event before any
content chunks.
default: false
stream_options:
$ref: '#/components/schemas/StreamOptions'
description: >-
Streaming options. Use include_usage=true with stream=true to
receive a final usage event.
CompletionsGroundedResponse:
type: object
title: CompletionsGroundedResponse
description: Response from the grounded completions endpoint.
properties:
id:
type: string
description: Unique completion identifier.
object:
type: string
description: Object type, always 'chat.completion'.
default: chat.completion
created:
type: integer
description: Unix timestamp of when the completion was created.
model:
type: string
description: The model that was selected and used for the completion.
provider:
type: string
description: The model provider name.
model_family:
type: string
description: Provider family of the selected model.
auto_routing:
type: boolean
description: Indicates whether auto routing was used.
routing_mechanism:
type: string
description: >-
The routing method used: auto_routing, model_family, or
direct_model_selection.
routing_tier:
type: string
description: The performance tier assigned by the routing system.
routing_confidence:
type: number
description: Confidence score for the routing decision (0.0 to 1.0).
tradition:
type: string
description: The theological perspective that was applied to the response.
sources_returned:
type: boolean
description: Whether RAG was used to retrieve sources and ground the response.
citations:
anyOf:
- type: array
items:
$ref: '#/components/schemas/CitationObject'
- type: 'null'
description: >-
Array of source citations used to ground the response. Only present
when include_citations is true in the request.
choices:
type: array
items:
$ref: '#/components/schemas/CompletionsV2Choice'
description: List of completion choices.
usage:
$ref: '#/components/schemas/CompletionsV2Usage'
description: Token consumption metrics.
service_tier:
type: 'null'
system_fingerprint:
type: 'null'
ChatCompletionStreamChunk:
type: object
title: Content or Usage Event
description: >-
JSON payload carried in each `data:` line of a chat completion
Server-Sent Events stream.
required:
- id
- object
- created
- model
- choices
properties:
id:
type: string
object:
type: string
enum:
- chat.completion.chunk
created:
type: integer
model:
type: string
choices:
type: array
items:
$ref: '#/components/schemas/ChatCompletionStreamChoice'
usage:
anyOf:
- $ref: '#/components/schemas/ChatCompletionStreamUsage'
- type: 'null'
service_tier:
type:
- string
- 'null'
system_fingerprint:
type:
- string
- 'null'
ttft_ms:
type:
- number
- 'null'
additionalProperties: true
AiStreamErrorChunk:
title: Error Event
allOf:
- $ref: '#/components/schemas/ChatCompletionStreamChunk'
- type: object
title: Error Event
description: >-
SSE payload emitted after stream headers have already been sent and
a provider/platform error occurs.
required:
- error
properties:
choices:
type: array
items:
type: object
properties:
finish_reason:
type: string
enum:
- error
additionalProperties: true
error:
$ref: '#/components/schemas/AiError'
additionalProperties: true
AiStreamContentFilterChunk:
title: Content Filter Event
allOf:
- $ref: '#/components/schemas/ChatCompletionStreamChunk'
- type: object
title: Content Filter Event
description: >-
Terminal SSE payload used when provider/output moderation stops a
stream without emitting a top-level error object.
properties:
choices:
type: array
items:
type: object
properties:
finish_reason:
type: string
enum:
- content_filter
additionalProperties: true
additionalProperties: true
GroundedCitationsStreamEvent:
type: object
title: Citations Event
description: >-
First SSE payload emitted by grounded streaming completions when
include_citations=true and citations are available.
required:
- citations
properties:
citations:
type: array
items:
$ref: '#/components/schemas/CitationObject'
additionalProperties: false
AiErrorResponse:
type: object
title: AiErrorResponse
description: >-
AI API error response with existing detail field plus enriched error
metadata.
required:
- detail
- error
properties:
detail:
description: Existing endpoint-specific error detail. May be a string or object.
error:
$ref: '#/components/schemas/AiError'
additionalProperties: true
Error:
type: object
properties:
detail:
type: string
description: A human-readable description of the error.
title: Error
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
LlmMessage:
properties:
role:
type: string
title: Role
description: Role of the message sender
default: user
content:
type: string
title: Content
description: Content of the message
default: Hello!
type: object
title: LlmMessage
ModelFamily:
type: string
enum:
- openai
- anthropic
- google
- open source
title: ModelFamily
description: The model provider family to use for routing.
Tradition:
type: string
enum:
- evangelical
- catholic
- mainline
- not_faith_specific
title: Tradition
description: Theological perspective to apply to responses.
Tool:
properties:
type:
type: string
title: Type
description: This field must be the literal string function.
default: function
function:
$ref: '#/components/schemas/ToolFunction'
description: Function attributes.
type: object
required:
- function
title: Tool
ToolChoiceFunctionOption:
properties:
function:
$ref: '#/components/schemas/ToolChoiceFunction'
description: The encapsulation of the chosen function to invoke.
type:
type: string
title: Type
description: This field must be the literal string function.
default: function
type: object
required:
- function
title: ToolChoiceFunctionOption
StreamOptions:
type: object
title: Stream Options
description: Options for streaming responses.
properties:
include_usage:
type: boolean
default: false
description: >-
When true and stream=true, emits a final usage event with token
counts before the stream closes.
additionalProperties: false
CitationObject:
type: object
title: CitationObject
description: A source citation used to ground the response.
properties:
item_title:
type: string
description: Title of the cited content item.
item_url:
type: string
description: URL of the cited content item.
author:
type: array
items:
type: string
description: List of authors of the cited item.
publisher:
type: string
description: Publisher of the cited item.
publication_date:
type: string
description: Publication date of the cited item.
snippets:
type: array
items:
type: string
description: Relevant text excerpts from the cited item used for grounding.
CompletionsV2Choice:
type: object
title: CompletionsV2Choice
properties:
finish_reason:
type: string
description: >-
The reason the model stopped generating tokens (e.g., stop, length,
tool_calls).
index:
type: integer
description: The index of this choice in the list of choices.
logprobs:
anyOf:
- type: object
description: Log probability information for the choice.
- type: 'null'
message:
type: object
properties:
content:
type: string
description: The generated message content.
role:
type: string
description: The role of the message author (assistant).
tool_calls:
anyOf:
- type: array
description: Tool calls generated by the model.
items:
type: object
- type: 'null'
refusal:
type: 'null'
annotations:
type: 'null'
audio:
type: 'null'
function_call:
type: 'null'
reasoning:
type: 'null'
native_finish_reason:
type: string
CompletionsV2Usage:
type: object
title: CompletionsV2Usage
description: Token consumption metrics for the completion.
properties:
completion_tokens:
type: integer
description: Number of tokens in the generated completion.
prompt_tokens:
type: integer
description: Number of tokens in the prompt.
total_tokens:
type: integer
description: Total number of tokens used (prompt + completion).
ChatCompletionStreamChoice:
type: object
title: Stream Choice
required:
- delta
- finish_reason
- index
properties:
delta:
$ref: '#/components/schemas/ChatCompletionStreamDelta'
finish_reason:
type:
- string
- 'null'
description: >-
Null while content is streaming; terminal values include stop,
error, content_filter, tool_calls, and function_call.
index:
type: integer
logprobs:
type:
- object
- 'null'
additionalProperties: true
additionalProperties: true
ChatCompletionStreamUsage:
type: object
title: Usage Details
required:
- prompt_tokens
- completion_tokens
- total_tokens
properties:
prompt_tokens:
type: integer
completion_tokens:
type: integer
total_tokens:
type: integer
completion_tokens_details:
type:
- object
- 'null'
additionalProperties: true
prompt_tokens_details:
type:
- object
- 'null'
additionalProperties: true
additionalProperties: true
AiError:
type: object
title: AiError
description: >-
Standard AI API error object emitted by global provider/model error
handlers.
required:
- message
- type
- code
- name
- category
- description
- fault
- retryable
- trace_id
properties:
message:
type: string
description: Request-specific customer-facing error message.
type:
type: string
description: Stable wire-format error type.
code:
type: integer
description: Stable numeric internal error code.
name:
type: string
description: Stable symbolic error code name.
category:
type: string
enum:
- client_error
- provider_error
- platform_error
description: Error category derived from the numeric code range.
description:
type: string
description: Stable one-sentence explanation of what the error code means.
fault:
type: string
enum:
- client
- provider
- internal
description: System responsible for the failure.
retryable:
type: boolean
description: Whether retrying the same request may succeed.
trace_id:
type:
- string
- 'null'
description: Sentry trace identifier when available.
additionalProperties: true
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ToolFunction:
properties:
name:
type: string
title: Name
description: Name of the function.
description:
type: string
title: Description
description: Description of the function.
parameters:
type: object
title: Parameters
description: Parameters to call the function.
default: {}
strict:
type: boolean
title: Strict
description: Whether to adhere strictly to the parameters definition.
default: false
type: object
required:
- name
- description
title: ToolFunction
ToolChoiceFunction:
properties:
name:
type: string
title: Name
description: The name of the chosen function to invoke.
type: object
required:
- name
title: ToolChoiceFunction
ChatCompletionStreamDelta:
type: object
title: Stream Delta
properties:
content:
type:
- string
- 'null'
role:
type:
- string
- 'null'
function_call:
type:
- object
- 'null'
additionalProperties: true
refusal:
type:
- string
- 'null'
tool_calls:
type:
- array
- 'null'
items:
additionalProperties: true
type: object
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form Bearer ``, where
`` is your [auth token](/studio/manage-api-credentials).
````