{
"openapi": "3.1.0",
"info": {
"title": "xAI's REST API",
"description": "REST API for xAI compatible with other providers.",
"license": { "name": "" },
"version": "1.0.0"
},
"paths": {
"/v1/api-key": {
"get": {
"tags": ["v1"],
"summary": "Get information about an API key, including name, status, permissions and users who created or modified this key.",
"operationId": "handle_get_api_key_info_request",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ApiKey" },
"example": {
"redacted_api_key": "xai-...b14o",
"user_id": "59fbe5f2-040b-46d5-8325-868bb8f23eb2",
"name": "My API Key",
"create_time": "2024-01-01T12:55:18.139305Z",
"modify_time": "2024-08-28T17:20:12.343321Z",
"modified_by": "3d38b4dc-4eb7-4785-ae26-c3fa8997ffc7",
"team_id": "5ea6f6bd-7815-4b8a-9135-28b2d7ba6722",
"acls": ["api-key:model:*", "api-key:endpoint:*"],
"api_key_id": "ae1e1841-4326-4b36-a8a9-8a1a7237db11",
"team_blocked": false,
"api_key_blocked": false,
"api_key_disabled": false
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/chat/completions": {
"post": {
"tags": ["v1"],
"summary": "Create a chat response from text/image chat prompts. This is the endpoint for making requests to chat and image understanding models.",
"operationId": "handle_generic_completion_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ChatRequest" },
"example": {
"messages": [
{
"role": "system",
"content": "You are a helpful assistant that can answer questions and help with tasks."
},
{ "role": "user", "content": "What is 101*3?" }
],
"model": "grok-4-0709"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ChatResponse" },
"example": {
"id": "a3d1008e-4544-40d4-d075-11527e794e4a",
"object": "chat.completion",
"created": 1752854522,
"model": "grok-4-0709",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "101 multiplied by 3 is 303.",
"refusal": null
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 32,
"completion_tokens": 9,
"total_tokens": 135,
"prompt_tokens_details": {
"text_tokens": 32,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 6
},
"completion_tokens_details": {
"reasoning_tokens": 94,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
},
"num_sources_used": 0
},
"system_fingerprint": "fp_3a7881249c"
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/chat/deferred-completion/{request_id}": {
"get": {
"tags": ["v1"],
"summary": "Tries to fetch a result for a previously-started deferred completion. Returns `200 Success` with the response body, if the request has been completed. Returns `202 Accepted` when the request is pending processing.",
"operationId": "handle_get_deferred_completion_request",
"parameters": [
{
"name": "request_id",
"in": "path",
"description": "The deferred request id returned by a previous deferred chat request.",
"required": true,
"schema": { "type": "string" }
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ChatResponse" },
"example": {
"id": "335b92e4-afa5-48e7-b99c-b9a4eabc1c8e",
"object": "chat.completion",
"created": 1743770624,
"model": "grok-4-0709",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "101 multiplied by 3 is 303.",
"refusal": null
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 31,
"completion_tokens": 11,
"total_tokens": 42,
"prompt_tokens_details": {
"text_tokens": 31,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"system_fingerprint": "fp_156d35dcaa"
}
}
}
},
"202": {
"description": "Accepted. The request is processing, but haven't been completed. You can retry at a later time."
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"404": {
"description": "Not found. No deferred completion could be found with the given request_id."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/complete": {
"post": {
"tags": ["v1"],
"summary": "(Legacy - Not supported by reasoning models) Create a text completion response. This endpoint is compatible with the Anthropic API.",
"operationId": "handle_generic_complete_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/CompleteRequest" },
"example": {
"model": "grok-3",
"max_tokens_to_sample": 8,
"temperature": 0.1,
"prompt": "\n\nHuman: Hello, how are you?\n\nAssistant:"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/CompleteResponse" },
"example": {
"type": "completion",
"id": "982044c5-760c-4c8d-8936-f906b5cedc26",
"completion": " Hey there! I'm doing great, thanks",
"stop_reason": "max_tokens",
"model": "grok-3"
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/completions": {
"post": {
"tags": ["v1"],
"summary": "(Legacy - Not supported by reasoning models) Create a text completion response for a given prompt. Replaced by /v1/chat/completions.",
"operationId": "handle_sample_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/SampleRequest" },
"example": { "prompt": "1, 2, 3, 4, ", "model": "grok-3", "max_tokens": 3 }
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/SampleResponse" },
"example": {
"id": "873492b3-6144-4279-ac2e-2c45242c5ce6",
"object": "text_completion",
"created": 1743771779,
"model": "grok-3",
"choices": [{ "index": 0, "text": "5, ", "finish_reason": "length" }],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 3,
"total_tokens": 15,
"prompt_tokens_details": {
"text_tokens": 12,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"system_fingerprint": "fp_156d35dcaa"
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/documents/search": {
"post": {
"tags": ["v1"],
"summary": "Search for content related to the query within the given collections.",
"operationId": "handle_document_search_request_v2",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/SearchRequest" },
"example": {
"query": "What is the revenue in the last quarter?",
"source": { "collection_ids": ["collection_80100614-300c-4609-959b-a138fa90f542"] }
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/SearchResponse" },
"example": {
"matches": [
{
"file_id": "file_ac3c5728-7399-41fc-bd62-0fef0042de9c",
"chunk_id": "0199717c-511b-7a80-bab3-dfe9a27f82ab",
"chunk_content": ", deferred revenue related to such customer payments amounted to $2.10 billion and $1.77 billion, respectively, mainly due to contractual payment terms. Revenue recognized from the deferred revenue balances as of December 31, 2024 and 2023 was $944 million and $873 million for the six months ended June 30, 2025 and 2024, respectively. We have elected the practical expedient to omit disclosure of the amount of the transaction price allocated to remaining performance obligations for contracts with an original expected contract length of one year or less. As of June 30, 2025, total transaction price allocated to performance obligations that were unsatisfied or partially unsatisfied for contracts with an original expected length of more than one year was $10.38 billion. Of this amount, we expect to recognize $5.47 billion in the next 12 months and the rest over the remaining performance obligation period. Changes in government and economic incentives or tariffs may impact the transaction price or our ability to e",
"score": 1.1447691,
"collection_ids": ["collection_80100614-300c-4609-959b-a138fa90f542"]
}
]
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/embedding-models": {
"get": {
"tags": ["v1"],
"summary": "List all embedding models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es).",
"operationId": "handle_embedding_models_list_request",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ListEmbeddingModelsResponse" },
"example": {
"models": [
{
"id": "v1",
"fingerprint": "fp_df37966059",
"created": 1725148800,
"object": "model",
"owned_by": "xai",
"version": "0.1.0",
"input_modalities": ["text"],
"prompt_text_token_price": 100,
"prompt_image_token_price": 0,
"aliases": []
}
]
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/embedding-models/{model_id}": {
"get": {
"tags": ["v1"],
"summary": "Get full information about an embedding model with its model_id.",
"operationId": "handle_embedding_model_get_request",
"parameters": [
{
"name": "model_id",
"in": "path",
"description": "ID of the model to get.",
"required": true,
"schema": { "type": "string" }
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/EmbeddingModel" },
"example": {
"id": "v1",
"created": 1725148800,
"object": "model",
"owned_by": "xai",
"version": "0.1.0",
"input_modalities": ["text"],
"prompt_text_token_price": 10,
"prompt_image_token_price": 0,
"aliases": []
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"404": { "description": "Model not found" }
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/embeddings": {
"post": {
"tags": ["v1"],
"summary": "Create an embedding vector representation corresponding to the input text. This is the endpoint for making requests to embedding models.",
"operationId": "handle_embedding_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/EmbeddingRequest" },
"example": "{\n \"input\": [\"This is an example content to embed...\"],\n \"model\": \"v1\",\n \"encoding_format\": \"float\"\n }"
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/EmbeddingResponse" },
"example": {
"object": "list",
"model": "v1",
"data": [
{
"index": 0,
"embedding": [0.01567895, 0.063257694, 0.045925662],
"object": "embedding"
}
],
"usage": { "prompt_tokens": 1, "total_tokens": 1 }
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/image-generation-models": {
"get": {
"tags": ["v1"],
"summary": "List all image generation models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es).",
"operationId": "handle_image_generation_models_list_request",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ListImageGenerationModelsResponse" },
"example": {
"models": [
{
"id": "grok-2-image",
"fingerprint": "fp_ca78641a52",
"max_prompt_length": 1024,
"created": 1738961600,
"object": "model",
"owned_by": "xai",
"version": "1.0.0",
"prompt_text_token_price": 100000,
"prompt_image_token_price": 100000,
"generated_image_token_price": 100000,
"aliases": []
}
]
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/image-generation-models/{model_id}": {
"get": {
"tags": ["v1"],
"summary": "Get full information about an image generation model with its model_id.",
"operationId": "handle_image_generation_model_get_request",
"parameters": [
{
"name": "model_id",
"in": "path",
"description": "ID of the model to get.",
"required": true,
"schema": { "type": "string" }
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ImageGenerationModel" },
"example": {
"id": "grok-2-image",
"fingerprint": "fp_ca78641a52",
"max_prompt_length": 1024,
"created": 1737961600,
"object": "model",
"owned_by": "xai",
"version": "1.0.0",
"prompt_text_token_price": 100000,
"prompt_image_token_price": 100000,
"generated_image_token_price": 100000,
"aliases": []
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"404": { "description": "Model not found" }
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/images/edits": {
"post": {
"tags": ["v1"],
"summary": "Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models.",
"operationId": "handle_edit_image_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/EditImageRequest" },
"example": {
"prompt": "Add a hat to this cat.",
"image": { "url": "..." },
"model": "grok-2-image"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/GeneratedImageResponse" },
"example": { "data": [{ "url": "..." }] }
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/images/generations": {
"post": {
"tags": ["v1"],
"summary": "Generate an image based on a prompt. This is the endpoint for making generation requests to image generation models.",
"operationId": "handle_generate_image_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/GenerateImageRequest" },
"example": {
"prompt": "A cat in a tree",
"model": "grok-2-image",
"response_format": "url",
"n": 2
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/GeneratedImageResponse" },
"example": {
"data": [
{
"url": "...",
"revised_prompt": "A high-resolution photograph of a cat perched on a branch in a lush, green tree during the daytime. The cat, possibly a tabby with distinctive fur patterns, is the central focus of the image, looking curiously forward with its fur slightly ruffled. The background features a serene park setting with other trees and a clear sky, ensuring no distractions from the main subject. The lighting is soft and natural, enhancing the realistic and calm atmosphere of the scene.<|separator|><|eos|>"
},
{
"url": "...",
"revised_prompt": "1. A high-resolution photograph of a gray tabby cat perched on a branch of a lush, green tree in a suburban backyard during the day. The cat is facing forward, with its fur slightly ruffled by a gentle breeze. The background features other trees and a distant house, all slightly out of focus to emphasize the cat. The lighting is natural, with sunlight filtering through the leaves, creating a serene and realistic setting. The composition focuses primarily on the cat, ensuring it remains the central subject of the image.<|separator|><|eos|>"
}
]
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/language-models": {
"get": {
"tags": ["v1"],
"summary": "List all chat and image understanding models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es).",
"operationId": "handle_language_models_list_request",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ListLanguageModelsResponse" },
"example": {
"models": [
{
"id": "grok-3",
"fingerprint": "fp_898ae9f31c",
"created": 1743724800,
"object": "model",
"owned_by": "xai",
"version": "1.0",
"input_modalities": ["text"],
"output_modalities": ["text"],
"prompt_text_token_price": 30000,
"cached_prompt_text_token_price": 7500,
"prompt_image_token_price": 0,
"completion_text_token_price": 150000,
"search_price": 250000000,
"aliases": ["grok-3-latest", "grok-3-beta"]
},
{
"id": "grok-3-mini",
"fingerprint": "fp_6a09108ff5",
"created": 1743724800,
"object": "model",
"owned_by": "xai",
"version": "1.0",
"input_modalities": ["text"],
"output_modalities": ["text"],
"prompt_text_token_price": 3000,
"cached_prompt_text_token_price": 750,
"prompt_image_token_price": 0,
"completion_text_token_price": 5000,
"search_price": 250000000,
"aliases": ["grok-3-mini-latest", "grok-3-mini-beta"]
},
{
"id": "grok-2-vision-1212",
"fingerprint": "fp_daba7546e5",
"created": 1733961600,
"object": "model",
"owned_by": "xai",
"version": "0.1.0",
"input_modalities": ["text", "image"],
"output_modalities": ["text"],
"prompt_text_token_price": 20000,
"prompt_image_token_price": 20000,
"completion_text_token_price": 100000,
"aliases": []
}
]
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/language-models/{model_id}": {
"get": {
"tags": ["v1"],
"summary": "Get full information about a chat or image understanding model with its model_id.",
"operationId": "handle_language_model_get_request",
"parameters": [
{
"name": "model_id",
"in": "path",
"description": "ID of the model to get.",
"required": true,
"schema": { "type": "string" }
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/LanguageModel" },
"example": {
"id": "grok-4-0709",
"fingerprint": "fp_156d35dcaa",
"created": 1743724800,
"object": "model",
"owned_by": "xai",
"version": "1.0.0",
"input_modalities": ["text"],
"output_modalities": ["text"],
"prompt_text_token_price": 20000,
"cached_prompt_text_token_price": 0,
"prompt_image_token_price": 0,
"completion_text_token_price": 100000,
"aliases": ["grok-4", "grok-4-latest"]
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"404": { "description": "Model not found" }
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/messages": {
"post": {
"tags": ["v1"],
"summary": "Create a messages response. This endpoint is compatible with the Anthropic API.",
"operationId": "handle_generic_messages_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/MessageRequest" },
"example": {
"model": "grok-4-0709",
"max_tokens": 32,
"messages": [{ "role": "user", "content": "Hello, world" }]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/MessageResponse" },
"example": {
"id": "4f224bfb-9d53-4c82-b40a-b7cd80831ec2",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello there! \"Hello, world\" is a classic, isn't it? Whether you're just saying hi or channeling your inner coder, I'm happy to greet you back"
}
],
"model": "grok-4-0709",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 9,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 32
}
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/models": {
"get": {
"tags": ["v1"],
"summary": "List all models available to the authenticating API key with minimalized information, including model names (ID), creation times, etc.",
"operationId": "handle_models_list_request",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ListModelsResponse" },
"example": {
"data": [
{
"id": "grok-4-0709",
"created": 1752019200,
"object": "model",
"owned_by": "xai"
},
{
"id": "grok-code-fast-1",
"created": 1755993600,
"object": "model",
"owned_by": "xai"
},
{ "id": "grok-3", "created": 1743724800, "object": "model", "owned_by": "xai" },
{
"id": "grok-3-mini",
"created": 1743724800,
"object": "model",
"owned_by": "xai"
},
{
"id": "grok-2-image-1212",
"created": 1736726400,
"object": "model",
"owned_by": "xai"
},
{
"id": "grok-2-vision-1212",
"created": 1733961600,
"object": "model",
"owned_by": "xai"
}
],
"object": "list"
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/models/{model_id}": {
"get": {
"tags": ["v1"],
"summary": "Get minimalized information about a model with its model_id.",
"operationId": "handle_model_get_request",
"parameters": [
{
"name": "model_id",
"in": "path",
"description": "ID of the model to get.",
"required": true,
"schema": { "type": "string" }
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Model" },
"example": {
"id": "grok-4-0709",
"created": 1743724800,
"object": "model",
"owned_by": "xai"
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"404": { "description": "Model not found" }
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/responses": {
"post": {
"tags": ["v1"],
"summary": "Generates a response based on text or image prompts. The response ID can be used to retrieve the response later or to continue the conversation without repeating prior context. New responses will be stored for 30 days and then permanently deleted.",
"operationId": "handle_generic_model_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ModelRequest" },
"example": {
"input": [
{
"role": "system",
"content": "You are a helpful assistant that can answer questions and help with tasks."
},
{ "role": "user", "content": "What is 101*3?" }
],
"model": "grok-4-0709"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ModelResponse" },
"example": {
"created_at": 1754475266,
"id": "ad5663da-63e6-86c6-e0be-ff15effa8357",
"max_output_tokens": null,
"model": "grok-4-0709",
"object": "response",
"output": [
{
"content": [
{
"type": "output_text",
"text": "101 multiplied by 3 is 303.",
"logprobs": null,
"annotations": []
}
],
"id": "msg_ad5663da-63e6-86c6-e0be-ff15effa8357",
"role": "assistant",
"type": "message",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": null,
"temperature": null,
"text": { "format": { "type": "text" } },
"tool_choice": "auto",
"tools": [],
"top_p": null,
"usage": {
"prompt_tokens": 32,
"completion_tokens": 9,
"total_tokens": 151,
"prompt_tokens_details": {
"text_tokens": 32,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 8
},
"completion_tokens_details": {
"reasoning_tokens": 110,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
},
"num_sources_used": 0
},
"user": null,
"incomplete_details": null,
"status": "completed",
"store": true
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"422": {
"description": "Unprocessable Entity. There are missing fields in the request body."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/responses/{response_id}": {
"get": {
"tags": ["v1"],
"summary": "Retrieve a previously generated response.",
"operationId": "handle_get_stored_completion_request",
"parameters": [
{
"name": "response_id",
"in": "path",
"description": "The response id returned by a previous create response request.",
"required": true,
"schema": { "type": "string" }
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ModelResponse" },
"example": {
"created_at": 1754475266,
"id": "ad5663da-63e6-86c6-e0be-ff15effa8357",
"max_output_tokens": null,
"model": "grok-4-0709",
"object": "response",
"output": [
{
"content": [
{
"type": "output_text",
"text": "101 multiplied by 3 is 303.",
"logprobs": null,
"annotations": []
}
],
"id": "msg_ad5663da-63e6-86c6-e0be-ff15effa8357",
"role": "assistant",
"type": "message",
"status": "completed"
},
{
"id": "",
"summary": [
{
"text": "First, the user asked: \"What is 101*3?\"\n\nThis is a simple multiplication: 101 multiplied by 3.\n\nCalculating: 100 * 3 = 300, and 1 * 3 = 3, so 300 + 3 = 303.\n\nI should respond helpfully and directly, as per my system prompt: \"You are a helpful assistant that can answer questions and help with tasks.\"\n\nKeep the response concise and accurate. No need for extra fluff unless it adds value.\n\nFinal answer: 303.",
"type": "summary_text"
}
],
"type": "reasoning",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": null,
"temperature": null,
"text": { "format": { "type": "text" } },
"tool_choice": "auto",
"tools": [],
"top_p": null,
"usage": {
"prompt_tokens": 32,
"completion_tokens": 9,
"total_tokens": 151,
"prompt_tokens_details": {
"text_tokens": 32,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 8
},
"completion_tokens_details": {
"reasoning_tokens": 110,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
},
"num_sources_used": 0
},
"user": null,
"incomplete_details": null,
"status": "completed",
"store": true
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"404": {
"description": "Not found. No responses could be found with the given response_id."
}
},
"security": [{ "bearerAuth": [] }]
},
"delete": {
"tags": ["v1"],
"summary": "Delete a previously generated response.",
"operationId": "handle_delete_stored_completion_request",
"parameters": [
{
"name": "response_id",
"in": "path",
"description": "The response id returned by a previous create response request.",
"required": true,
"schema": { "type": "string" }
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/DeleteStoredCompletionResponse" },
"example": {
"id": "ad5663da-63e6-86c6-e0be-ff15effa8357",
"object": "response",
"deleted": true
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
},
"404": {
"description": "Not found. No responses could be found with the given response_id."
}
},
"security": [{ "bearerAuth": [] }]
}
},
"/v1/tokenize-text": {
"post": {
"tags": ["v1"],
"summary": "Tokenize text with the specified model",
"operationId": "handle_tokenize_text_request",
"requestBody": {
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/TokenizeRequest" },
"example": { "text": "Hello world!", "model": "grok-4-0709" }
}
},
"required": true
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/TokenizeResponse" },
"example": {
"token_ids": [
{
"token_id": 13902,
"string_token": "Hello",
"token_bytes": [72, 101, 108, 108, 111]
},
{
"token_id": 1749,
"string_token": " world",
"token_bytes": [32, 119, 111, 114, 108, 100]
},
{ "token_id": 161, "string_token": "!", "token_bytes": [33] }
]
}
}
}
},
"400": {
"description": "Bad request. The request is invalid or an invalid API key is provided."
}
},
"security": [{ "bearerAuth": [] }]
}
}
},
"components": {
"schemas": {
"Annotation": {
"type": "object",
"required": ["type", "url"],
"properties": {
"end_index": {
"type": ["integer", "null"],
"format": "int32",
"description": "The end index of the annotation."
},
"start_index": {
"type": ["integer", "null"],
"format": "int32",
"description": "The summary of the annotation."
},
"title": { "type": ["string", "null"], "description": "The title of the annotation." },
"type": {
"type": "string",
"description": "The type of the annotation. Only supported type currently is `url_citation`."
},
"url": { "type": "string", "description": "The URL of the web resource." }
}
},
"ApiKey": {
"type": "object",
"required": [
"redacted_api_key",
"user_id",
"name",
"create_time",
"modify_time",
"modified_by",
"team_id",
"acls",
"api_key_id",
"team_blocked",
"api_key_blocked",
"api_key_disabled"
],
"properties": {
"acls": {
"type": "array",
"items": { "type": "string" },
"description": "A list of ACLs authorized with the API key, e.g. `\"api-key:endpoint:*\"`, `\"api-key:model:*\"`."
},
"api_key_blocked": {
"type": "boolean",
"description": "Indicates whether the API key is blocked."
},
"api_key_disabled": {
"type": "boolean",
"description": "Indicates whether the API key is disabled."
},
"api_key_id": { "type": "string", "description": "ID of the API key." },
"create_time": {
"type": "string",
"description": "Creation time of the API key in Unix timestamp."
},
"modified_by": {
"type": "string",
"description": "User ID of the user who last modified the API key."
},
"modify_time": {
"type": "string",
"description": "Last modification time of the API key in Unix timestamp."
},
"name": { "type": "string", "description": "The name of the API key specified by user." },
"redacted_api_key": { "type": "string", "description": "The redacted API key." },
"team_blocked": {
"type": "boolean",
"description": "Indicates whether the team that owns the API key."
},
"team_id": {
"type": "string",
"description": "The team ID of the team that owns the API key."
},
"user_id": { "type": "string", "description": "User ID the API key belongs to." }
}
},
"ChatRequest": {
"type": "object",
"description": "The chat request body for `/v1/chat/completions` endpoint.",
"properties": {
"bootstrap_host": {
"type": ["string", "null"],
"description": "(Internal) Bootstrap host address for disaggregated prefill/decode. Used for PD disaggregation."
},
"bootstrap_room": {
"type": ["integer", "null"],
"format": "int64",
"description": "(Internal) Bootstrap room ID for disaggregated prefill/decode. Used for PD disaggregation.",
"minimum": 0
},
"deferred": {
"type": ["boolean", "null"],
"description": "If set to `true`, the request returns a `request_id`. You can then get the deferred response by GET `/v1/chat/deferred-completion/{request_id}`.",
"default": false
},
"frequency_penalty": {
"type": ["number", "null"],
"format": "float",
"description": "(Not supported by reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.",
"default": 0,
"maximum": 2,
"minimum": -2
},
"logit_bias": {
"type": ["object", "null"],
"description": "(Unsupported) A JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.",
"additionalProperties": { "type": "number", "format": "float" },
"propertyNames": { "type": "integer", "format": "int32" }
},
"logprobs": {
"type": ["boolean", "null"],
"description": "Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.",
"default": false
},
"max_completion_tokens": {
"type": ["integer", "null"],
"format": "int32",
"description": "An upper bound for the number of tokens that can be generated for a completion, only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls). Defaults to None, meaning the model will generate as many tokens as needed up until the model's maximum context length.",
"example": 8192
},
"max_tokens": {
"type": ["integer", "null"],
"format": "int32",
"description": "\\[DEPRECATED\\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of `max_completion_tokens`.",
"example": 8192
},
"messages": {
"type": "array",
"items": { "$ref": "#/components/schemas/Message" },
"description": "A list of messages that make up the the chat conversation. Different models support different message types, such as image and text."
},
"model": {
"type": "string",
"description": "Model name for the model to use. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>.",
"example": "grok-4-0709"
},
"n": {
"type": ["integer", "null"],
"format": "int32",
"description": "How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs.",
"default": 1,
"example": 1,
"minimum": 1
},
"parallel_tool_calls": {
"type": ["boolean", "null"],
"description": "If set to false, the model can perform maximum one tool call.",
"default": true,
"example": false
},
"presence_penalty": {
"type": ["number", "null"],
"format": "float",
"description": "(Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.",
"default": 0,
"maximum": 2,
"minimum": -2
},
"reasoning_effort": {
"type": ["string", "null"],
"description": "Constrains how hard a reasoning model thinks before responding. Not supported by `grok-4` and will result in error if used with `grok-4`. Possible values are `low` (uses fewer reasoning tokens) and `high` (uses more reasoning tokens)."
},
"response_format": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ResponseFormat",
"description": "An object specifying the format that the model must output. Specify `{ \"type\": \"json_object\" }` for JSON output, or `{ \"type\": \"json_schema\", \"json_schema\": {...} }` for structured outputs. If `{ \\\"type\\\": \\\"text\\\" }`, the model will return a text response."
}
]
},
"search_parameters": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/SearchParameters",
"description": "Set the parameters to be used for searched data. If not set, no data will be acquired by the model."
}
]
},
"seed": {
"type": ["integer", "null"],
"format": "int32",
"description": "If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend."
},
"stop": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "(Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens."
},
"stream": {
"type": ["boolean", "null"],
"description": "If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.",
"default": false,
"example": true
},
"stream_options": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/StreamOptions",
"description": "Options for streaming response. Only set this when you set `stream: true`."
}
]
},
"temperature": {
"type": ["number", "null"],
"format": "float",
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.",
"default": 1,
"example": 0.2,
"maximum": 2,
"minimum": 0
},
"tool_choice": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ToolChoice",
"description": "Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present."
}
]
},
"tools": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/Tool" },
"description": "A list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.",
"maxItems": 128
},
"top_logprobs": {
"type": ["integer", "null"],
"format": "int32",
"description": "An integer between 0 and 8 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.",
"maximum": 8,
"minimum": 0
},
"top_p": {
"type": ["number", "null"],
"format": "float",
"description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both.",
"default": 1,
"maximum": 1,
"exclusiveMinimum": 0
},
"user": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
},
"web_search_options": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/WebSearchOptions",
"description": "Options to control the web search. This is only included for compatibility reason. Prefer\nthe usage of `realtime_data_parameters` instead."
}
]
}
}
},
"ChatResponse": {
"type": "object",
"description": "The chat response body for `/v1/chat/completions` endpoint.",
"required": ["id", "object", "created", "model", "choices"],
"properties": {
"choices": {
"type": "array",
"items": { "$ref": "#/components/schemas/Choice" },
"description": "A list of response choices from the model. The length corresponds to the `n` in request body (default to 1)."
},
"citations": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of all the external pages used by the model to answer."
},
"created": {
"type": "integer",
"format": "int64",
"description": "The chat completion creation time in Unix timestamp."
},
"debug_output": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/DebugOutput",
"description": "Debug output. Only available to trusted testers."
}
]
},
"id": { "type": "string", "description": "A unique ID for the chat response." },
"model": {
"type": "string",
"description": "Model ID used to create chat completion.",
"example": "grok-4-0709"
},
"object": {
"type": "string",
"description": "The object type, which is always `\"chat.completion\"`."
},
"system_fingerprint": {
"type": ["string", "null"],
"description": "System fingerprint, used to indicate xAI system configuration changes."
},
"usage": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/components/schemas/Usage", "description": "Token usage information." }
]
}
}
},
"ChatResponseChunk": {
"type": "object",
"required": ["id", "object", "created", "model", "choices"],
"properties": {
"choices": {
"type": "array",
"items": { "$ref": "#/components/schemas/ChoiceChunk" },
"description": "A list of response choices from the model. The length corresponds to the `n` in request body (default to 1)."
},
"citations": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of all the external pages used by the model to answer. Only populated for the last chunk."
},
"created": {
"type": "integer",
"format": "int64",
"description": "The chat completion creation time in Unix timestamp."
},
"debug_output": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/DebugOutput",
"description": "Debug output. Only available to trusted testers."
}
]
},
"id": { "type": "string", "description": "A unique ID for the chat response chunk." },
"model": {
"type": "string",
"description": "The model ID used to create chat completion.",
"example": "grok-4-0709"
},
"object": {
"type": "string",
"description": "The object type, which is always `\"chat.completion.chunk\"`."
},
"system_fingerprint": {
"type": ["string", "null"],
"description": "System fingerprint, used to indicate xAI system configuration changes."
},
"usage": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/components/schemas/Usage", "description": "Token usage information." }
]
}
}
},
"Choice": {
"type": "object",
"required": ["index", "message"],
"properties": {
"finish_reason": {
"type": ["string", "null"],
"description": "Finish reason. `\"stop\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last."
},
"index": {
"type": "integer",
"format": "int32",
"description": "Index of the choice within the response choices, starting from 0."
},
"logprobs": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/LogProbs",
"description": "The log probabilities of each output token returned in the content of message."
}
]
},
"message": {
"$ref": "#/components/schemas/ChoiceMessage",
"description": "The generated chat completion message."
}
}
},
"ChoiceChunk": {
"type": "object",
"required": ["index", "delta"],
"properties": {
"delta": {
"$ref": "#/components/schemas/Delta",
"description": "Additional difference (delta) of the result."
},
"finish_reason": {
"type": ["string", "null"],
"description": "Finish reason. `\"stop\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last."
},
"index": { "type": "integer", "format": "int32", "description": "Index of the choice." },
"logprobs": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/LogProbs",
"description": "The log probabilities of each output token returned in the content of message."
}
]
}
}
},
"ChoiceMessage": {
"type": "object",
"required": ["role"],
"properties": {
"content": { "type": ["string", "null"], "description": "The content of the message." },
"reasoning_content": {
"type": ["string", "null"],
"description": "The reasoning trace generated by the model."
},
"refusal": {
"type": ["string", "null"],
"description": "The reason given by model if the model is unable to generate a response. null if model is able to generate."
},
"role": {
"type": "string",
"description": "The role that the message belongs to, the response from model is always `\"assistant\"`."
},
"tool_calls": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/ToolCall" },
"description": "A list of tool calls asked by model for user to perform."
}
}
},
"CodeInterpreterCall": {
"type": "object",
"description": "The output of a code interpreter tool call.",
"required": ["type", "outputs"],
"properties": {
"code": {
"type": "string",
"description": "The code of the code interpreter tool call."
},
"id": {
"type": "string",
"description": "The unique ID of the code interpreter tool call."
},
"outputs": {
"type": "array",
"items": { "$ref": "#/components/schemas/CodeInterpreterOutput" },
"description": "The outputs of the code interpreter tool call."
},
"status": {
"type": "string",
"description": "The status of the code interpreter tool call."
},
"type": {
"type": "string",
"description": "The type of the code interpreter tool call. Always `code_interpreter_call`."
}
}
},
"CodeInterpreterOutput": {
"oneOf": [
{
"type": "object",
"description": "The output of the code interpreter tool call.",
"required": ["logs", "type"],
"properties": {
"logs": {
"type": "string",
"description": "The output of the code interpreter tool call."
},
"type": { "type": "string", "enum": ["logs"] }
}
},
{
"type": "object",
"description": "The error of the code interpreter tool call.",
"required": ["url", "type"],
"properties": {
"type": { "type": "string", "enum": ["image"] },
"url": {
"type": "string",
"description": "The error of the code interpreter tool call."
}
}
}
]
},
"CompleteRequest": {
"type": "object",
"description": "(Legacy) Anthropic compatible complete request on `/v1/complete` endpoint.",
"properties": {
"max_tokens_to_sample": {
"type": "integer",
"format": "int32",
"description": "The maximum number of tokens to generate before stopping."
},
"metadata": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/MessageMetadata",
"description": "An object describing metadata about the request."
}
]
},
"model": { "type": "string", "description": "Model to use for completion." },
"prompt": {
"type": "string",
"description": "Prompt for the model to perform completion on."
},
"stop_sequences": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "(Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens."
},
"stream": {
"type": ["boolean", "null"],
"description": "(Unsupported) If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message."
},
"temperature": {
"type": ["number", "null"],
"format": "float",
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.",
"default": 1,
"example": 0.2,
"maximum": 2,
"minimum": 0
},
"top_k": {
"type": ["integer", "null"],
"format": "int32",
"description": "(Unsupported) When generating next tokens, randomly selecting the next token from the k most likely options."
},
"top_p": {
"type": ["number", "null"],
"format": "float",
"description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both.",
"default": 1,
"maximum": 1,
"exclusiveMinimum": 0
}
}
},
"CompleteResponse": {
"type": "object",
"description": "(Legacy) Anthropic compatible complete response on `/v1/complete` endpoint.",
"required": ["type", "id", "completion", "model"],
"properties": {
"completion": {
"type": "string",
"description": "The completion content up to and excluding stop sequences."
},
"id": { "type": "string", "description": "ID of the completion response." },
"model": { "type": "string", "description": "The model that handled the request." },
"stop_reason": {
"type": ["string", "null"],
"description": "The reason to stop completion. `\"stop_sequence\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last."
},
"type": {
"type": "string",
"description": "Completion response object type. This is always `\"completion\"`."
}
}
},
"CompletionUsageDetail": {
"type": "object",
"description": "Details of completion usage.",
"required": [
"reasoning_tokens",
"audio_tokens",
"accepted_prediction_tokens",
"rejected_prediction_tokens"
],
"properties": {
"accepted_prediction_tokens": {
"type": "integer",
"format": "int32",
"description": "The number of tokens in the prediction that appeared in the completion."
},
"audio_tokens": {
"type": "integer",
"format": "int32",
"description": "Audio input tokens generated by the model."
},
"reasoning_tokens": {
"type": "integer",
"format": "int32",
"description": "Tokens generated by the model for reasoning."
},
"rejected_prediction_tokens": {
"type": "integer",
"format": "int32",
"description": "The number of tokens in the prediction that did not appear in the completion."
}
}
},
"Content": {
"oneOf": [
{ "type": "string", "description": "Text prompt." },
{
"type": "array",
"items": { "$ref": "#/components/schemas/ContentPart" },
"description": "An array of content parts of different types, such as image, text or text file."
}
],
"description": "Content of each chat message."
},
"ContentPart": {
"type": "object",
"required": ["type"],
"properties": {
"detail": {
"type": ["string", "null"],
"description": "Specifies the detail level of the image."
},
"file": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/FileRef",
"description": "File reference for file attachments (OpenAI-compatible nesting)."
}
]
},
"image_url": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ImageUrl",
"description": "A public URL of image prompt, only available for vision models."
}
]
},
"text": { "type": ["string", "null"], "description": "Text prompt." },
"text_file": {
"type": ["string", "null"],
"description": "File path to a text file to be used as prompt."
},
"type": { "type": "string", "description": "The type of the content part." }
}
},
"CustomToolCall": {
"type": "object",
"description": "The output of a custom tool call.",
"required": ["call_id", "name", "type", "id"],
"properties": {
"call_id": {
"type": "string",
"description": "The unique ID of the function tool call generated by the model."
},
"id": { "type": "string", "description": "The status of the custom tool call." },
"input": { "type": "string", "description": "The unique ID of the custom tool call," },
"name": {
"type": "string",
"description": "An identifier used to map this custom tool call to a tool call output."
},
"status": {
"type": "string",
"description": "Status of the item. One of `completed`, `in_progress` or `incomplete`."
},
"type": {
"type": "string",
"description": "The input for the custom tool call generated by the model."
}
}
},
"DebugOutput": {
"type": "object",
"required": [
"attempts",
"request",
"prompt",
"engine_request",
"responses",
"chunks",
"cache_read_count",
"cache_read_input_bytes",
"cache_write_count",
"cache_write_input_bytes",
"lb_address",
"sampler_tag",
"sampler_checkpoint_mount"
],
"properties": {
"attempts": {
"type": "integer",
"format": "int32",
"description": "Number of attempts made to the model."
},
"cache_read_count": {
"type": "integer",
"format": "int32",
"description": "Number of cache reads",
"minimum": 0
},
"cache_read_input_bytes": {
"type": "integer",
"format": "int64",
"description": "Size of cache read",
"minimum": 0
},
"cache_write_count": {
"type": "integer",
"format": "int32",
"description": "Number of cache writes",
"minimum": 0
},
"cache_write_input_bytes": {
"type": "integer",
"format": "int64",
"description": "Size of cache write",
"minimum": 0
},
"chunks": {
"type": "array",
"items": { "type": "string" },
"description": "The individual chunks returned from the pipeline of samplers."
},
"engine_request": {
"type": "string",
"description": "JSON-serialized request sent to the inference engine."
},
"lb_address": { "type": "string", "description": "The load balancer address" },
"prompt": {
"type": "string",
"description": "The prompt sent to the model in text form."
},
"request": { "type": "string", "description": "The request received from the user." },
"responses": {
"type": "array",
"items": { "type": "string" },
"description": "The response(s) received from the model."
},
"sampler_checkpoint_mount": {
"type": "string",
"description": "The underlying checkpoint mount path for the sampler that served this request."
},
"sampler_tag": {
"type": "string",
"description": "The tag of the actual engines sitting behind the GTP address. Eg \"grok-4-code-eapi-lap4-unified-sblbm-0\""
}
}
},
"DeleteStoredCompletionResponse": {
"type": "object",
"description": "Response to delete a stored completion.",
"required": ["id", "object", "deleted"],
"properties": {
"deleted": {
"type": "boolean",
"description": "Whether the response was successfully deleted."
},
"id": { "type": "string", "description": "The response_id to be deleted." },
"object": {
"type": "string",
"description": "The deleted object type, which is always `response`."
}
}
},
"Delta": {
"type": "object",
"properties": {
"content": { "type": ["string", "null"] },
"images": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "Images generated by the model."
},
"reasoning_content": { "type": ["string", "null"] },
"role": { "type": ["string", "null"] },
"tool_calls": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/ToolCall" }
}
}
},
"DocumentsSource": {
"type": "object",
"description": "DocumentsSource defines the source of documents to search over.",
"required": ["collection_ids"],
"properties": {
"collection_ids": {
"type": "array",
"items": { "type": "string" },
"description": "The collection IDs to search in."
}
}
},
"EditImageRequest": {
"type": "object",
"description": "Request for editing image",
"required": ["prompt", "image"],
"properties": {
"image": {
"$ref": "#/components/schemas/ImageUrl",
"description": "Input image to perform edit on."
},
"mask": { "oneOf": [{ "type": "null" }, { "$ref": "#/components/schemas/ImageUrl" }] },
"model": {
"type": ["string", "null"],
"description": "Model to be used.",
"example": "grok-2-image"
},
"n": {
"type": ["integer", "null"],
"format": "int32",
"description": "Number of image edits to be generated."
},
"prompt": { "type": "string", "description": "Prompt for image editing." },
"quality": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ImageQuality",
"description": "Quality of the output image. Can be `low`, `medium`, or `high`."
}
]
},
"response_format": {
"type": ["string", "null"],
"description": "Response format to return the image in. Can be `url` or `b64_json`. If `b64_json` is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file.",
"default": "url"
},
"size": {
"type": ["string", "null"],
"description": "(Not supported) Size of the image."
},
"style": {
"type": ["string", "null"],
"description": "(Not supported) Style of the image."
},
"user": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
}
}
},
"Embedding": {
"type": "object",
"required": ["index", "embedding", "object"],
"properties": {
"embedding": {
"$ref": "#/components/schemas/EmbeddingContent",
"description": "Embedding content."
},
"index": {
"type": "integer",
"format": "int32",
"description": "Index of the embedding object in the data list."
},
"object": {
"type": "string",
"description": "The object type, which is always `\"embedding\"`."
}
}
},
"EmbeddingContent": {
"oneOf": [
{ "type": "string", "description": "Embedding in base64 string." },
{
"type": "array",
"items": { "type": "number", "format": "float" },
"description": "Embedding as an array of floats."
}
]
},
"EmbeddingInput": {
"oneOf": [
{
"type": "object",
"description": "A strings to be embedded. For best performance, prepend \"query: \" in front of query content and prepend \"passage: \" in front of passage/text",
"required": ["String"],
"properties": {
"String": {
"type": "string",
"description": "A strings to be embedded. For best performance, prepend \"query: \" in front of query content and prepend \"passage: \" in front of passage/text"
}
}
},
{
"type": "object",
"description": "An array of strings to be embedded",
"required": ["StringArray"],
"properties": {
"StringArray": {
"type": "array",
"items": { "type": "string" },
"description": "An array of strings to be embedded"
}
}
},
{
"type": "object",
"description": "A token in integer to be embedded",
"required": ["Ints"],
"properties": {
"Ints": {
"type": "array",
"items": { "type": "integer", "format": "int32" },
"description": "A token in integer to be embedded"
}
}
},
{
"type": "object",
"description": "An array of tokens in integers to be embedded",
"required": ["IntsArray"],
"properties": {
"IntsArray": {
"type": "array",
"items": { "type": "array", "items": { "type": "integer", "format": "int32" } },
"description": "An array of tokens in integers to be embedded"
}
}
}
]
},
"EmbeddingModel": {
"type": "object",
"description": "Details of an embedding model",
"required": [
"id",
"fingerprint",
"created",
"object",
"owned_by",
"version",
"input_modalities",
"output_modalities",
"prompt_text_token_price",
"prompt_image_token_price",
"aliases"
],
"properties": {
"aliases": {
"type": "array",
"items": { "type": "string" },
"description": "Alias ID(s) of the model that user can use in a request's model field."
},
"created": {
"type": "integer",
"format": "int64",
"description": "Model creation time in Unix timestamp."
},
"fingerprint": {
"type": "string",
"description": "Fingerprint of the xAI system configuration hosting the model."
},
"id": {
"type": "string",
"description": "Model ID. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>."
},
"input_modalities": {
"type": "array",
"items": { "type": "string" },
"description": "The input modalities supported by the model."
},
"object": { "type": "string", "description": "Object type, should be model." },
"output_modalities": {
"type": "array",
"items": { "type": "string" },
"description": "The output modalities supported by the model."
},
"owned_by": { "type": "string", "description": "Owner of the model." },
"prompt_image_token_price": {
"type": "integer",
"format": "int64",
"description": "Price of the prompt image token in USD cents per million token."
},
"prompt_text_token_price": {
"type": "integer",
"format": "int64",
"description": "Price of the prompt text token in USD cents per million token."
},
"version": { "type": "string", "description": "Version of the model." }
}
},
"EmbeddingRequest": {
"type": "object",
"properties": {
"dimensions": {
"type": ["integer", "null"],
"format": "int32",
"description": "The number of dimensions the resulting output embeddings should have."
},
"encoding_format": {
"type": ["string", "null"],
"description": "The format to return the embeddings in. Can be either `float` or `base64`."
},
"input": {
"$ref": "#/components/schemas/EmbeddingInput",
"description": "Input text to embed, encoded as a string or list of tokens. To embed multiple inputs in a single request, pass a list of strings or list of token lists. The total tokens in the input must not exceed the context window for the model and cannot be an empty string. If the input is a list, the maximum length of the list is 128."
},
"model": { "type": "string", "description": "ID of the model to use.", "example": "v1" },
"preview": {
"type": ["boolean", "null"],
"description": "Flag to use the new format of the API."
},
"user": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
}
}
},
"EmbeddingResponse": {
"type": "object",
"required": ["object", "model", "data"],
"properties": {
"data": {
"type": "array",
"items": { "$ref": "#/components/schemas/Embedding" },
"description": "A list of embedding objects."
},
"model": { "type": "string", "description": "Model ID used to create embedding." },
"object": {
"type": "string",
"description": "The object type of `data` field, which is always `\"list\"`."
},
"usage": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/EmbeddingUsage",
"description": "Token usage information."
}
]
}
}
},
"EmbeddingUsage": {
"type": "object",
"required": ["prompt_tokens", "total_tokens"],
"properties": {
"prompt_tokens": {
"type": "integer",
"format": "int32",
"description": "Prompt token used."
},
"total_tokens": {
"type": "integer",
"format": "int32",
"description": "Total token used."
}
}
},
"FileRef": {
"type": "object",
"required": ["file_id"],
"properties": {
"file_id": { "type": "string", "description": "The file ID from the Files API." }
}
},
"FileSearchCall": {
"type": "object",
"description": "The output of a web search tool call.",
"required": ["type", "queries", "results"],
"properties": {
"id": { "type": "string", "description": "The unique ID of the file search tool call." },
"queries": {
"type": "array",
"items": { "type": "string" },
"description": "The queries used to search for files."
},
"results": {
"type": "array",
"items": { "$ref": "#/components/schemas/FileSearchResult" },
"description": "The results of the file search tool call."
},
"status": { "type": "string", "description": "The status of the file search tool call." },
"type": {
"type": "string",
"description": "The type of the file search tool call. Always `file_search_call`."
}
}
},
"FileSearchResult": {
"type": "object",
"required": ["file_id", "filename", "score", "text"],
"properties": {
"file_id": { "type": "string", "description": "The file ID of the file search result." },
"filename": {
"type": "string",
"description": "The filename of the file search result."
},
"score": {
"type": "number",
"format": "double",
"description": "The score of the file search result."
},
"text": { "type": "string", "description": "The text of the file search result." }
}
},
"Function": {
"type": "object",
"required": ["name", "arguments"],
"properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }
},
"FunctionCall": {
"type": "object",
"required": ["name", "arguments"],
"properties": {
"arguments": { "type": "string", "description": "Arguments available to the function." },
"name": { "type": "string", "description": "Name of the function." }
}
},
"FunctionChoice": {
"type": "object",
"description": "Function name.",
"required": ["name"],
"properties": { "name": { "type": "string" } }
},
"FunctionDefinition": {
"type": "object",
"description": "Definition of the tool call made available to the model.",
"required": ["name", "parameters"],
"properties": {
"description": {
"type": ["string", "null"],
"description": "A description of the function to indicate to the model when to call it."
},
"name": {
"type": "string",
"description": "The name of the function. If the model calls the function, this name is used in the\nresponse."
},
"parameters": {
"description": "A JSON schema describing the function parameters. The model _should_ follow the schema,\nhowever, this is not enforced at the moment."
},
"strict": {
"type": ["boolean", "null"],
"description": "Not supported. Only maintained for compatibility reasons."
}
}
},
"FunctionToolCall": {
"type": "object",
"description": "A tool call to run a function.",
"required": ["arguments", "call_id", "name", "type"],
"properties": {
"arguments": {
"type": "string",
"description": "The arguments to pass to the function, as a JSON string."
},
"call_id": {
"type": "string",
"description": "The unique ID of the function tool call generated by the model."
},
"id": { "type": "string", "description": "The unique ID of the function tool call." },
"name": { "type": "string", "description": "The name of the function." },
"status": {
"type": "string",
"description": "Status of the item. One of `completed`, `in_progress` or `incomplete`."
},
"type": {
"type": "string",
"description": "The type of the function tool call, which can be `\"function_call\"` for client-side tool calls,\nand `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"` for server-side tool calls."
}
}
},
"FunctionToolCallOutput": {
"type": "object",
"description": "The output of a function tool call.",
"required": ["call_id", "output", "type"],
"properties": {
"call_id": {
"type": "string",
"description": "The unique ID of the function tool call generated by the model."
},
"output": {
"type": "string",
"description": "The output of the function tool call, as a JSON string."
},
"type": {
"type": "string",
"description": "The type of the function tool call, which is always `function_call_output`."
}
}
},
"GenerateImageRequest": {
"type": "object",
"properties": {
"model": {
"type": ["string", "null"],
"description": "Model to be used.",
"example": "grok-2-image"
},
"n": {
"type": ["integer", "null"],
"format": "int32",
"description": "Number of images to be generated",
"default": 1,
"maximum": 10,
"minimum": 1
},
"prompt": { "type": "string", "description": "Prompt for image generation." },
"quality": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ImageQuality",
"description": "Quality of the output image. Can be `low`, `medium`, or `high`."
}
]
},
"response_format": {
"type": ["string", "null"],
"description": "Response format to return the image in. Can be url or b64_json. If b64_json is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file.",
"default": "url"
},
"size": {
"type": ["string", "null"],
"description": "(Not supported) Size of the image."
},
"style": {
"type": ["string", "null"],
"description": "(Not supported) Style of the image."
},
"user": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
}
}
},
"GeneratedImage": {
"type": "object",
"description": "Generated images",
"required": ["revised_prompt"],
"properties": {
"b64_json": {
"type": ["string", "null"],
"description": "A base64-encoded string representation of the generated image in `jpeg` encoding, if `b64_json` is specified as `response_format` in the request."
},
"revised_prompt": {
"type": "string",
"description": "The revised prompt generated by a chat model from the original prompt. This prompt is used in the final image generation."
},
"url": {
"type": ["string", "null"],
"description": "A url to the generated image, if `response_format` is not specified or with `url` in the request."
}
}
},
"GeneratedImageResponse": {
"type": "object",
"description": "Image generation response for `/v1/image/generations` endpoint",
"required": ["data"],
"properties": {
"data": {
"type": "array",
"items": { "$ref": "#/components/schemas/GeneratedImage" },
"description": "A list of generated image objects."
}
}
},
"HybridReranker": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/RerankerModel",
"description": "Use a reranker model to perform the reranking."
},
{
"type": "object",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["reranker_model"] } }
}
],
"description": "Use a reranker model to perform the reranking."
},
{
"allOf": [
{
"$ref": "#/components/schemas/ReciprocalRankFusion",
"description": "Use RRF to perform the reranking."
},
{
"type": "object",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["rrf"] } }
}
],
"description": "Use RRF to perform the reranking."
}
],
"description": "Reranker configuration for hybrid retrieval."
},
"HybridRetrieval": {
"type": "object",
"description": "Document search using a combination of keyword and semantic search.",
"properties": {
"reranker": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/HybridReranker",
"description": "Which reranker to use to limit results to the desired value."
}
]
},
"search_multiplier": {
"type": ["integer", "null"],
"format": "int32",
"description": "Additional multiplier to requested search limit.\nValid range is [1, 100]. Defaults to 1 when unset."
}
}
},
"ImageGenerationModel": {
"type": "object",
"description": "Details of an image generation model",
"required": [
"id",
"fingerprint",
"max_prompt_length",
"created",
"object",
"owned_by",
"version",
"input_modalities",
"output_modalities",
"image_price",
"aliases"
],
"properties": {
"aliases": {
"type": "array",
"items": { "type": "string" },
"description": "Alias ID(s) of the model that user can use in a request's model field."
},
"created": {
"type": "integer",
"format": "int64",
"description": "Model creation time in Unix timestamp."
},
"fingerprint": {
"type": "string",
"description": "Fingerprint of the xAI system configuration hosting the model."
},
"id": { "type": "string", "description": "Model ID." },
"image_price": {
"type": "integer",
"format": "int64",
"description": "Price of a single image in USD cents."
},
"input_modalities": {
"type": "array",
"items": { "type": "string" },
"description": "The input modalities supported by the model."
},
"max_prompt_length": { "type": "integer", "format": "int64" },
"object": {
"type": "string",
"description": "The object type, which is always `\"model\"`."
},
"output_modalities": {
"type": "array",
"items": { "type": "string" },
"description": "The output modalities supported by the model."
},
"owned_by": { "type": "string", "description": "Owner of the model." },
"version": { "type": "string", "description": "Version of the model." }
}
},
"ImageQuality": {
"type": "string",
"description": "Request to generate image for `/v1/image/generations` endpoint\nQuality level for image generation",
"enum": ["low", "medium", "high"]
},
"ImageUrl": {
"type": "object",
"description": "Image URL object of Image prompt",
"required": ["url"],
"properties": {
"detail": {
"type": ["string", "null"],
"description": "Specifies the detail level of the image."
},
"url": { "type": "string", "description": "URL of the image." }
}
},
"IncompleteDetails": {
"type": "object",
"description": "Details about why a response is incomplete.",
"required": ["reason"],
"properties": {
"reason": {
"type": "string",
"description": "The reason why the response is incomplete."
}
}
},
"InputTokensDetails": {
"type": "object",
"required": ["cached_tokens"],
"properties": {
"cached_tokens": {
"type": "integer",
"format": "int32",
"description": "Token cached by xAI from previous requests and reused for this request."
}
}
},
"KeywordRetrieval": {
"type": "object",
"description": "Document search using keyword matching (sparse embeddings).",
"properties": {
"reranker": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/RerankerModel",
"description": "Optional, but always used when doing search across multiple collections."
}
]
}
}
},
"LanguageModel": {
"type": "object",
"description": "Details of a language model",
"required": [
"id",
"fingerprint",
"created",
"object",
"owned_by",
"version",
"input_modalities",
"output_modalities",
"prompt_text_token_price",
"cached_prompt_text_token_price",
"prompt_image_token_price",
"completion_text_token_price",
"search_price",
"aliases"
],
"properties": {
"aliases": {
"type": "array",
"items": { "type": "string" },
"description": "Alias ID(s) of the model that user can use in a request's model field."
},
"cached_prompt_text_token_price": {
"type": "integer",
"format": "int64",
"description": "Price of a prompt text token (in USD cents per 100 million tokens) that was cached previously."
},
"completion_text_token_price": {
"type": "integer",
"format": "int64",
"description": "Price of the completion text token in USD cents per 100 million token."
},
"created": {
"type": "integer",
"format": "int64",
"description": "Creation time of the model in Unix timestamp."
},
"fingerprint": {
"type": "string",
"description": "Fingerprint of the xAI system configuration hosting the model."
},
"id": {
"type": "string",
"description": "Model ID. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>."
},
"input_modalities": {
"type": "array",
"items": { "type": "string" },
"description": "The input modalities supported by the model, e.g. `\"text\"`, `\"image\"`."
},
"object": {
"type": "string",
"description": "The object type, which is always `\"model\"`."
},
"output_modalities": {
"type": "array",
"items": { "type": "string" },
"description": "The output modalities supported by the model, e.g. `\"text\"`, `\"image\"`."
},
"owned_by": { "type": "string", "description": "Owner of the model." },
"prompt_image_token_price": {
"type": "integer",
"format": "int64",
"description": "Price of the prompt image token in USD cents per 100 million token."
},
"prompt_text_token_price": {
"type": "integer",
"format": "int64",
"description": "Price of the prompt text token in USD cents per 100 million token."
},
"search_price": {
"type": "integer",
"format": "int64",
"description": "Price of the search in USD cents per 100 million searches."
},
"version": { "type": "string", "description": "Version of the model." }
}
},
"ListEmbeddingModelsResponse": {
"type": "object",
"required": ["models"],
"properties": {
"models": {
"type": "array",
"items": { "$ref": "#/components/schemas/EmbeddingModel" },
"description": "Array of available embedding models."
}
}
},
"ListImageGenerationModelsResponse": {
"type": "object",
"required": ["models"],
"properties": {
"models": {
"type": "array",
"items": { "$ref": "#/components/schemas/ImageGenerationModel" },
"description": "Array of available image generation models."
}
}
},
"ListLanguageModelsResponse": {
"type": "object",
"required": ["models"],
"properties": {
"models": {
"type": "array",
"items": { "$ref": "#/components/schemas/LanguageModel" },
"description": "Array of available language models."
}
}
},
"ListModelsResponse": {
"type": "object",
"required": ["data", "object"],
"properties": {
"data": {
"type": "array",
"items": { "$ref": "#/components/schemas/Model" },
"description": "A list of models with with minimalized information."
},
"object": {
"type": "string",
"description": "The object type of `data` field, which is always `\"list\"`."
}
}
},
"LogProbs": {
"type": "object",
"properties": {
"content": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/TokenLogProb" },
"description": "An array the log probabilities of each output token returned."
}
}
},
"McpCall": {
"type": "object",
"description": "The output of a MCP tool call.",
"required": ["type", "name", "server_label", "arguments", "output"],
"properties": {
"arguments": {
"type": "string",
"description": "A JSON string of the arguments passed to the tool."
},
"error": { "type": "string", "description": "The error message of the MCP tool call." },
"id": { "type": "string", "description": "The unique ID of the MCP tool call." },
"name": { "type": "string", "description": "The name of the tool that was run." },
"output": { "type": "string", "description": "The output of the MCP tool call." },
"server_label": {
"type": "string",
"description": "The label of the MCP server running the tool."
},
"status": { "type": "string", "description": "The status of the MCP tool call." },
"type": {
"type": "string",
"description": "The type of the MCP tool call. Always `mcp_call`."
}
}
},
"Message": {
"oneOf": [
{
"type": "object",
"description": "System message, usually instructions for the model to respond in a certain way.",
"required": ["content", "role"],
"properties": {
"content": {
"$ref": "#/components/schemas/Content",
"description": "System prompt content."
},
"name": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
},
"role": { "type": "string", "enum": ["system"] }
}
},
{
"type": "object",
"description": "User message, typically request from user for the model to answer.",
"required": ["content", "role"],
"properties": {
"content": {
"$ref": "#/components/schemas/Content",
"description": "System prompt content."
},
"name": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
},
"role": { "type": "string", "enum": ["user"] }
}
},
{
"type": "object",
"description": "Assistant role message, previous chat messages from the model.",
"required": ["role"],
"properties": {
"content": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/Content",
"description": "Assistant prompt content."
}
]
},
"name": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
},
"reasoning_content": {
"type": ["string", "null"],
"description": "Assistant reasoning content."
},
"role": { "type": "string", "enum": ["assistant"] },
"tool_calls": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/ToolCall" },
"description": "An array of tool calls available to the model on your machine."
}
}
},
{
"type": "object",
"description": "Tool call role message, used to return function call result to the model.",
"required": ["content", "role"],
"properties": {
"content": {
"$ref": "#/components/schemas/Content",
"description": "Content of the tool call result."
},
"role": { "type": "string", "enum": ["tool"] },
"tool_call_id": {
"type": ["string", "null"],
"description": "The ID of the tool call received from assistant message response."
}
}
},
{
"type": "object",
"description": "Function call role message. Deprecated in favor of `{\"role\": \"tool\"}`.",
"required": ["content", "role"],
"properties": {
"content": {
"$ref": "#/components/schemas/Content",
"description": "Content of the tool call result."
},
"name": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
},
"role": { "type": "string", "enum": ["function"] }
}
}
],
"description": "Chat message objects."
},
"MessageBody": {
"type": "object",
"description": "Anthropic compatible message body",
"required": ["role", "content"],
"properties": {
"content": {
"$ref": "#/components/schemas/MessageContent",
"description": "The content message."
},
"role": {
"type": "string",
"description": "The role that the message belongs to, `\"system\"` for system prompt, `\"user\"` for user prompt, and `\"assistant\"` for response from the model."
}
}
},
"MessageContent": {
"oneOf": [
{ "type": "string", "description": "Text prompt." },
{
"type": "array",
"items": { "$ref": "#/components/schemas/MessageContentPart" },
"description": "An array of message content parts."
}
]
},
"MessageContentPart": {
"oneOf": [
{
"type": "object",
"description": "Text prompt message content part.",
"required": ["text", "type"],
"properties": {
"cache_control": { "description": "(Unsupported) Cache control." },
"text": { "type": "string", "description": "Text prompt." },
"type": { "type": "string", "enum": ["text"] }
}
},
{
"type": "object",
"description": "Image prompt message content part.",
"required": ["source", "type"],
"properties": {
"cache_control": { "description": "(Unsupported) Cache control." },
"source": {
"$ref": "#/components/schemas/MessageImageContent",
"description": "Image source."
},
"type": { "type": "string", "enum": ["image"] }
}
},
{
"type": "object",
"description": "Tool call message content part. Received from model.",
"required": ["id", "name", "input", "type"],
"properties": {
"cache_control": { "description": "(Unsupported) Cache control." },
"id": { "type": "string", "description": "ID of the tool call." },
"input": { "description": "Input for tool call." },
"name": { "type": "string", "description": "Name of the tool call." },
"type": { "type": "string", "enum": ["tool_use"] }
}
},
{
"type": "object",
"description": "Tool call result.",
"required": ["tool_use_id", "content", "type"],
"properties": {
"cache_control": { "description": "(Unsupported) Cache control." },
"content": { "type": "string", "description": "Result content of the tool call." },
"is_error": {
"type": ["boolean", "null"],
"description": "Whether the tool call returns an error."
},
"tool_use_id": {
"type": "string",
"description": "ID of the tool call given by the model."
},
"type": { "type": "string", "enum": ["tool_result"] }
}
},
{
"type": "object",
"description": "(Redacted) Thinking of the model.",
"required": ["data", "type"],
"properties": {
"data": {
"type": "string",
"description": "Encrypted data of the redacted thinking."
},
"type": { "type": "string", "enum": ["redacted_thinking"] }
}
},
{
"type": "object",
"description": "Thinking of the model.",
"required": ["thinking", "type"],
"properties": {
"thinking": { "type": "string", "description": "Thinking." },
"type": { "type": "string", "enum": ["thinking"] }
}
}
]
},
"MessageImageContent": {
"oneOf": [
{
"type": "object",
"required": ["media_type", "data", "type"],
"properties": {
"data": { "type": "string", "description": "Base64 encoded image string." },
"media_type": {
"type": "string",
"description": "Media type of the image source. Available options: `image/jpeg`, `image/png`, `image/webp`."
},
"type": { "type": "string", "enum": ["base64"] }
}
},
{
"type": "object",
"required": ["url", "type"],
"properties": {
"type": { "type": "string", "enum": ["url"] },
"url": { "type": "string", "description": "URL of the image." }
}
}
]
},
"MessageMetadata": {
"type": "object",
"properties": {
"user_id": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
}
}
},
"MessageRequest": {
"type": "object",
"description": "Request message for `/v1/messages`",
"properties": {
"max_tokens": {
"type": "integer",
"format": "int32",
"description": "The maximum number of tokens to generate before stopping. The model may stop before the max_tokens when it reaches the stop sequence."
},
"messages": {
"type": "array",
"items": { "$ref": "#/components/schemas/MessageBody" },
"description": "Input messages."
},
"metadata": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/MessageMetadata",
"description": "An object describing metadata about the request."
}
]
},
"model": {
"type": "string",
"description": "Model name for the model to use.",
"example": "grok-4-0709"
},
"stop_sequences": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "(Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens."
},
"stream": {
"type": ["boolean", "null"],
"description": "If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message."
},
"system": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/SystemMessageContent",
"description": "System prompt message for the model, defining how the model should behave to user messages."
}
]
},
"temperature": {
"type": ["number", "null"],
"format": "float",
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. It may not work well with reasoning models.",
"default": 1,
"maximum": 2,
"minimum": 0
},
"tool_choice": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/MessageToolChoice",
"description": "Controls which (if any) tool is called by the model. `\"none\"` means the model will not call any tool and instead generates a message. `\"auto\"` means the model can pick between generating a message or calling one or more tools. `\"any\"` means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"tool\", \"function\": {\"name\": \"get_weather\"}}` forces the model to call that tool. `\"none\"` is the default when no tools are provided. `\"auto\"` is the default if tools are provided."
}
]
},
"tools": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/MessageTools" },
"description": "A list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported."
},
"top_k": {
"type": ["integer", "null"],
"format": "int32",
"description": "(Unsupported) When generating next tokens, randomly selecting the next token from the k most likely options."
},
"top_p": {
"type": ["number", "null"],
"format": "float",
"description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both.",
"default": 1,
"maximum": 1,
"exclusiveMinimum": 0
}
}
},
"MessageResponse": {
"type": "object",
"description": "Response message for `/v1/messages`",
"required": ["id", "type", "role", "content", "model", "usage"],
"properties": {
"content": {
"type": "array",
"items": { "$ref": "#/components/schemas/MessageResponseContent" },
"description": "Response message content."
},
"id": { "type": "string", "description": "Unique object identifier." },
"model": {
"type": "string",
"description": "Model name that handled the request.",
"example": "grok-4-0709"
},
"role": {
"type": "string",
"description": "Role of the generated message. Always `\"assistant\"`"
},
"stop_reason": {
"type": ["string", "null"],
"description": "Reason to stop. `\"stop_sequence\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"max_tokens\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last. `\"tool_use\"` means the model has called a tool and is waiting for the tool response."
},
"stop_sequence": {
"type": ["string", "null"],
"description": "Custom stop sequence used to stop the generation."
},
"type": {
"type": "string",
"description": "Object type. This is always `\"message\"` for message types.",
"example": "message"
},
"usage": {
"$ref": "#/components/schemas/MessageUsage",
"description": "Token usage information."
}
}
},
"MessageResponseContent": {
"oneOf": [
{
"type": "object",
"description": "Text response from the model.",
"required": ["text", "type"],
"properties": {
"text": { "type": "string" },
"type": { "type": "string", "enum": ["text"] }
}
},
{
"type": "object",
"description": "Thinking response for the model",
"required": ["signature", "thinking", "type"],
"properties": {
"signature": { "type": "string", "description": "Signature of the content" },
"thinking": { "type": "string", "description": "Thinking content" },
"type": { "type": "string", "enum": ["thinking"] }
}
},
{
"type": "object",
"description": "Redacted thinking response for the model",
"required": ["data", "type"],
"properties": {
"data": { "type": "string", "description": "Signature of the content" },
"type": { "type": "string", "enum": ["redacted_thinking"] }
}
},
{
"type": "object",
"description": "Request by the model to invoke a tool call.",
"required": ["id", "name", "input", "type"],
"properties": {
"id": { "type": "string", "description": "Tool call ID." },
"input": { "description": "Input to the tool call follwing the `input_schema`." },
"name": { "type": "string", "description": "Name of the tool call to be used." },
"type": { "type": "string", "enum": ["tool_use"] }
}
}
]
},
"MessageToolChoice": {
"oneOf": [
{
"type": "object",
"description": "Allows the model to automatically decide whether to call the tool",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["auto"] } }
},
{
"type": "object",
"description": "Forces the model to use at least one tool, without specifying the tool.",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["any"] } }
},
{
"type": "object",
"description": "Forces the model to use the named tool",
"required": ["name", "type"],
"properties": {
"name": { "type": "string", "description": "Name of the tool to use." },
"type": { "type": "string", "enum": ["tool"] }
}
}
],
"description": "Tool choice option."
},
"MessageToolInputSchema": {
"type": "object",
"required": ["type", "properties"],
"properties": {
"properties": { "description": "JSON-object of the tool input schema." },
"required": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "Required properties of the tool input schema, if any."
},
"type": {
"type": "string",
"description": "Type of the schema. This is always `\"object\"`."
}
}
},
"MessageTools": {
"type": "object",
"required": ["name", "description", "input_schema"],
"properties": {
"cache_control": { "description": "(Unsupported) Cache control." },
"description": { "type": "string", "description": "Description of the tool." },
"input_schema": {
"$ref": "#/components/schemas/MessageToolInputSchema",
"description": "Input schema allowed by the tool."
},
"name": { "type": "string", "description": "Name of the tool." }
}
},
"MessageUsage": {
"type": "object",
"required": [
"input_tokens",
"cache_creation_input_tokens",
"cache_read_input_tokens",
"output_tokens"
],
"properties": {
"cache_creation_input_tokens": {
"type": "integer",
"format": "int32",
"description": "(Unsupported) Number of tokens written to the cache when creating a new entry."
},
"cache_read_input_tokens": {
"type": "integer",
"format": "int32",
"description": "Number of tokens retrieved from the cache for this request."
},
"input_tokens": {
"type": "integer",
"format": "int32",
"description": "Number of input tokens used"
},
"output_tokens": {
"type": "integer",
"format": "int32",
"description": "Number of output tokens used"
}
}
},
"Model": {
"type": "object",
"description": "Same as `LanguageModel` but fully compliant with the OpenAI API.",
"required": ["id", "created", "object", "owned_by"],
"properties": {
"created": {
"type": "integer",
"format": "int64",
"description": "Model creation time in Unix timestamp."
},
"id": {
"type": "string",
"description": "Model ID. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>."
},
"object": {
"type": "string",
"description": "The object type, which is always `\"model\"`."
},
"owned_by": { "type": "string", "description": "Owner of the model." }
}
},
"ModelInput": {
"oneOf": [
{ "type": "string", "description": "Text input." },
{
"type": "array",
"items": { "$ref": "#/components/schemas/ModelInputPart" },
"description": "A list of input items to the model. Can be of different types."
}
],
"description": "Content of the input passed to a `/v1/response` request."
},
"ModelInputContent": {
"oneOf": [
{ "type": "string", "description": "Text input." },
{
"type": "array",
"items": { "$ref": "#/components/schemas/ModelInputContentItem" },
"description": "A list of input items to the model. Can include text and images."
}
]
},
"ModelInputContentItem": {
"oneOf": [
{
"type": "object",
"description": "Text input.",
"required": ["text", "type"],
"properties": {
"text": { "type": "string", "description": "Text input." },
"type": { "type": "string", "enum": ["input_text"] }
}
},
{
"type": "object",
"description": "Image input. Note: Storing and fetching images is not fully supported at the moment.",
"required": ["image_url", "type"],
"properties": {
"detail": {
"type": ["string", "null"],
"description": "Specifies the detail level of the image. One of `high`, `low` or `auto`. Defaults to `auto`."
},
"file_id": {
"type": ["string", "null"],
"description": "Only included for compatibility."
},
"image_url": {
"type": "string",
"description": "A public URL of image prompt, only available for vision models."
},
"type": { "type": "string", "enum": ["input_image"] }
}
},
{
"type": "object",
"description": "File input.",
"required": ["file_id", "type"],
"properties": {
"file_id": { "type": "string", "description": "The file ID from the Files API." },
"type": { "type": "string", "enum": ["input_file"] }
}
}
]
},
"ModelInputItem": {
"oneOf": [
{ "allOf": [{ "$ref": "#/components/schemas/ModelOutput" }] },
{ "allOf": [{ "$ref": "#/components/schemas/FunctionToolCallOutput" }] }
]
},
"ModelInputPart": {
"oneOf": [
{
"type": "object",
"description": "Message input to the model.",
"required": ["content", "role"],
"properties": {
"content": {
"$ref": "#/components/schemas/ModelInputContent",
"description": "Text, image or audio input."
},
"name": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Only supported for `user` messages."
},
"role": {
"type": "string",
"description": "The role of the message. Possible values are `user`, `assistant`, `system` and `developer`."
},
"type": {
"type": ["string", "null"],
"description": "The type of the message, which is always `message`."
}
}
},
{
"allOf": [{ "$ref": "#/components/schemas/ModelInputItem" }],
"description": "Previous responses of the model and tool call outputs."
}
]
},
"ModelOutput": {
"oneOf": [
{ "allOf": [{ "$ref": "#/components/schemas/OutputMessage" }] },
{ "allOf": [{ "$ref": "#/components/schemas/FunctionToolCall" }] },
{ "allOf": [{ "$ref": "#/components/schemas/Reasoning" }] },
{ "allOf": [{ "$ref": "#/components/schemas/WebSearchCall" }] },
{ "allOf": [{ "$ref": "#/components/schemas/FileSearchCall" }] },
{ "allOf": [{ "$ref": "#/components/schemas/CodeInterpreterCall" }] },
{ "allOf": [{ "$ref": "#/components/schemas/McpCall" }] },
{ "allOf": [{ "$ref": "#/components/schemas/CustomToolCall" }] }
]
},
"ModelRequest": {
"type": "object",
"description": "The request body for `/v1/responses` endpoint.",
"required": ["input"],
"properties": {
"background": {
"type": ["boolean", "null"],
"description": "(Unsupported) Whether to process the response asynchronously in the background.",
"default": false
},
"include": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "What additional output data to include in the response. Currently the only supported value is `reasoning.encrypted_content` which returns an encrypted version of the reasoning tokens."
},
"input": {
"$ref": "#/components/schemas/ModelInput",
"description": "The input passed to the model. Can be text, image or file."
},
"instructions": {
"type": ["string", "null"],
"description": "An alternate way to specify the system prompt. Note that this cannot be used alongside `previous_response_id`, where the system prompt of the previous message will be used."
},
"logprobs": {
"type": ["boolean", "null"],
"description": "Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.",
"default": false
},
"max_output_tokens": {
"type": ["integer", "null"],
"format": "int32",
"description": "Max number of tokens that can be generated in a response. This includes both output and reasoning tokens."
},
"metadata": {
"description": "Not supported. Only maintained for compatibility reasons."
},
"model": {
"type": "string",
"description": "Model name for the model to use. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>.",
"example": "grok-4-0709"
},
"parallel_tool_calls": {
"type": ["boolean", "null"],
"description": "Whether to allow the model to run parallel tool calls.",
"default": true
},
"previous_response_id": {
"type": ["string", "null"],
"description": "The ID of the previous response from the model."
},
"reasoning": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ReasoningConfiguration",
"description": "Reasoning configuration. Only for reasoning models."
}
]
},
"search_parameters": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/SearchParameters",
"description": "Set the parameters to be used for searched data. Takes precedence over `web_search_preview` tool if specified in the tools."
}
]
},
"service_tier": {
"type": ["string", "null"],
"description": "Not supported. Only maintained for compatibility reasons."
},
"store": {
"type": ["boolean", "null"],
"description": "Whether to store the input message(s) and model response for later retrieval.",
"default": true
},
"stream": {
"type": ["boolean", "null"],
"description": "If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.",
"default": false,
"example": true
},
"temperature": {
"type": ["number", "null"],
"format": "float",
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.",
"default": 1,
"example": 0.2,
"maximum": 2,
"minimum": 0
},
"text": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ModelResponseConfiguration",
"description": "Settings for customizing a text response from the model."
}
]
},
"tool_choice": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ModelToolChoice",
"description": "Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present."
}
]
},
"tools": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/ModelTool" },
"description": "A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported.`web_search_preview` tool, if specified, will be overridden by `search_parameters`.",
"maxItems": 128
},
"top_logprobs": {
"type": ["integer", "null"],
"format": "int32",
"description": "An integer between 0 and 8 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.",
"maximum": 8,
"minimum": 0
},
"top_p": {
"type": ["number", "null"],
"format": "float",
"description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both.",
"default": 1,
"maximum": 1,
"exclusiveMinimum": 0
},
"truncation": {
"type": ["string", "null"],
"description": "Not supported. Only maintained for compatibility reasons."
},
"user": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
}
}
},
"ModelResponse": {
"type": "object",
"description": "The response body for `/v1/responses` endpoint.",
"required": [
"created_at",
"id",
"model",
"object",
"output",
"parallel_tool_calls",
"text",
"tool_choice",
"tools",
"status",
"store",
"metadata"
],
"properties": {
"background": {
"type": ["boolean", "null"],
"description": "Whether to process the response asynchronously in the background.",
"default": false
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "The Unix timestamp (in seconds) for the response creation time."
},
"debug_output": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/DebugOutput",
"description": "Debug output. Only available to trusted testers."
}
]
},
"id": { "type": "string", "description": "Unique ID of the response." },
"incomplete_details": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/IncompleteDetails",
"description": "Details about why the response is incomplete."
}
]
},
"max_output_tokens": {
"type": ["integer", "null"],
"format": "int32",
"description": "Max number of tokens that can be generated in a response. This includes both output and reasoning tokens."
},
"metadata": { "description": "Only included for compatibility." },
"model": { "type": "string", "description": "Model name used to generate the response." },
"object": {
"type": "string",
"description": "The object type of this resource. Always set to `response`."
},
"output": {
"type": "array",
"items": { "$ref": "#/components/schemas/ModelOutput" },
"description": "The response generated by the model."
},
"parallel_tool_calls": {
"type": "boolean",
"description": "Whether to allow the model to run parallel tool calls."
},
"previous_response_id": {
"type": ["string", "null"],
"description": "The ID of the previous response from the model."
},
"reasoning": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ReasoningConfiguration",
"description": "Reasoning configuration. Only for reasoning models."
}
]
},
"status": {
"type": "string",
"description": "Status of the response. One of `completed`, `in_progress` or `incomplete`."
},
"store": {
"type": "boolean",
"description": "Whether to store the input message(s) and model response for later retrieval.",
"default": true
},
"temperature": {
"type": ["number", "null"],
"format": "float",
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.",
"default": 1,
"maximum": 2,
"minimum": 0
},
"text": {
"$ref": "#/components/schemas/ModelResponseConfiguration",
"description": "Settings for customizing a text response from the model."
},
"tool_choice": {
"$ref": "#/components/schemas/ModelToolChoice",
"description": "Controls which (if any) tool is called by the model. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present."
},
"tools": {
"type": "array",
"items": { "$ref": "#/components/schemas/ModelTool" },
"description": "A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported.",
"maxItems": 128
},
"top_p": {
"type": ["number", "null"],
"format": "float",
"description": "An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both.",
"default": 1,
"maximum": 1,
"exclusiveMinimum": 0
},
"usage": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ModelUsage",
"description": "Token usage information."
}
]
},
"user": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
}
}
},
"ModelResponseConfiguration": {
"type": "object",
"properties": {
"format": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ModelResponseFormat",
"description": "An object specifying the format that the model must output. Specify `{ \"type\": \"json_object\" }` for JSON output, or `{ \"type\": \"json_schema\", \"json_schema\": {...} }` for structured outputs. If `{ \\\"type\\\": \\\"text\\\" }`, the model will return a text response."
}
]
}
}
},
"ModelResponseFormat": {
"oneOf": [
{
"type": "object",
"description": "Specify text response format, always `\"text\"`.",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["text"] } }
},
{
"type": "object",
"description": "Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `\"json_schema\"` instead of this.",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["json_object"] } }
},
{
"type": "object",
"description": "Specify json_schema response format with a given schema. Type is always `\"json_schema\"`.",
"required": ["schema", "type"],
"properties": {
"description": {
"type": ["string", "null"],
"description": "Only included for compatibility."
},
"name": {
"type": ["string", "null"],
"description": "Only included for compatibility."
},
"schema": {
"description": "A json schema representing the desired response schema."
},
"strict": {
"type": ["boolean", "null"],
"description": "Only included for compatibility."
},
"type": { "type": "string", "enum": ["json_schema"] }
}
}
],
"description": "Response format parameter for structured outputs."
},
"ModelTool": {
"oneOf": [
{
"allOf": [
{ "$ref": "#/components/schemas/FunctionDefinition" },
{
"type": "object",
"description": "A function that the model can call.",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["function"] } }
}
],
"description": "A function that the model can call."
},
{
"allOf": [
{ "$ref": "#/components/schemas/WebSearchOptions" },
{
"type": "object",
"properties": {
"allowed_domains": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of website domains to allow in the search results. This parameter act as a whitelist\nwhere only those websites can be selected. A maximum of 5 websites can be selected.\n\nNote: This parameter cannot be set with `excluded_domains`.",
"example": ["wikipedia.com"],
"maxItems": 5
},
"enable_image_understanding": {
"type": ["boolean", "null"],
"description": "Enable image understanding during web search."
},
"excluded_domains": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of website domains to exclude from the search results without protocol specification or\nsubdomains. A maximum of 5 websites can be excluded.\n\nNote: This parameter cannot be set with `allowed_domains`",
"example": ["wikipedia.com"],
"maxItems": 5
},
"external_web_access": {
"type": ["boolean", "null"],
"description": "Control whether the web search tool fetches live content or uses only cached content.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set."
},
"filters": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/WebSearchFilters",
"description": "Filters to apply to the search results. Compatible with OpenAI's API."
}
]
},
"search_context_size": {
"type": ["string", "null"],
"description": "High level guidance for the amount of context window space to use for the\nsearch. Available values are `low`, `medium`, or `high`.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set."
},
"user_location": {
"description": "The user location to use for the search.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set."
}
}
},
{
"type": "object",
"description": "Search the web.",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["web_search"] } }
}
],
"description": "Search the web."
},
{
"type": "object",
"description": "Search X.",
"required": ["type"],
"properties": {
"allowed_x_handles": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of X Handles of the users from whom to consider the posts.\n\nNote: This parameter cannot be set with `excluded_x_handles`.",
"example": ["elonmusk"],
"maxItems": 10
},
"enable_image_understanding": {
"type": ["boolean", "null"],
"description": "Enable image understanding during X search."
},
"enable_video_understanding": {
"type": ["boolean", "null"],
"description": "Enable video understanding during X search."
},
"excluded_x_handles": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of X Handles of the users from whom to exclude the posts.\n\nNote: This parameter cannot be set with `allowed_x_handles`.",
"example": ["elonmusk"],
"maxItems": 10
},
"from_date": {
"type": ["string", "null"],
"format": "date",
"description": "Date from which to consider the results in ISO-8601 YYYY-MM-DD. See\n<https://en.wikipedia.org/wiki/ISO_8601>.",
"example": "2024-06-24"
},
"to_date": {
"type": ["string", "null"],
"format": "date",
"description": "Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See\n<https://en.wikipedia.org/wiki/ISO_8601>.",
"example": "2024-12-24"
},
"type": { "type": "string", "enum": ["x_search"] }
}
},
{
"type": "object",
"description": "Search the knowledge bases.",
"required": ["vector_store_ids", "type"],
"properties": {
"filters": {
"description": "A filter to apply.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set."
},
"max_num_results": {
"type": ["integer", "null"],
"format": "int32",
"example": 10,
"minimum": 1
},
"ranking_options": {
"description": "Ranking options for search.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set."
},
"type": { "type": "string", "enum": ["file_search"] },
"vector_store_ids": {
"type": "array",
"items": { "type": "string" },
"description": "List of vector store IDs to search within.",
"example": ["collection_id_1", "collection_id_2"],
"maxItems": 10
}
}
},
{
"type": "object",
"description": "Execute code.",
"required": ["type"],
"properties": {
"container": {
"description": "The code interpreter container. Can be a container ID or an object that specifies\nuploaded file IDs to make available to your code.\nFor OpenAI API compatibility ONLY. Request will be rejected if this field is set."
},
"type": { "type": "string", "enum": ["code_interpreter"] }
}
},
{
"type": "object",
"description": "A remote MCP server to use.",
"required": ["server_label", "server_url", "type"],
"properties": {
"allowed_tools": { "type": ["array", "null"], "items": { "type": "string" } },
"authorization": { "type": ["string", "null"] },
"connector_id": { "type": ["string", "null"] },
"headers": {
"type": ["object", "null"],
"additionalProperties": { "type": "string" },
"propertyNames": { "type": "string" }
},
"require_approval": { "type": ["string", "null"] },
"server_description": { "type": ["string", "null"] },
"server_label": { "type": "string" },
"server_url": { "type": "string" },
"type": { "type": "string", "enum": ["mcp"] }
}
}
],
"description": "Definition of one tool that the model can call."
},
"ModelToolChoice": {
"oneOf": [
{
"type": "string",
"description": "Controls tool access by the model. `\"none\"` makes model ignore tools, `\"auto\"` let the model automatically decide whether to call a tool, `\"required\"` forces model to pick a tool to call."
},
{
"type": "object",
"required": ["type", "name"],
"properties": {
"name": { "type": "string", "description": "Name of the function to use." },
"type": { "type": "string", "description": "Type is always `\"function\"`." }
}
}
],
"description": "Parameter to control how model chooses the tools."
},
"ModelUsage": {
"type": "object",
"required": [
"input_tokens",
"input_tokens_details",
"output_tokens",
"output_tokens_details",
"total_tokens",
"num_sources_used",
"num_server_side_tools_used"
],
"properties": {
"cost_in_nano_usd": {
"type": ["integer", "null"],
"format": "int64",
"description": "Cost in nano US dollars for this request."
},
"input_tokens": {
"type": "integer",
"format": "int32",
"description": "Number of input tokens used."
},
"input_tokens_details": {
"$ref": "#/components/schemas/InputTokensDetails",
"description": "Breakdown of the input tokens."
},
"num_server_side_tools_used": {
"type": "integer",
"format": "int32",
"description": "Number of server side tools used."
},
"num_sources_used": {
"type": "integer",
"format": "int32",
"description": "Number of sources used (for live search)."
},
"output_tokens": {
"type": "integer",
"format": "int32",
"description": "Number of output tokens used."
},
"output_tokens_details": {
"$ref": "#/components/schemas/OutputTokensDetails",
"description": "Breakdown of the output tokens."
},
"server_side_tool_usage_details": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/ServerSideToolUsageDetails",
"description": "Details about the server side tool usage."
}
]
},
"total_tokens": {
"type": "integer",
"format": "int32",
"description": "Total tokens used."
}
}
},
"OutputMessage": {
"type": "object",
"description": "An output message from the model.",
"required": ["content", "role", "type"],
"properties": {
"content": {
"type": "array",
"items": { "$ref": "#/components/schemas/OutputMessageContent" },
"description": "Content of the output message."
},
"id": { "type": "string", "description": "The unique ID of the output message." },
"role": {
"type": "string",
"description": "The role of the output message, which can be `assistant` or `tool`."
},
"status": {
"type": "string",
"description": "Status of the item. One of `completed`, `in_progress` or `incomplete`."
},
"type": {
"type": "string",
"description": "The type of the output message, which is always `message`."
}
}
},
"OutputMessageContent": {
"oneOf": [
{
"type": "object",
"description": "Text output.",
"required": ["text", "annotations", "type"],
"properties": {
"annotations": {
"type": "array",
"items": { "$ref": "#/components/schemas/Annotation" },
"description": "Citations."
},
"logprobs": {
"type": "array",
"items": { "$ref": "#/components/schemas/TokenLogProb" },
"description": "The log probabilities of each output token returned in the content of message."
},
"text": { "type": "string", "description": "The text output from the model." },
"type": { "type": "string", "enum": ["output_text"] }
}
},
{
"type": "object",
"description": "Refusal.",
"required": ["refusal", "type"],
"properties": {
"refusal": { "type": "string", "description": "The reason for the refusal." },
"type": { "type": "string", "enum": ["refusal"] }
}
}
]
},
"OutputTokensDetails": {
"type": "object",
"required": ["reasoning_tokens"],
"properties": {
"reasoning_tokens": {
"type": "integer",
"format": "int32",
"description": "Tokens generated by the model for reasoning."
}
}
},
"PromptUsageDetail": {
"type": "object",
"description": "Details of prompt usage.",
"required": ["text_tokens", "audio_tokens", "image_tokens", "cached_tokens"],
"properties": {
"audio_tokens": {
"type": "integer",
"format": "int32",
"description": "Audio prompt token used."
},
"cached_tokens": {
"type": "integer",
"format": "int32",
"description": "Token cached by xAI from previous requests and reused for this request."
},
"image_tokens": {
"type": "integer",
"format": "int32",
"description": "Image prompt token used."
},
"text_tokens": {
"type": "integer",
"format": "int32",
"description": "Text prompt token used."
}
}
},
"RankingMetric": {
"type": "string",
"description": "Deprecated: Metric now comes from collection creation.",
"enum": [
"RANKING_METRIC_UNKNOWN",
"RANKING_METRIC_L2_DISTANCE",
"RANKING_METRIC_COSINE_SIMILARITY"
]
},
"Reasoning": {
"type": "object",
"description": "The reasoning done by the model.",
"required": ["summary", "type"],
"properties": {
"encrypted_content": {
"type": ["string", "null"],
"description": "The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`."
},
"id": { "type": "string", "description": "The unique ID of the reasoning content." },
"status": {
"type": "string",
"description": "Status of the item. One of `completed`, `in_progress` or `incomplete`."
},
"summary": {
"type": "array",
"items": { "$ref": "#/components/schemas/ReasoningText" },
"description": "The reasoning text contents."
},
"type": {
"type": "string",
"description": "The type of the object, which is always `reasoning`."
}
}
},
"ReasoningConfiguration": {
"type": "object",
"properties": {
"effort": {
"type": ["string", "null"],
"description": "Constrains how hard a reasoning model thinks before responding. Possible values are `low` (uses fewer reasoning tokens), `medium` and `high` (uses more reasoning tokens).",
"default": "medium"
},
"generate_summary": {
"type": ["string", "null"],
"description": "Only included for compatibility."
},
"summary": {
"type": ["string", "null"],
"description": "A summary of the model's reasoning process. Possible values are `auto`, `concise` and `detailed`. Only included for compatibility. The model shall always return `detailed`."
}
}
},
"ReasoningText": {
"type": "object",
"required": ["text", "type"],
"properties": {
"text": { "type": "string", "description": "Reasoning done by the model." },
"type": {
"type": "string",
"description": "The type of the object, which is always `summary_text`."
}
}
},
"ReciprocalRankFusion": {
"type": "object",
"description": "Configuration for reciprocal rank fusion (RRF) reranking.",
"properties": {
"embedding_weight": {
"type": "number",
"format": "float",
"description": "Weight for embedding (dense) search results. Should be between 0 and 1. Defaults to 0.5."
},
"k": {
"type": ["integer", "null"],
"format": "int32",
"description": "The RRF constant k used in the reciprocal rank fusion formula. Defaults to 60."
},
"text_weight": {
"type": "number",
"format": "float",
"description": "Weight for keyword (sparse) search results. Should be between 0 and 1. Defaults to 0.5."
}
}
},
"RerankerModel": {
"type": "object",
"description": "Configuration for model-based reranking.",
"properties": {
"instructions": {
"type": ["string", "null"],
"description": "Instructions for the reranking model. Defaults to generic reranking instructions."
},
"model": {
"type": ["string", "null"],
"description": "The model to use for reranking. Defaults to standard reranker model."
}
}
},
"ResponseFormat": {
"oneOf": [
{
"type": "object",
"description": "Specify text response format, always `\"text\"`.",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["text"] } }
},
{
"type": "object",
"description": "Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `\"json_schema\"` instead of this.",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["json_object"] } }
},
{
"type": "object",
"description": "Specify json_schema response format with a given schema. Type is always `\"json_schema\"`.",
"required": ["json_schema", "type"],
"properties": {
"json_schema": {
"description": "A json schema representing the desired response schema. Includes the schema as a `\"schema\"` field."
},
"type": { "type": "string", "enum": ["json_schema"] }
}
}
],
"description": "Response format parameter for structured outputs."
},
"RetrievalMode": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/HybridRetrieval",
"description": "Hybrid search combining keyword and semantic search."
},
{
"type": "object",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["hybrid"] } }
}
],
"description": "Hybrid search combining keyword and semantic search."
},
{
"allOf": [
{
"$ref": "#/components/schemas/SemanticRetrieval",
"description": "Semantic search using dense embeddings."
},
{
"type": "object",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["semantic"] } }
}
],
"description": "Semantic search using dense embeddings."
},
{
"allOf": [
{
"$ref": "#/components/schemas/KeywordRetrieval",
"description": "Keyword search using sparse embeddings."
},
{
"type": "object",
"required": ["type"],
"properties": { "type": { "type": "string", "enum": ["keyword"] } }
}
],
"description": "Keyword search using sparse embeddings."
}
],
"description": "Retrieval mode configuration for document search."
},
"SampleChoice": {
"type": "object",
"required": ["index", "text", "finish_reason"],
"properties": {
"finish_reason": {
"type": "string",
"description": "Finish reason. `\"stop\"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `\"length\"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `\"end_turn\"` or `null` in streaming mode when the chunk is not the last."
},
"index": { "type": "integer", "format": "int32", "description": "Index of the choice." },
"text": { "type": "string", "description": "Text response." }
}
},
"SampleContent": {
"oneOf": [
{ "type": "string", "description": "Text prompt." },
{
"type": "array",
"items": { "type": "string" },
"description": "An array of strings, a token list, or an array of token lists."
}
]
},
"SampleRequest": {
"type": "object",
"description": "(Legacy) Request for `/v1/completions` endpoint",
"properties": {
"best_of": {
"type": ["integer", "null"],
"format": "int32",
"description": "(Unsupported) Generates multiple completions internally and returns the top-scoring one. Not functional yet."
},
"echo": {
"type": ["boolean", "null"],
"description": "Option to include the original prompt in the response along with the generated completion."
},
"frequency_penalty": {
"type": ["number", "null"],
"format": "float",
"description": "(Unsupported) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim."
},
"logit_bias": {
"type": ["object", "null"],
"description": "(Unsupported) Accepts a JSON object that maps tokens to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.",
"additionalProperties": { "type": "number", "format": "float" },
"propertyNames": { "type": "integer", "format": "int32" }
},
"logprobs": {
"type": ["boolean", "null"],
"description": "Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the logprob of the sampled token, so there may be up to `logprobs+1` elements in the response."
},
"max_tokens": {
"type": ["integer", "null"],
"format": "int32",
"description": "Limits the number of tokens that can be produced in the output. Ensure the sum of prompt tokens and `max_tokens` does not exceed the model's context limit."
},
"model": {
"type": "string",
"description": "Specifies the model to be used for the request."
},
"n": {
"type": ["integer", "null"],
"format": "int32",
"description": "Determines how many completion sequences to produce for each prompt. Be cautious with its use due to high token consumption; adjust `max_tokens` and stop sequences accordingly."
},
"presence_penalty": {
"type": ["number", "null"],
"format": "float",
"description": "(Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics."
},
"prompt": {
"$ref": "#/components/schemas/SampleContent",
"description": "Input for generating completions, which can be a string, list of strings, token list, or list of token lists. `<|endoftext|>` is used as a document separator, implying a new context start if omitted."
},
"seed": {
"type": ["integer", "null"],
"format": "int32",
"description": "If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend."
},
"stop": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "(Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens."
},
"stream": {
"type": ["boolean", "null"],
"description": "Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message."
},
"stream_options": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/StreamOptions",
"description": "Options for streaming response. Only set this when you set `stream: true`."
}
]
},
"suffix": {
"type": ["string", "null"],
"description": "(Unsupported) Optional string to append after the generated text."
},
"temperature": {
"type": ["number", "null"],
"format": "float",
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.",
"default": 1,
"example": 0.2,
"maximum": 2,
"minimum": 0
},
"top_p": {
"type": ["number", "null"],
"format": "float",
"description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both."
},
"user": {
"type": ["string", "null"],
"description": "A unique identifier representing your end-user, which can help xAI to monitor and detect abuse."
}
}
},
"SampleResponse": {
"type": "object",
"description": "(Legacy) Response for `/v1/completions` endpoint",
"required": ["id", "object", "created", "model", "choices"],
"properties": {
"choices": {
"type": "array",
"items": { "$ref": "#/components/schemas/SampleChoice" },
"description": "A list of response choices from the model. The length corresponds to the `n` in request body (default to 1)."
},
"created": {
"type": "integer",
"format": "int64",
"description": "The chat completion creation time in Unix timestamp."
},
"id": { "type": "string", "description": "ID of the request." },
"model": {
"type": "string",
"description": "Model to be used.",
"example": "grok-4-0709"
},
"object": {
"type": "string",
"description": "Object type of the response. This is always `\"text_completion\"`."
},
"system_fingerprint": {
"type": ["string", "null"],
"description": "System fingerprint, used to indicate xAI system configuration changes."
},
"usage": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/components/schemas/Usage", "description": "Token usage information." }
]
}
}
},
"SearchMatch": {
"type": "object",
"description": "SearchMatch defines a single match from a search request.",
"required": ["file_id", "chunk_id", "chunk_content", "score", "collection_ids", "fields"],
"properties": {
"chunk_content": { "type": "string", "description": "The chunk content." },
"chunk_id": { "type": "string", "description": "The chunk ID." },
"collection_ids": {
"type": "array",
"items": { "type": "string" },
"description": "The collection ID(s)."
},
"fields": {
"type": "object",
"description": "Metadata fields belonging to the document of this chunk.",
"additionalProperties": { "type": "string" },
"propertyNames": { "type": "string" }
},
"file_id": { "type": "string", "description": "The document ID." },
"score": { "type": "number", "format": "float", "description": "The relevance score." }
}
},
"SearchParameters": {
"type": "object",
"description": "Parameters to control realtime data.",
"properties": {
"from_date": {
"type": ["string", "null"],
"format": "date",
"description": "Date from which to consider the results in ISO-8601 YYYY-MM-DD. See\n<https://en.wikipedia.org/wiki/ISO_8601>.",
"example": "2024-06-24"
},
"max_search_results": {
"type": ["integer", "null"],
"format": "int32",
"description": "Maximum number of search results to use.",
"default": 15,
"maximum": 30,
"minimum": 1
},
"mode": {
"type": ["string", "null"],
"description": "Choose the mode to query realtime data:\n* `off`: no search performed and no external will be considered.\n* `on` (default): the model will search in every sources for relevant data.\n* `auto`: the model choose whether to search data or not and where to search the data.",
"default": "auto",
"example": "auto"
},
"return_citations": {
"type": ["boolean", "null"],
"description": "Whether to return citations in the response or not.",
"default": true
},
"sources": {
"type": ["array", "null"],
"items": { "$ref": "#/components/schemas/SearchSource" },
"description": "List of sources to search in. If no sources specified, the model will look over the web and X by default."
},
"to_date": {
"type": ["string", "null"],
"format": "date",
"description": "Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See\n<https://en.wikipedia.org/wiki/ISO_8601>.",
"example": "2024-12-24"
}
}
},
"SearchRequest": {
"type": "object",
"description": "SearchRequest defines the request to search for documents.",
"required": ["query", "source"],
"properties": {
"instructions": {
"type": ["string", "null"],
"description": "User-defined instructions to be included in the search query. Defaults to generic search instructions."
},
"limit": {
"type": ["integer", "null"],
"format": "int32",
"description": "The number of chunks to return.\nWill always return the top matching chunks.\nOptional, defaults to 10."
},
"query": {
"type": "string",
"description": "The query to search for which will be embedded using the\nsame embedding model as the one used for the source to query."
},
"ranking_metric": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/RankingMetric",
"description": "Deprecated: Metric now comes from collection creation."
}
]
},
"retrieval_mode": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/RetrievalMode",
"description": "How to perform the document search. Defaults to hybrid retrieval."
}
]
},
"source": {
"$ref": "#/components/schemas/DocumentsSource",
"description": "The source to query."
}
}
},
"SearchResponse": {
"type": "object",
"description": "SearchResponse defines the response to a search request.",
"required": ["matches"],
"properties": {
"matches": {
"type": "array",
"items": { "$ref": "#/components/schemas/SearchMatch" },
"description": "The search matches."
}
}
},
"SearchSource": {
"oneOf": [
{
"type": "object",
"required": ["type"],
"properties": {
"excluded_x_handles": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of X handles to exclude from the search results. X posts returned will not include\nany posts authored by these handles."
},
"included_x_handles": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": " NOTE: `included_x_handles` and `x_handles` are the same parameter.\n`included_x_handles` is the new name but we keep both for backward compatibility.\n\nX Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`."
},
"post_favorite_count": {
"type": ["integer", "null"],
"format": "int32",
"description": "The minimum favorite count of the X posts to consider."
},
"post_view_count": {
"type": ["integer", "null"],
"format": "int32",
"description": "The minimum view count of the X posts to consider."
},
"type": { "type": "string", "enum": ["x"] },
"x_handles": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "DEPRECATED in favor of `included_x_handles`. Use `included_x_handles` instead.\nX Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`.",
"deprecated": true
}
}
},
{
"type": "object",
"required": ["type"],
"properties": {
"allowed_websites": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of website to allow in the search results. This parameter act as a whitelist\nwhere only those websites can be selected. A maximum of 5 websites can be selected.\n\nNote 1: If no relevant information is found on those websites, the number of results\nreturned might be smaller than `max_search_results`.\n\nNote 2: This parameter cannot be set with `excluded_websites`.",
"example": ["wikipedia.com"],
"maxItems": 5
},
"country": {
"type": ["string", "null"],
"format": "iso3166-1-alpha-2",
"description": "ISO alpha-2 code of the country. If the country is set, only data coming from this country\nwill be considered. See <https://en.wikipedia.org/wiki/ISO_3166-2>.",
"example": "BE"
},
"excluded_websites": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of website to exclude from the search results without protocol specification or\nsubdomains. A maximum of 5 websites can be excluded.\n\nNote 2: This parameter cannot be set with `allowed_websites`",
"example": ["wikipedia.com"],
"maxItems": 5
},
"safe_search": {
"type": ["boolean", "null"],
"description": "If set to true, mature content won't be considered during the search. Default to `true`."
},
"type": { "type": "string", "enum": ["web"] }
}
},
{
"type": "object",
"required": ["type"],
"properties": {
"country": {
"type": ["string", "null"],
"format": "iso3166-1-alpha-2",
"description": "ISO alpha-2 code of the country. If the country is set, only data coming from this country\nwill be considered. See <https://en.wikipedia.org/wiki/ISO_3166-2>.",
"example": "BE"
},
"excluded_websites": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of website to exclude from the search results without protocol specification or\nsubdomains. A maximum of 5 websites can be excluded.",
"example": ["foxnews.com"],
"maxItems": 5
},
"safe_search": {
"type": ["boolean", "null"],
"description": "If set to true, mature content won't be considered during the search. Default to `true`."
},
"type": { "type": "string", "enum": ["news"] }
}
},
{
"type": "object",
"required": ["links", "type"],
"properties": {
"links": {
"type": "array",
"items": { "type": "string" },
"description": "Links of the RSS feeds.",
"example": ["https://status.x.ai/feed.xml"],
"maxItems": 1,
"minItems": 1
},
"type": { "type": "string", "enum": ["rss"] }
}
}
]
},
"SemanticRetrieval": {
"type": "object",
"description": "Document search using semantic similarity (dense embeddings).",
"properties": {
"reranker": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/RerankerModel",
"description": "Optional, but always used when doing search across multiple collections."
}
]
}
}
},
"ServerSideToolUsageDetails": {
"type": "object",
"required": [
"web_search_calls",
"x_search_calls",
"code_interpreter_calls",
"file_search_calls",
"mcp_calls",
"document_search_calls"
],
"properties": {
"code_interpreter_calls": {
"type": "integer",
"format": "int32",
"description": "Number of code interpreter calls."
},
"document_search_calls": {
"type": "integer",
"format": "int32",
"description": "Number of document search calls."
},
"file_search_calls": {
"type": "integer",
"format": "int32",
"description": "Number of file search calls."
},
"mcp_calls": {
"type": "integer",
"format": "int32",
"description": "Number of MCP calls."
},
"web_search_calls": {
"type": "integer",
"format": "int32",
"description": "Number of web search calls."
},
"x_search_calls": {
"type": "integer",
"format": "int32",
"description": "Number of X search calls."
}
}
},
"StartDeferredChatResponse": {
"type": "object",
"required": ["request_id"],
"properties": {
"request_id": {
"type": "string",
"description": "A unique request ID for the chat response."
}
}
},
"StreamOptions": {
"type": "object",
"description": "Options available when using streaming response.",
"required": ["include_usage"],
"properties": {
"include_usage": {
"type": "boolean",
"description": "Set an additional chunk to be streamed before the `data: [DONE]` message. The other chunks will return `null` in `usage` field."
}
}
},
"SystemMessageContent": {
"oneOf": [
{ "type": "string", "description": "Text content of system prompt." },
{
"type": "array",
"items": { "$ref": "#/components/schemas/SystemMessagePart" },
"description": "An array of system prompt parts."
}
]
},
"SystemMessagePart": {
"type": "object",
"required": ["type", "text"],
"properties": {
"cache_control": { "description": "(Unsupported) Cache control." },
"text": { "type": "string", "description": "System prompt text." },
"type": {
"type": "string",
"description": "Type of the object. This is always `\"text\"`."
}
}
},
"TokenLogProb": {
"type": "object",
"required": ["token", "logprob", "top_logprobs"],
"properties": {
"bytes": {
"type": ["array", "null"],
"items": { "type": "integer", "format": "int32", "minimum": 0 },
"description": "The ASCII encoding of the output character."
},
"logprob": {
"type": "number",
"format": "float",
"description": "The log probability of returning this token."
},
"token": { "type": "string", "description": "The token." },
"top_logprobs": {
"type": "array",
"items": { "$ref": "#/components/schemas/TopLogProb" },
"description": "An array of the most likely tokens to return at this token position."
}
}
},
"TokenizeRequest": {
"type": "object",
"properties": {
"model": { "type": "string", "description": "The model to tokenize with." },
"text": { "type": "string", "description": "The text content to be tokenized." },
"user": { "type": ["string", "null"], "description": "Optional user identifier." }
}
},
"TokenizeResponse": {
"type": "object",
"required": ["token_ids"],
"properties": {
"token_ids": {
"type": "array",
"items": { "$ref": "#/components/schemas/TokenizeResponseToken" },
"description": "A list of tokens."
}
}
},
"TokenizeResponseToken": {
"type": "object",
"required": ["token_id", "string_token", "token_bytes"],
"properties": {
"string_token": { "type": "string", "description": "The string of the token." },
"token_bytes": {
"type": "array",
"items": { "type": "integer", "format": "int32", "minimum": 0 },
"description": "The bytes that constituted the token."
},
"token_id": {
"type": "integer",
"format": "int32",
"description": "The integer representation of the token for the model.",
"minimum": 0
}
}
},
"Tool": {
"oneOf": [
{
"type": "object",
"required": ["function", "type"],
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionDefinition",
"description": "Definition of tool call available to the model."
},
"type": { "type": "string", "enum": ["function"] }
}
},
{
"type": "object",
"required": ["sources", "type"],
"properties": {
"sources": {
"type": "array",
"items": { "$ref": "#/components/schemas/SearchSource" }
},
"type": { "type": "string", "enum": ["live_search"] }
}
}
],
"description": "Definition of one tool that the model can call."
},
"ToolCall": {
"type": "object",
"required": ["id", "function"],
"properties": {
"function": {
"$ref": "#/components/schemas/Function",
"description": "Function to call for the tool call."
},
"id": {
"type": "string",
"description": "A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request."
},
"index": {
"type": ["integer", "null"],
"format": "int32",
"description": "Index of the tool call."
},
"type": {
"type": ["string", "null"],
"description": "Type of tool call, should be `\"function\"` or `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"`"
}
}
},
"ToolChoice": {
"oneOf": [
{
"type": "string",
"description": "Controls tool access by the model. `\"none\"` makes model ignore tools, `\"auto\"` let the model automatically decide whether to call a tool, `\"required\"` forces model to pick a tool to call."
},
{
"type": "object",
"required": ["type"],
"properties": {
"function": {
"oneOf": [
{ "type": "null" },
{
"$ref": "#/components/schemas/FunctionChoice",
"description": "Name of the function to use."
}
]
},
"type": { "type": "string", "description": "Type is always `\"function\"`." }
}
}
],
"description": "Parameter to control how model chooses the tools."
},
"TopLogProb": {
"type": "object",
"required": ["token", "logprob"],
"properties": {
"bytes": {
"type": ["array", "null"],
"items": { "type": "integer", "format": "int32", "minimum": 0 },
"description": "The ASCII encoding of the output character."
},
"logprob": {
"type": "number",
"format": "float",
"description": "The log probability of returning this token."
},
"token": { "type": "string", "description": "The token." }
}
},
"Usage": {
"type": "object",
"required": [
"prompt_tokens",
"completion_tokens",
"total_tokens",
"prompt_tokens_details",
"completion_tokens_details",
"num_sources_used"
],
"properties": {
"completion_tokens": {
"type": "integer",
"format": "int32",
"description": "Total completion token used."
},
"completion_tokens_details": {
"$ref": "#/components/schemas/CompletionUsageDetail",
"description": "Breakdown of completion token usage of different types."
},
"num_sources_used": {
"type": "integer",
"format": "int32",
"description": "Number of individual live search source used."
},
"prompt_tokens": {
"type": "integer",
"format": "int32",
"description": "Total prompt token used."
},
"prompt_tokens_details": {
"$ref": "#/components/schemas/PromptUsageDetail",
"description": "Breakdown of prompt token usage of different types."
},
"total_tokens": {
"type": "integer",
"format": "int32",
"description": "Total token used, the sum of prompt token and completion token amount."
}
}
},
"WebSearchAction": {
"oneOf": [
{
"type": "object",
"description": "Action type \"search\" - Performs a web search query.",
"required": ["query", "type"],
"properties": {
"query": { "type": "string", "description": "The search query." },
"sources": {
"type": "array",
"items": { "$ref": "#/components/schemas/WebSearchSource" },
"description": "The sources used in the search."
},
"type": { "type": "string", "enum": ["search"] }
}
},
{
"type": "object",
"description": "Action type \"open_page\" - Opens a specific URL from search results.",
"required": ["url", "type"],
"properties": {
"type": { "type": "string", "enum": ["open_page"] },
"url": { "type": "string", "description": "The URL of the page to open." }
}
},
{
"type": "object",
"description": "Action type \"find\": Searches for a pattern within a loaded page.",
"required": ["source", "pattern", "type"],
"properties": {
"pattern": {
"type": "string",
"description": "The pattern or text to search for within the page."
},
"source": {
"$ref": "#/components/schemas/WebSearchSource",
"description": "The source of the page to search in."
},
"type": { "type": "string", "enum": ["find"] }
}
}
]
},
"WebSearchCall": {
"type": "object",
"description": "The output of a web search tool call.",
"required": ["type", "action"],
"properties": {
"action": {
"$ref": "#/components/schemas/WebSearchAction",
"description": "An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find)."
},
"id": { "type": "string", "description": "The unique ID of the web search tool call." },
"status": { "type": "string", "description": "The status of the web search tool call." },
"type": {
"type": "string",
"description": "The type of the web search tool call. Always `web_search_call`."
}
}
},
"WebSearchFilters": {
"type": "object",
"properties": {
"allowed_domains": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of website domains (without protocol specification or subdomains)\nto restrict search results to (e.g., [\"example.com\"]). A maximum of 5 websites can be allowed.\nUse this as a whitelist to limit results to only these specific sites; no other websites will\nbe considered. If no relevant information is found on these websites, the number of results\nreturned might be smaller than `max_search_results` set in `SearchParameters`. Note: This\nparameter cannot be set together with `excluded_domains`.",
"example": ["example.com"],
"maxItems": 5
},
"excluded_domains": {
"type": ["array", "null"],
"items": { "type": "string" },
"description": "List of website domains (without protocol specification or subdomains) to exclude from search results (e.g., [\"example.com\"]).\nUse this to prevent results from unwanted sites. A maximum of 5 websites can be excluded.\nThis parameter cannot be set together with `allowed_domains`.",
"example": ["example.com"],
"maxItems": 5
}
}
},
"WebSearchOptions": {
"type": "object",
"properties": {
"filters": { "description": "Only included for compatibility." },
"search_context_size": {
"type": ["string", "null"],
"description": "This field included for compatibility reason with OpenAI's API. It is mapped to `max_search`.",
"default": "medium",
"example": "medium"
},
"user_location": { "description": "Only included for compatibility." }
}
},
"WebSearchSource": {
"type": "object",
"required": ["type"],
"properties": {
"type": { "type": "string", "description": "The type of source." },
"url": { "type": "string", "description": "The URL of the source." }
}
}
},
"securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }
}
}