Attach files to a Grok chat request

Send input_file on POST https://api.x.ai/v1/responses. A public file_url needs no upload. A private file goes to POST /v1/files first, then you pass file_id. The API turns on attachment_search and searches the documents for you.

Public URL

curl -X POST "https://api.x.ai/v1/responses" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "What was the total revenue in this report?"},
          {"type": "input_file", "file_url": "https://docs.x.ai/assets/api-examples/documents/sales-report.txt"}
        ]
      }
    ]
  }'

Upload, then attach by id

import os
from xai_sdk import Client
from xai_sdk.chat import user, file

client = Client(api_key=os.getenv("XAI_API_KEY"))

uploaded = client.files.upload("/path/to/your/document.pdf")

chat = client.chat.create(model="grok-4.6")
chat.append(user(
    "What was the total revenue in this report?",
    file(uploaded.id),
))
print(chat.sample().content)

Responses body for an uploaded file: {"type": "input_file", "file_id": "file_…"}. purpose=assistants is the conventional upload flag; xAI stores it for SDK compatibility and does not enforce it.

Stack several input_file parts on one message to search across documents. Follow-ups keep file context: Responses API uses previous_response_id; the xAI SDK uses use_encrypted_content=True then chat.append(response) before the next question.

Limits

• Max 48 MB per file.
• Agentic models only (grok-4.20, grok-4.5, grok-4.6). Use grok-4.6.
• No batch (n > 1). Stream if you want to see search tool calls.
• Formats that work: .txt, .md, .csv, .json, .pdf, code files, and other text-based types.

Delete with DELETE https://api.x.ai/v1/files/{id} when you are done. Optional expires_after (3600–2592000 seconds) auto-deletes; put that multipart field before file.

Pitfalls

• Public URLs must be reachable by xAI. Private docs need an upload and file_id.
• Combining files with code_interpreter / code_execution() is supported for CSV-style analysis; document search still runs as an agentic tool.
• Console API credits are separate from SuperGrok's weekly pool on grok.com.