> ## Documentation Index
> Fetch the complete documentation index at: https://concentrate.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Message
> Anthropic Messages API compatibility endpoint for Claude Code and other clients
**Beta Feature**
The Messages API is currently in beta. It provides Anthropic Messages API compatibility for clients like Claude Code. For production use, we recommend using the [Responses API](/docs/api-reference/endpoint/create-response) instead.
## Overview
The Messages API provides compatibility with the Anthropic Messages API format. It's designed primarily for clients that expect Anthropic's API structure, such as Claude Code and other tools built for Claude's API.
## OpenAPI
````yaml POST /v1/messages/
openapi: 3.0.3
info:
title: Responses API
description: Unified responses API
version: 1.0.0
servers:
- url: https://api.concentrate.ai
security: []
paths:
/v1/messages/:
post:
tags:
- messages
- anthropic
description: >-
Anthropic Messages API compatibility endpoint for Claude Code and other
clients
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
model:
description: >-
Model identifier. Use /v1/models to list all available
models. Supports canonical names (e.g. gpt-5.2,
claude-opus-4-6), aliases, and provider-prefixed formats
(e.g. openai/gpt-5.2). Use "auto" for automatic model
selection.
type: string
provider:
description: One of 4616 allowed values.
type: string
messages:
minItems: 1
type: array
items:
type: object
properties:
role:
type: string
enum:
- user
- assistant
- system
content:
anyOf:
- type: string
- type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
title: Web Search Result Location
required:
- type
- text
title: Text
- type: object
properties:
type:
type: string
enum:
- image
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- image/jpeg
- image/png
- image/gif
- image/webp
data:
type: string
required:
- type
- media_type
- data
title: Base64
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
format: uri
required:
- type
- url
title: URL
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- source
title: Image
- type: object
properties:
type:
type: string
enum:
- document
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- application/pdf
data:
type: string
required:
- type
- media_type
- data
title: Base64 PDF
- type: object
properties:
type:
type: string
enum:
- text
media_type:
type: string
enum:
- text/plain
data:
type: string
required:
- type
- media_type
- data
title: Plain Text
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
required:
- type
- url
title: URL
- type: object
properties:
type:
type: string
enum:
- content
content:
type: array
items:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
title: Web Search Result Location
required:
- type
- text
required:
- type
- content
title: Content
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations: {}
context:
type: string
title:
type: string
required:
- type
- source
title: Document
- type: object
properties:
type:
type: string
enum:
- thinking
thinking:
type: string
signature:
type: string
required:
- type
- thinking
- signature
title: Thinking
- type: object
properties:
type:
type: string
enum:
- redacted_thinking
data:
type: string
required:
- type
- data
title: Redacted Thinking
- type: object
properties:
type:
type: string
enum:
- tool_use
id:
type: string
name:
type: string
input:
type: object
additionalProperties: {}
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- id
- name
- input
title: Tool Use
- type: object
properties:
type:
type: string
enum:
- tool_result
tool_use_id:
type: string
content:
anyOf:
- type: string
- type: array
items:
anyOf:
- type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
title: Web Search Result Location
required:
- type
- text
title: Text
- type: object
properties:
type:
type: string
enum:
- image
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- image/jpeg
- image/png
- image/gif
- image/webp
data:
type: string
required:
- type
- media_type
- data
title: Base64
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
format: uri
required:
- type
- url
title: URL
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- source
title: Image
- type: object
properties:
type:
type: string
enum:
- tool_reference
tool_name:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- tool_name
title: Tool Reference
- type: object
properties:
type:
type: string
enum:
- search_result
content:
type: array
items:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- {}
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
title: Web Search Result Location
required:
- type
- text
source:
type: string
title:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations: {}
required:
- type
- content
- source
- title
title: Search Result
- type: object
properties:
type:
type: string
enum:
- document
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- application/pdf
data:
type: string
required:
- type
- media_type
- data
title: Base64 PDF
- type: object
properties:
type:
type: string
enum:
- text
media_type:
type: string
enum:
- text/plain
data:
type: string
required:
- type
- media_type
- data
title: Plain Text
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
required:
- type
- url
title: URL
- type: object
properties:
type:
type: string
enum:
- content
content:
type: array
items:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations:
nullable: true
type: array
items:
oneOf:
- {}
required:
- type
- text
required:
- type
- content
title: Content
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations: {}
context:
type: string
title:
type: string
required:
- type
- source
title: Document
is_error:
type: boolean
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- tool_use_id
- content
title: Tool Result
- type: object
properties:
type:
type: string
enum:
- server_tool_use
name:
type: string
enum:
- web_search
id:
type: string
input:
type: object
additionalProperties: {}
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- name
- id
- input
title: Server Tool Use
- type: object
properties:
type:
type: string
enum:
- web_search_tool_result
tool_use_id:
type: string
content:
anyOf:
- type: object
properties:
type:
type: string
enum:
- web_search_tool_result_error
error_code:
type: string
enum:
- invalid_tool_input
- unavailable
- max_uses_exceeded
- query_too_long
required:
- type
- error_code
title: Error
- type: array
items:
type: object
properties:
type:
type: string
enum:
- web_search_result
encrypted_content:
type: string
page_age:
nullable: true
type: string
title:
type: string
url:
type: string
required:
- type
- encrypted_content
- title
- url
title: Search Results
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- tool_use_id
- content
title: Web Search Tool Result
required:
- role
- content
max_tokens:
type: integer
minimum: 0
exclusiveMinimum: true
maximum: 9007199254740991
cache_control:
nullable: true
allOf:
- $ref: '#/components/schemas/CacheControlInput'
metadata:
nullable: true
allOf:
- type: object
properties:
user_id:
type: string
- type: object
additionalProperties:
type: string
maxLength: 512
description: >-
Set of 16 key-value pairs that can be attached to an
object. This can be useful for storing additional
information about the object in a structured format, and
querying for objects via API or the dashboard. Keys are
strings with a maximum length of 64 characters. Values
are strings with a maximum length of 512 characters.
output_config:
nullable: true
type: object
properties:
effort:
nullable: true
type: string
enum:
- low
- medium
- high
- xhigh
- max
format:
nullable: true
type: object
properties:
type:
type: string
enum:
- json_schema
schema:
type: object
additionalProperties: {}
required:
- type
- schema
stream:
nullable: true
type: boolean
system:
nullable: true
anyOf:
- type: string
- type: array
items:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
title: Web Search Result Location
required:
- type
- text
temperature:
nullable: true
type: number
minimum: 0
maximum: 1
thinking:
nullable: true
oneOf:
- type: object
properties:
budget_tokens:
type: number
minimum: 1024
type:
type: string
enum:
- enabled
display:
nullable: true
type: string
enum:
- summarized
- omitted
required:
- type
title: Enabled
- type: object
properties:
type:
type: string
enum:
- disabled
required:
- type
title: Disabled
- type: object
properties:
type:
type: string
enum:
- adaptive
display:
nullable: true
type: string
enum:
- summarized
- omitted
required:
- type
title: Adaptive
tool_choice:
nullable: true
oneOf:
- type: object
properties:
type:
type: string
enum:
- auto
disable_parallel_tool_use:
nullable: true
type: boolean
required:
- type
title: Auto
- type: object
properties:
type:
type: string
enum:
- any
disable_parallel_tool_use:
nullable: true
type: boolean
required:
- type
title: Any
- type: object
properties:
type:
type: string
enum:
- tool
name:
type: string
disable_parallel_tool_use:
nullable: true
type: boolean
required:
- type
- name
title: Tool
- type: object
properties:
type:
type: string
enum:
- none
required:
- type
title: None
tools:
type: array
items:
oneOf:
- type: object
properties:
type:
nullable: true
type: string
enum:
- custom
name:
type: string
maxLength: 256
description: >-
The name. Must contain only alphanumeric
characters, underscores, dots, and hyphens, with a
maximum length of 256 characters, with a minimum
length of 1 character after unaccepted characters
are stripped.
input_schema:
type: object
additionalProperties: {}
description:
nullable: true
type: string
strict:
nullable: true
type: boolean
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- name
- input_schema
title: Custom Tool
- type: object
properties:
type:
type: string
enum:
- web_search_20250305
name:
type: string
enum:
- web_search
allowed_domains:
nullable: true
type: array
items:
type: string
blocked_domains:
nullable: true
type: array
items:
type: string
max_uses:
nullable: true
type: integer
minimum: 0
maximum: 9007199254740991
user_location:
allOf:
- $ref: '#/components/schemas/UserLocationInput'
nullable: true
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControlInput'
required:
- type
- name
title: Web Search Tool
top_p:
nullable: true
type: number
minimum: 0
maximum: 1
container:
nullable: true
type: string
inference_geo:
nullable: true
type: string
service_tier:
nullable: true
type: string
stop_sequences:
nullable: true
type: array
items:
type: string
top_k:
nullable: true
type: integer
minimum: 0
exclusiveMinimum: true
maximum: 9007199254740991
routing:
nullable: true
type: object
properties:
model:
nullable: true
type: object
properties:
fallbacks:
nullable: true
type: array
items:
description: One of 4616 allowed values.
type: string
description: >-
Ordered list of models to fall back to if the
primary model is unavailable or fails.
Using auto in the fallbacks will move it to the end
of the fallback list, and can be used to
continuously try models until one succeeds.
sort:
nullable: true
default: performance
description: >-
The metric used to sort and select among routing
candidates, such as cost, performance, or a
percentile latency metric (e.g. p95_latency).
Defaults to performance.
All metrics are cached for the most recent 15
minutes (except percentile latencies other than p50,
p90, and p99).
anyOf:
- type: string
enum:
- cost
- performance
- total_requests
- uptime
- throughput
- avg_latency
- latency
- avg_e2e_latency
- e2e_latency
- input_tokens
- output_tokens
- total_tokens
- type: string
pattern: ^p([0-9]|[1-9][0-9]|100)_(latency|e2e_latency)$
description: Model-level routing configuration.
provider:
nullable: true
type: object
properties:
fallbacks:
nullable: true
type: array
items:
type: string
description: One of 65 allowed values.
description: >-
Ordered list of providers to fall back to if the
primary provider is unavailable or fails.
sort:
nullable: true
default: performance
description: >-
The metric used to sort and select among routing
candidates, such as cost, performance, or a
percentile latency metric (e.g. p95_latency).
Defaults to performance.
All metrics are cached for the most recent 15
minutes (except percentile latencies other than p50,
p90, and p99).
anyOf:
- type: string
enum:
- cost
- performance
- total_requests
- uptime
- throughput
- avg_latency
- latency
- avg_e2e_latency
- e2e_latency
- input_tokens
- output_tokens
- total_tokens
- type: string
pattern: ^p([0-9]|[1-9][0-9]|100)_(latency|e2e_latency)$
interval:
nullable: true
description: >-
The time window over which routing metrics are
evaluated. Can be written as '1h' or '1 hour'.
Defaults to 15 minutes.
All metrics are cached for the most recent 15
minutes (except percentile latencies other than p50,
p90, and p99). Any historical metrics longer than 15
minutes are then cached for 15 minutes upon request,
and are refreshed when you use those metrics again.
type: string
pattern: >-
^\d+(?:m| minutes|h| hours?|d| days?|w| weeks?|y|
years?)$
description: Provider-level routing configuration.
description: >-
Concentrate routing configuration controlling how requests
are routed across models and providers. Learn more about
routing.
required:
- messages
- max_tokens
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
type:
type: string
enum:
- message
role:
type: string
enum:
- assistant
model:
type: string
content:
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
additionalProperties: false
title: Web Search Result Location
required:
- type
- text
additionalProperties: false
title: Text
- type: object
properties:
type:
type: string
enum:
- image
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- image/jpeg
- image/png
- image/gif
- image/webp
data:
type: string
required:
- type
- media_type
- data
additionalProperties: false
title: Base64
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
format: uri
required:
- type
- url
additionalProperties: false
title: URL
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
required:
- type
- source
additionalProperties: false
title: Image
- type: object
properties:
type:
type: string
enum:
- document
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- application/pdf
data:
type: string
required:
- type
- media_type
- data
additionalProperties: false
title: Base64 PDF
- type: object
properties:
type:
type: string
enum:
- text
media_type:
type: string
enum:
- text/plain
data:
type: string
required:
- type
- media_type
- data
additionalProperties: false
title: Plain Text
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
required:
- type
- url
additionalProperties: false
title: URL
- type: object
properties:
type:
type: string
enum:
- content
content:
type: array
items:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
additionalProperties: false
title: Web Search Result Location
required:
- type
- text
additionalProperties: false
required:
- type
- content
additionalProperties: false
title: Content
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations: {}
context:
type: string
title:
type: string
required:
- type
- source
additionalProperties: false
title: Document
- type: object
properties:
type:
type: string
enum:
- thinking
thinking:
type: string
signature:
type: string
required:
- type
- thinking
- signature
additionalProperties: false
title: Thinking
- type: object
properties:
type:
type: string
enum:
- redacted_thinking
data:
type: string
required:
- type
- data
additionalProperties: false
title: Redacted Thinking
- type: object
properties:
type:
type: string
enum:
- tool_use
id:
type: string
name:
type: string
input:
type: object
additionalProperties: {}
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
required:
- type
- id
- name
- input
additionalProperties: false
title: Tool Use
- type: object
properties:
type:
type: string
enum:
- tool_result
tool_use_id:
type: string
content:
anyOf:
- type: string
- type: array
items:
anyOf:
- type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
additionalProperties: false
title: Web Search Result Location
required:
- type
- text
additionalProperties: false
title: Text
- type: object
properties:
type:
type: string
enum:
- image
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- image/jpeg
- image/png
- image/gif
- image/webp
data:
type: string
required:
- type
- media_type
- data
additionalProperties: false
title: Base64
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
format: uri
required:
- type
- url
additionalProperties: false
title: URL
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
required:
- type
- source
additionalProperties: false
title: Image
- type: object
properties:
type:
type: string
enum:
- tool_reference
tool_name:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
required:
- type
- tool_name
additionalProperties: false
title: Tool Reference
- type: object
properties:
type:
type: string
enum:
- search_result
content:
type: array
items:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
additionalProperties: false
title: Web Search Result Location
required:
- type
- text
additionalProperties: false
source:
type: string
title:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations: {}
required:
- type
- content
- source
- title
additionalProperties: false
title: Search Result
- type: object
properties:
type:
type: string
enum:
- document
source:
oneOf:
- type: object
properties:
type:
type: string
enum:
- base64
media_type:
type: string
enum:
- application/pdf
data:
type: string
required:
- type
- media_type
- data
additionalProperties: false
title: Base64 PDF
- type: object
properties:
type:
type: string
enum:
- text
media_type:
type: string
enum:
- text/plain
data:
type: string
required:
- type
- media_type
- data
additionalProperties: false
title: Plain Text
- type: object
properties:
type:
type: string
enum:
- url
url:
type: string
required:
- type
- url
additionalProperties: false
title: URL
- type: object
properties:
type:
type: string
enum:
- content
content:
type: array
items:
type: object
properties:
type:
type: string
enum:
- text
text:
type: string
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations:
nullable: true
type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- web_search_result_location
title:
nullable: true
type: string
url:
type: string
cited_text:
type: string
encrypted_index:
type: string
required:
- type
- title
- url
- cited_text
- encrypted_index
additionalProperties: false
title: Web Search Result Location
required:
- type
- text
additionalProperties: false
required:
- type
- content
additionalProperties: false
title: Content
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
citations: {}
context:
type: string
title:
type: string
required:
- type
- source
additionalProperties: false
title: Document
is_error:
type: boolean
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
required:
- type
- tool_use_id
- content
additionalProperties: false
title: Tool Result
- type: object
properties:
type:
type: string
enum:
- server_tool_use
name:
type: string
enum:
- web_search
id:
type: string
input:
type: object
additionalProperties: {}
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
required:
- type
- name
- id
- input
additionalProperties: false
title: Server Tool Use
- type: object
properties:
type:
type: string
enum:
- web_search_tool_result
tool_use_id:
type: string
content:
anyOf:
- type: object
properties:
type:
type: string
enum:
- web_search_tool_result_error
error_code:
type: string
enum:
- invalid_tool_input
- unavailable
- max_uses_exceeded
- query_too_long
required:
- type
- error_code
additionalProperties: false
title: Error
- type: array
items:
type: object
properties:
type:
type: string
enum:
- web_search_result
encrypted_content:
type: string
page_age:
nullable: true
type: string
title:
type: string
url:
type: string
required:
- type
- encrypted_content
- title
- url
additionalProperties: false
title: Search Results
cache_control:
allOf:
- $ref: '#/components/schemas/CacheControl'
required:
- type
- tool_use_id
- content
additionalProperties: false
title: Web Search Tool Result
stop_reason:
nullable: true
type: string
enum:
- end_turn
- max_tokens
- stop_sequence
- tool_use
- pause_turn
- refusal
stop_sequence:
nullable: true
type: string
usage:
type: object
properties:
cache_creation:
nullable: true
type: object
properties:
ephemeral_5m_input_tokens:
type: number
minimum: 0
ephemeral_1h_input_tokens:
type: number
minimum: 0
required:
- ephemeral_5m_input_tokens
- ephemeral_1h_input_tokens
additionalProperties: false
cache_creation_input_tokens:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
cache_read_input_tokens:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
inference_geo:
type: string
input_tokens:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
output_tokens:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
server_tool_use:
type: object
properties:
web_fetch_requests:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
web_search_requests:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- web_fetch_requests
- web_search_requests
additionalProperties: false
service_tier:
type: string
enum:
- standard
- priority
- batch
required:
- cache_creation_input_tokens
- cache_read_input_tokens
- inference_geo
- input_tokens
- output_tokens
- server_tool_use
- service_tier
additionalProperties: false
cost:
type: object
properties:
total:
type: number
byok:
type: boolean
description: >-
Whether the request was served using one of your BYOK
provider keys.
breakdown:
type: object
additionalProperties:
type: object
properties:
input_tokens:
type: number
minimum: 0
input_tokens_details:
type: object
properties:
cached_tokens:
type: number
minimum: 0
description: >-
The number of input tokens read from the
prompt cache.
cached_tokens_created:
nullable: true
type: number
minimum: 0
description: >-
Deprecated: use cache_write_tokens instead.
The number of input tokens written to the
prompt cache. Still populated for now, but
will be removed in a future release.
deprecated: true
cache_write_tokens:
nullable: true
type: number
minimum: 0
description: >-
The number of input tokens written to the
prompt cache.
required:
- cached_tokens
additionalProperties: false
output_tokens:
type: number
minimum: 0
output_tokens_details:
type: object
properties:
reasoning_tokens:
type: number
minimum: 0
required:
- reasoning_tokens
additionalProperties: false
tool_calls:
nullable: true
type: object
properties:
web_search:
nullable: true
type: number
minimum: 0
exa_web_search:
nullable: true
type: number
minimum: 0
additionalProperties: false
total_tokens:
type: number
minimum: 0
required:
- input_tokens
- input_tokens_details
- output_tokens
- output_tokens_details
- total_tokens
additionalProperties: false
required:
- total
- byok
- breakdown
additionalProperties: false
redact:
nullable: true
type: object
properties:
entities_found:
type: number
entity_types:
type: array
items:
type: string
models_used:
type: array
items:
type: string
execution_time_ms:
type: number
redaction_coverage:
type: number
redacted_input:
type: array
items:
$ref: '#/components/schemas/InputItem'
redacted_tools:
type: array
items:
$ref: '#/components/schemas/Tool'
additionalProperties: false
required:
- id
- type
- role
- model
- content
- usage
- cost
additionalProperties: false
default:
description: Default Response
content:
application/json:
schema:
anyOf:
- type: object
properties:
error:
type: object
properties:
code:
type: string
description: One of 25 allowed values.
message:
type: string
upstream_error:
type: string
description: >-
The raw JSON error payload returned by the
upstream provider, present when the error
originated there
required:
- code
- message
additionalProperties: false
required:
- error
additionalProperties: false
components:
schemas:
CacheControlInput:
type: object
properties:
type:
default: ephemeral
description: The cache control type. Currently only ephemeral is supported.
type: string
enum:
- ephemeral
ttl:
default: 5m
description: >-
The time-to-live for the cache entry. One of 5m or 1h. Defaults to
5m.
type: string
enum:
- 5m
- 1h
description: Cache control settings for explicit prompt caching of this content.
UserLocationInput:
type: object
properties:
type:
type: string
description: The type of location approximation. Always approximate.
enum:
- approximate
timezone:
type: string
nullable: true
description: >-
IANA timezone identifier (e.g. America/New_York, Europe/London,
Asia/Tokyo).
country:
type: string
nullable: true
description: ISO 3166-1 alpha-2 country code (e.g. US, GB, DE, JP).
city:
type: string
description: Free text input for the city of the user, e.g. San Francisco.
nullable: true
region:
type: string
description: Free text input for the region of the user, e.g. California.
nullable: true
required:
- type
description: The approximate location of the user, used to refine web search results.
CacheControl:
type: object
properties:
type:
default: ephemeral
description: The cache control type. Currently only ephemeral is supported.
type: string
enum:
- ephemeral
ttl:
default: 5m
description: >-
The time-to-live for the cache entry. One of 5m or 1h. Defaults to
5m.
type: string
enum:
- 5m
- 1h
required:
- type
additionalProperties: false
description: Cache control settings for explicit prompt caching of this content.
InputItem:
anyOf:
- $ref: '#/components/schemas/InputMessage'
- $ref: '#/components/schemas/Item'
description: 'A single input item: a message or an item.'
Tool:
oneOf:
- $ref: '#/components/schemas/FunctionTool'
- $ref: '#/components/schemas/WebSearchTool'
- $ref: '#/components/schemas/CustomTool'
description: A tool the model may call while generating a response.
InputMessage:
type: object
properties:
type:
default: message
description: The type of the input item. Always message.
type: string
enum:
- message
role:
type: string
enum:
- user
- assistant
- system
- developer
description: The role of the message author.
content:
anyOf:
- type: string
minLength: 1
- type: array
items:
$ref: '#/components/schemas/InputItemContent'
description: 'The content of the message: a string, or an array of content parts.'
phase:
type: string
enum:
- commentary
- final_answer
nullable: true
required:
- role
- content
additionalProperties: false
title: Message
description: A message input to the model.
Item:
anyOf:
- $ref: '#/components/schemas/InputMessageItem'
- $ref: '#/components/schemas/OutputMessageItem'
- $ref: '#/components/schemas/FunctionToolCallItem'
- $ref: '#/components/schemas/FunctionToolCallOutputItem'
- $ref: '#/components/schemas/CustomToolCallItem'
- $ref: '#/components/schemas/CustomToolCallOutputItem'
- $ref: '#/components/schemas/ReasoningItem'
- $ref: '#/components/schemas/WebSearchToolCallItem'
- $ref: '#/components/schemas/CompactionItem'
description: A single item in the model's input or output.
FunctionTool:
type: object
properties:
type:
type: string
description: The type of the tool. Always function.
enum:
- function
name: {}
description:
type: string
description: >-
A description of the function. Used by the model to determine
whether or not to call the function.
nullable: true
parameters:
type: object
additionalProperties: {}
description: A JSON schema object describing the parameters of the function.
strict:
type: boolean
description: Whether to enforce strict parameter validation.
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
required:
- type
- name
- parameters
additionalProperties: false
title: Function Tool
description: Defines a function in your own code the model can choose to call.
WebSearchTool:
type: object
properties:
type:
type: string
enum:
- web_search
- web_search_2025_08_26
- web_search_preview
- web_search_preview_2025_03_11
description: The type of the web search tool.
engine:
oneOf:
- type: object
properties:
type:
type: string
enum:
- auto
- native
required:
- type
additionalProperties: false
title: Auto / Native
- type: object
properties:
type:
type: string
enum:
- exa
required:
- type
additionalProperties: false
title: Exa
nullable: true
filters:
type: object
properties:
allowed_domains:
minItems: 1
maxItems: 1200
type: array
items:
type: string
description: >-
Allowed domains for the search. If not provided, all domains are
allowed.
nullable: true
blocked_domains:
minItems: 1
maxItems: 1200
type: array
items:
type: string
description: >-
Blocked domains for the search. If not provided, all domains are
allowed.
nullable: true
additionalProperties: false
description: Filters applied to the web search.
nullable: true
search_context_size:
type: string
enum:
- low
- medium
- high
description: >-
High level guidance for the amount of context window space to use
for the search. One of low, medium, or high.
nullable: true
user_location:
allOf:
- $ref: '#/components/schemas/UserLocation'
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
required:
- type
additionalProperties: false
title: Web Search Tool
description: Search the web for the latest information before generating a response.
CustomTool:
type: object
properties:
type:
type: string
description: The type of the tool. Always custom.
enum:
- custom
name: {}
description:
type: string
description: >-
Optional description of the custom tool, used to provide more
context.
nullable: true
format:
allOf:
- $ref: '#/components/schemas/CustomToolFormat'
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
required:
- type
- name
additionalProperties: false
title: Custom Tool
description: A custom tool that processes input using a specified format.
InputItemContent:
oneOf:
- $ref: '#/components/schemas/InputText'
- $ref: '#/components/schemas/InputImage'
- $ref: '#/components/schemas/InputFile'
description: 'A single piece of content in an input message: text, image, or file.'
InputMessageItem:
type: object
properties:
type:
default: message
description: The type of the item. Always message.
type: string
enum:
- message
role:
type: string
enum:
- user
- system
- developer
description: The role of the message author.
status:
type: string
enum:
- completed
- in_progress
- incomplete
description: >-
The status of the item. One of in_progress, completed, or
incomplete.
nullable: true
content:
type: array
items:
$ref: '#/components/schemas/InputItemContent'
description: The content parts of the message.
required:
- role
- content
additionalProperties: false
title: Input Message
description: A message item in the model's input.
OutputMessageItem:
type: object
properties:
type:
default: message
description: The type of the item. Always message.
type: string
enum:
- message
role:
type: string
description: The role of the message author. Always assistant.
enum:
- assistant
id:
type: string
description: The unique ID of the output message.
nullable: true
status:
type: string
enum:
- completed
- in_progress
- incomplete
description: >-
The status of the item. One of in_progress, completed, or
incomplete.
nullable: true
content:
type: array
items:
$ref: '#/components/schemas/OutputItemContent'
description: The content parts of the message.
cache_control:
$ref: '#/components/schemas/CacheControl'
phase:
type: string
enum:
- commentary
- final_answer
nullable: true
required:
- role
- content
additionalProperties: false
title: Output Message
description: A message item produced by the model.
FunctionToolCallItem:
type: object
properties:
type:
type: string
description: The type of the item. Always function_call.
enum:
- function_call
call_id:
type: string
description: >-
The unique ID of the function tool call, used to correlate it with
its output.
name: {}
arguments:
type: string
description: A JSON string of the arguments to pass to the function.
id:
type: string
description: The unique ID of the function tool call item.
nullable: true
status:
type: string
enum:
- completed
- in_progress
- incomplete
description: >-
The status of the item. One of in_progress, completed, or
incomplete.
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
required:
- type
- call_id
- name
- arguments
additionalProperties: false
title: Function Tool Call
description: A tool call to a function generated by the model.
FunctionToolCallOutputItem:
type: object
properties:
type:
type: string
description: The type of the item. Always function_call_output.
enum:
- function_call_output
call_id:
type: string
minLength: 1
description: The unique ID of the function tool call this output is for.
output:
anyOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/InputItemContent'
description: The output of the function tool call.
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
description: The unique ID of the function tool call output item.
nullable: true
status:
type: string
enum:
- completed
- in_progress
- incomplete
description: >-
The status of the item. One of in_progress, completed, or
incomplete.
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
required:
- type
- call_id
- output
additionalProperties: false
title: Function Tool Call Output
description: The output of a function tool call, provided back to the model.
CustomToolCallItem:
type: object
properties:
type:
type: string
description: The type of the item. Always custom_tool_call.
enum:
- custom_tool_call
call_id:
type: string
description: >-
The unique ID of the custom tool call, used to correlate it with its
output.
name: {}
input:
type: string
description: The input passed to the custom tool.
id:
type: string
description: The unique ID of the custom tool call item.
nullable: true
required:
- type
- call_id
- name
- input
additionalProperties: false
title: Custom Tool Call
description: A call to a custom tool generated by the model.
CustomToolCallOutputItem:
type: object
properties:
type:
type: string
description: The type of the item. Always custom_tool_call_output.
enum:
- custom_tool_call_output
call_id:
type: string
description: The unique ID of the custom tool call this output is for.
output:
type: string
description: The output of the custom tool call.
id:
type: string
description: The unique ID of the custom tool call output item.
nullable: true
status:
type: string
enum:
- completed
- in_progress
- incomplete
description: >-
The status of the item. One of in_progress, completed, or
incomplete.
nullable: true
required:
- type
- call_id
- output
additionalProperties: false
title: Custom Tool Call Output
description: The output of a custom tool call, provided back to the model.
ReasoningItem:
type: object
properties:
type:
type: string
description: The type of the item. Always reasoning.
enum:
- reasoning
id:
type: string
description: The unique ID of the reasoning item.
nullable: true
summary:
type: array
items:
$ref: '#/components/schemas/SummaryText'
description: A summary of the reasoning performed by the model.
content:
type: array
items:
$ref: '#/components/schemas/ReasoningText'
description: The reasoning text produced by the model.
nullable: true
encrypted_content:
type: string
description: >-
The encrypted reasoning content, returned when reasoning is not
stored.
nullable: true
status:
type: string
enum:
- completed
- in_progress
- incomplete
description: >-
The status of the item. One of in_progress, completed, or
incomplete.
nullable: true
required:
- type
- summary
additionalProperties: false
title: Reasoning
description: A reasoning item produced by the model.
WebSearchToolCallItem:
type: object
properties:
type:
type: string
description: The type of the item. Always web_search_call.
enum:
- web_search_call
id:
type: string
description: The unique ID of the web search tool call.
action:
$ref: '#/components/schemas/WebSearchToolCallAction'
status:
anyOf:
- type: string
enum:
- completed
- in_progress
- incomplete
description: >-
The status of the item. One of in_progress, completed, or
incomplete.
- type: string
enum:
- searching
description: The status of the web search tool call.
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
required:
- type
- id
additionalProperties: false
title: Web Search Tool Call
description: A web search call generated by the model.
CompactionItem:
type: object
properties:
type:
type: string
description: The type of the item. Always compaction.
enum:
- compaction
id:
type: string
description: The unique ID of the compaction item.
nullable: true
encrypted_content:
type: string
maxLength: 10485760
description: The encrypted compacted conversation context.
required:
- type
- encrypted_content
additionalProperties: false
title: Compaction
description: A compaction item containing compacted conversation context.
UserLocation:
type: object
properties:
type:
type: string
description: The type of location approximation. Always approximate.
enum:
- approximate
timezone:
type: string
nullable: true
description: >-
IANA timezone identifier (e.g. America/New_York, Europe/London,
Asia/Tokyo).
country:
type: string
nullable: true
description: ISO 3166-1 alpha-2 country code (e.g. US, GB, DE, JP).
city:
type: string
description: Free text input for the city of the user, e.g. San Francisco.
nullable: true
region:
type: string
description: Free text input for the region of the user, e.g. California.
nullable: true
required:
- type
additionalProperties: false
description: The approximate location of the user, used to refine web search results.
CustomToolFormat:
oneOf:
- $ref: '#/components/schemas/TextFormat'
- $ref: '#/components/schemas/GrammarFormat'
description: >-
The input format for a custom tool. Either unconstrained text or a
grammar.
InputText:
type: object
properties:
type:
type: string
description: The type of the input item. Always input_text.
enum:
- input_text
text:
type: string
minLength: 1
description: The text input to the model.
cache_control:
$ref: '#/components/schemas/CacheControl'
prompt_cache_breakpoint:
$ref: '#/components/schemas/PromptCacheBreakpoint'
required:
- type
- text
additionalProperties: false
title: Input Text
description: A text input to the model.
InputImage:
type: object
properties:
type:
type: string
description: The type of the input item. Always input_image.
enum:
- input_image
image_url:
type: string
pattern: >-
^(https?:\/\/.+|data:image\/(png|jpe?g|webp|gif);base64,[A-Za-z0-9+/]+={0,2})$
description: >-
The URL of the image. Either an http(s) URL or a base64-encoded data
URL (data:image/;base64,...).
detail:
default: auto
description: >-
The detail level of the image to send to the model. One of low,
high, auto, or original. Models that don't support 'original'
convert it to 'high'.
type: string
enum:
- low
- high
- auto
- original
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
prompt_cache_breakpoint:
$ref: '#/components/schemas/PromptCacheBreakpoint'
required:
- type
- image_url
additionalProperties: false
title: Input Image
description: An image input to the model.
InputFile:
type: object
properties:
type:
type: string
description: The type of the input item. Always input_file.
enum:
- input_file
file_data:
type: string
pattern: ^(data:application\/pdf;base64,)
description: >-
The content of the file as a base64-encoded PDF data URL
(data:application/pdf;base64,...).
file_url:
type: string
pattern: ^https?:\/\/
description: The URL of the file to send to the model.
filename:
type: string
description: The name of the file, only provided with file_url.
cache_control:
$ref: '#/components/schemas/CacheControl'
prompt_cache_breakpoint:
$ref: '#/components/schemas/PromptCacheBreakpoint'
required:
- type
additionalProperties: false
title: Input File
description: A file input (PDF) to the model.
OutputItemContent:
oneOf:
- $ref: '#/components/schemas/OutputText'
description: A single piece of content in an output message.
SummaryText:
type: object
properties:
type:
type: string
description: The type of the content. Always summary_text.
enum:
- summary_text
text:
type: string
description: The summarized reasoning text.
required:
- type
- text
additionalProperties: false
description: A chunk of summarized reasoning text produced by the model.
ReasoningText:
type: object
properties:
type:
type: string
description: The type of the content. Always reasoning_text.
enum:
- reasoning_text
text:
type: string
description: The reasoning text produced by the model.
required:
- type
- text
additionalProperties: false
description: A chunk of reasoning text produced by the model.
WebSearchToolCallAction:
oneOf:
- $ref: '#/components/schemas/WebSearchToolCallSearchAction'
- $ref: '#/components/schemas/WebSearchToolCallOpenPageAction'
- $ref: '#/components/schemas/WebSearchToolCallFindAction'
description: An action performed by the web search tool.
TextFormat:
type: object
properties:
type:
type: string
description: The type of the format. Always text.
enum:
- text
required:
- type
additionalProperties: false
title: Text Format
description: Default response format. Used to generate text responses.
GrammarFormat:
type: object
properties:
type:
type: string
description: The type of the format. Always grammar.
enum:
- grammar
syntax:
type: string
enum:
- lark
- regex
description: The syntax of the grammar definition. One of lark or regex.
definition:
type: string
description: The grammar definition.
required:
- type
- syntax
- definition
additionalProperties: false
title: Grammar Format
description: A grammar format for a custom tool, defined using Lark or regex syntax.
PromptCacheBreakpoint:
type: object
properties:
mode:
type: string
description: Creates an explicit prompt-cache breakpoint after this block.
enum:
- explicit
required:
- mode
additionalProperties: false
description: OpenAI explicit prompt-cache breakpoint settings.
OutputText:
type: object
properties:
type:
type: string
description: The type of the output content. Always output_text.
enum:
- output_text
text:
type: string
description: The text output from the model.
annotations:
type: array
items:
$ref: '#/components/schemas/Annotation'
description: Annotations on the output text, such as URL citations.
nullable: true
logprobs:
type: array
items:
type: object
properties:
token:
type: string
bytes:
type: array
items:
type: number
logprob:
type: number
top_logprobs:
type: array
items:
type: object
properties:
token:
type: string
bytes:
type: array
items:
type: number
logprob:
type: number
required:
- token
- bytes
- logprob
additionalProperties: false
required:
- token
- bytes
- logprob
- top_logprobs
additionalProperties: false
description: Log probability information for the output tokens.
nullable: true
cache_control:
$ref: '#/components/schemas/CacheControl'
prompt_cache_breakpoint:
$ref: '#/components/schemas/PromptCacheBreakpoint'
required:
- type
- text
additionalProperties: false
title: Output Text
description: A text output from the model.
WebSearchToolCallSearchAction:
type: object
properties:
type:
type: string
description: The type of the action. Always search.
enum:
- search
query:
type: string
description: The search query.
queries:
type: array
items:
type: string
description: The list of search queries run.
nullable: true
sources:
type: array
items:
$ref: '#/components/schemas/Source'
description: The sources consulted during the search.
nullable: true
required:
- type
additionalProperties: false
title: Search Action
description: A search action performed by the web search tool.
WebSearchToolCallOpenPageAction:
type: object
properties:
type:
type: string
description: The type of the action. Always open_page.
enum:
- open_page
url:
type: string
description: The URL of the page opened.
nullable: true
required:
- type
additionalProperties: false
title: Open Page
description: An action where the web search tool opens a page.
WebSearchToolCallFindAction:
type: object
properties:
type:
type: string
description: The type of the action. Always find_in_page.
enum:
- find_in_page
pattern:
type: string
description: The pattern searched for within the page.
url:
type: string
description: The URL of the page searched.
required:
- type
- pattern
- url
additionalProperties: false
title: Find In Page
description: An action where the web search tool searches within a page.
Annotation:
oneOf:
- $ref: '#/components/schemas/UrlCitation'
description: An annotation on the output text.
Source:
oneOf:
- $ref: '#/components/schemas/UrlSource'
- $ref: '#/components/schemas/ApiSource'
description: A source consulted by the web search tool.
UrlCitation:
type: object
properties:
type:
type: string
description: The type of the annotation. Always url_citation.
enum:
- url_citation
start_index:
type: integer
minimum: 0
maximum: 9007199254740991
description: The index of the first character of the citation in the output text.
end_index:
type: integer
minimum: 0
maximum: 9007199254740991
description: The index of the last character of the citation in the output text.
title:
type: string
description: The title of the cited web page.
url:
type: string
description: The URL of the cited web page.
required:
- type
- start_index
- end_index
- title
- url
additionalProperties: false
title: URL Citation
description: A citation to a URL in the output text.
UrlSource:
type: object
properties:
type:
type: string
description: The type of the source. Always url.
enum:
- url
url:
type: string
description: The URL of the source.
required:
- type
- url
additionalProperties: false
title: URL Source
description: A web URL source consulted by the web search tool.
ApiSource:
type: object
properties:
type:
type: string
description: The type of the source. Always api.
enum:
- api
name:
type: string
description: The name of the API source.
required:
- type
- name
additionalProperties: false
title: API Source
description: An API source consulted by the web search tool.
````