openapi: 3.1.0
info:
title: xAI's REST v1 API
description: REST API for xAI compatible with other providers.
license:
name: ''
version: 1.0.0
tags:
- name: v1
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: latest
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: latest
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: latest
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: '
Human: Hello, how are you?
Assistant:'
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
filter: document_type = "financial_report" AND year > 2020
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/files:
get:
tags:
- v1
summary: 'List files owned by the authenticated team, paginated. The response
always returns a `pagination_token`; pass it back as a query parameter
to fetch the next page. The end of the list is reached when the
returned `data` array is shorter than `limit`.'
operationId: handle_list_files_request
parameters:
- name: limit
in: query
description: The maximum number of objects to be returned in a single response.
required: false
schema:
type: integer
format: int32
- name: order
in: query
description: The ordering to sort the returned files. Use `asc` for ascending and `desc` for descending order.
required: false
schema:
type: string
- name: sort_by
in: query
description: 'The field to sort by. Valid options: `created_at`, `filename`, `size`. Defaults to `created_at`.'
required: false
schema:
type: string
- name: pagination_token
in: query
description: The pagination token returned by the previous list files request.
required: false
schema:
type: string
- name: after
in: query
description: Only included for compatibility. Use `pagination_token` instead.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListFilesResponse'
example:
data:
- id: file_a128090d-f0c9-4873-bd84-e499777e7417
object: file
bytes: 12345
created_at: 1762345678
expires_at: null
filename: document.pdf
purpose: ''
pagination_token: file_a128090d-f0c9-4873-bd84-e499777e7417
security:
- bearerAuth: []
post:
tags:
- v1
summary: 'Upload a file to xAI''s storage. Returns the file''s metadata. Files can
be referenced by ID anywhere a `file_id` is accepted (e.g. chat
attachments). Maximum file size: 50 MB. Files are kept until you
delete them, or until `expires_after` elapses if set at upload time.'
operationId: handle_upload_file_request
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/UploadFileMultipartRequest'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/File'
example:
id: file_a128090d-f0c9-4873-bd84-e499777e7417
object: file
bytes: 12345
created_at: 1762345678
expires_at: 1762432078
filename: document.pdf
purpose: ''
'400':
description: 'Bad request. Common causes: `expires_after` outside [3600, 2592000], `expires_after` field appearing after `file` in the multipart body, missing or unnamed `file` part, invalid filename.'
'413':
description: Payload too large -- file exceeds 50 MB.
security:
- bearerAuth: []
/v1/files/{file_id}:
get:
tags:
- v1
summary: 'Retrieve metadata for a single file by ID. Errors with 404 if the file
doesn''t exist, has been deleted, or has passed its `expires_at`.'
operationId: handle_retrieve_file_request
parameters:
- name: file_id
in: path
description: The file's `id` returned by upload or list.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/File'
'404':
description: File not found, deleted, or expired.
security:
- bearerAuth: []
delete:
tags:
- v1
summary: 'Delete a file by ID. After this returns, the file no longer appears in
`GET /v1/files`, content download returns 404, and the ID can no longer
be referenced in chat attachments.'
operationId: handle_delete_file_request
parameters:
- name: file_id
in: path
description: The file's `id` to delete.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteFileResponse'
example:
id: file_a128090d-f0c9-4873-bd84-e499777e7417
deleted: true
'404':
description: File not found or already deleted.
security:
- bearerAuth: []
/v1/files/{file_id}/content:
get:
tags:
- v1
summary: 'Download the contents of a file as a stream of raw bytes. The response
`Content-Type` is `application/octet-stream`. Use this for the binary
payload; use `GET /v1/files/{file_id}` for metadata only.'
operationId: handle_download_file_content_request
parameters:
- name: file_id
in: path
description: The file's `id` to download.
required: true
schema:
type: string
- name: format
in: query
description: Format of the downloaded content.
required: false
schema:
$ref: '#/components/schemas/ContentFormat'
responses:
'200':
description: Success -- raw file bytes streamed in chunks.
content:
application/octet-stream:
schema:
type: string
'404':
description: File not found, deleted, or expired.
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-imagine-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-imagine-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-imagine-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-imagine-image
response_format: url
n: 2
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GeneratedImageResponse'
example:
data:
- url: '...'
- 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/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: latest
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: latest
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: latest
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
# --- truncated at 32 KB (210 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xai/refs/heads/main/openapi/xai-v1-api-openapi.yml