Create a response with POST /v1/responses — Responses API: Primary Endpoint

Your first request

The POST /v1/responses endpoint is the main entry point for the Responses API. This is where you send your prompts and receive responses from Grok models. In this lesson, you’ll learn how to build and send your first request.

Authentication

All requests require an authentication header with your xAI API key:

Authorization: Bearer $XAI_API_KEY

You can generate your keys at console.x.ai. Keep them secret—never commit them to a Git repository.

Minimal request

Here’s the simplest possible request:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-0309-reasoning",
    "input": "Explain what machine learning is in 3 sentences."
  }'

Two fields are enough:

model: the ID of the Grok model to use
input: your prompt, as plain text

With the Python SDK

If you use the OpenAI SDK (xAI-compatible), the syntax is similar:

from openai import OpenAI

client = OpenAI(
    api_key="xai-...",
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Explain what machine learning is in 3 sentences."
)

print(response.output[0].content[0].text)

Simple vs structured input

The input parameter accepts two formats.

Plain text

{
  "model": "grok-4.20-0309-reasoning",
  "input": "What is the capital of France?"
}

Structured array

For multimodal inputs or explicit roles:

{
  "model": "grok-4.20-0309-reasoning",
  "input": [
    {
      "role": "user",
      "content": "Analyze this image and describe what you see."
    }
  ]
}

The array format gives you more control, especially for including images or specifying different roles.

The instructions parameter

To give the model system behavior, use instructions rather than adding a system message in input:

{
  "model": "grok-4.20-0309-reasoning",
  "instructions": "You are a French cuisine expert. Always respond including a chef's tip.",
  "input": "How do I make a successful béchamel?"
}

The instructions field is equivalent to the system prompt in Chat Completions. It defines the model’s overall behavior for the entire conversation.

Practical exercise

Try building a request that:

Uses the grok-4.20-0309-reasoning model
Defines system instructions for a technical assistant
Asks a question about Python

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-0309-reasoning",
    "instructions": "You are a senior Python developer. Give concise code examples.",
    "input": "How do I read a JSON file in Python?"
  }'

Key takeaways

POST /v1/responses is the main endpoint—it requires model and input
input accepts plain text or a structured array with roles
instructions defines the model’s system behavior
Authentication happens via the Authorization: Bearer header
The OpenAI SDK is compatible with xAI by changing the base_url