Call the API with cURL — Grok API quickstart

The universal tool for testing APIs

cURL is a command-line tool available on every operating system. It lets you send HTTP requests without installing an SDK or writing a program. It’s the ideal tool for quickly testing an endpoint, debugging a request, or automating calls in a shell script.

Your first cURL request

Here’s how to send a request to the Grok API with cURL:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [
      {"role": "user", "content": "Hello, introduce yourself in one sentence."}
    ]
  }'

Breaking down the command

curl https://api.x.ai/v1/chat/completions: sends a POST request (implied by -d) to the endpoint
-H "Authorization: Bearer $XAI_API_KEY": adds the authentication header with your key
-H "Content-Type: application/json": says the body is JSON
-d '{...}': the request body in JSON format

Use the /v1/responses endpoint

The modern /v1/responses endpoint offers a more concise syntax:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "Explain machine learning to me in simple terms."
  }'

Note that input replaces messages for simple requests. You can pass a string directly instead of an array of messages.

Useful cURL options

Format the JSON output

The raw response is hard to read. Use jq to format it:

curl -s https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}' | jq .

The -s (silent) option hides cURL’s progress bar.

Extract only the answer

To get the text of the answer without the metadata:

curl -s https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }' | jq -r '.choices[0].message.content'

See the response headers

To debug rate limits or errors, add -i to display the HTTP headers:

curl -i https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Test"}'

Read the body from a file

For complex requests, store the JSON in a file:

# request.json
{
  "model": "grok-4.5",
  "messages": [
    {"role": "system", "content": "You are a translator."},
    {"role": "user", "content": "Translate into French: Hello world"}
  ],
  "temperature": 0.3
}

Then reference it with @:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Debug common errors

401 Unauthorized: an invalid or missing API key. Check echo $XAI_API_KEY
400 Bad Request: malformed JSON. Validate your JSON with jq . < request.json
429 Too Many Requests: you hit the rate limit. Wait a few seconds
404 Not Found: check the URL and the endpoint path

Key takeaways

cURL is perfect for testing and debugging without writing code
Authenticate with -H "Authorization: Bearer $XAI_API_KEY"
Use jq to format and filter JSON responses
Store complex requests in separate JSON files