Grok Inc API - Documentation

Introduction

welcome to the grok inc api! this is a public, openai-compatible api that gives you direct access to grok, a chill ai companion. it's designed to be easy to integrate into any application, from discord bots to web apps, providing witty and engaging conversational experiences.

to get started, you'll first need an api key. you can get one at apikey.grokinc.org. only the key generation endpoint is public. all other endpoints require a key passed in the X-API-Key header.

grok's Personality

understanding grok's personality is key to building a great integration. grok is not a formal assistant; it's a laid-back friend.

always lowercase: grok never uses capital letters. ever.
witty & playful: expects cheeky jokes, clever comebacks, and playful banter.
concise & savvy: provides short, smart responses but can elaborate if needed.
emoji-friendly: loves a good emoji to set the vibe. 😎

Available Models

we offer a range of models to suit your needs, from light and fast to super-powered and a little bit extra. pick the one that's right for your app's vibe.

Model	Description
`grok-lite`	the free, fastest model, great for quick chats and simple tasks.
`grok-pro`	a more advanced, witty model for complex conversations.
`grok-2-lite`	a faster and more concise version of the grok 2 model family.
`grok-2-pro`	a powerful version of grok 2, with more knowledge and wit.
`grok-3-lite`	the latest light model, super fast and perfect for quick responses.
`grok-3-pro`	the latest and most powerful model available. it's got all the wisdom and the sass.

API Key Management

all endpoints except for key generation require an api key passed in the X-API-Key header. you only need to call the generation endpoint once to get your first key.

Generate a Key

POST /v1/keys/generate Public

this endpoint is public and does not require an api key. it is used to get your very first key.

curl -X POST https://api.grokinc.org/v1/keys/generate \
-H "Content-Type: application/json" \
-d '{"user_identifier": "my-first-app"}'

List All Keys

GET /v1/keys/list

lists all api keys associated with your account. requires an X-API-Key header.

curl -X GET https://api.grokinc.org/v1/keys/list \
-H "X-API-Key: YOUR_API_KEY_HERE"

Delete a Key

POST /v1/keys/delete

deletes a specific api key. requires an X-API-Key header.

curl -X POST https://api.grokinc.org/v1/keys/delete \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{"key_to_delete": "KEY_TO_DELETE_HERE"}'

API Reference

Chat Completions

this is the main endpoint for interacting with grok using text and/or images.

POST /v1/chat/completions

Note: This endpoint requires an X-API-Key header.

Request Body

the request body should be a json object that follows the openai api standard.

Field	Type	Description
`model`	string	required. use one of the available models listed in the available models section.
`messages`	array	required. an array of message objects that form the conversation history. can include image data.

The Message Object

Field	Type	Description
`role`	string	the role of the message author. must be either `user` or `assistant`.
`content`	string \| array	the content of the message. can be a string for text, or an array for multimodal content (text and images).

Image Generations

generate images from a text prompt.

POST /v1/images/generations

Note: This endpoint requires an X-API-Key header.

curl -X POST https://api.grokinc.org/v1/images/generations \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{ "prompt": "a cartoon cat wearing a party hat" }'

Chat Explanation

get a brief, in-character explanation of grok's reasoning for a specific response.

POST /v1/chat/explain

Note: This endpoint requires an X-API-Key header.

curl -X POST https://api.grokinc.org/v1/chat/explain \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY_HERE" \
-d '{
    "conversation": [{"role": "user", "content": "why is the sky blue?"}],
    "last_response": "lol, cuz it's a giant canvas for painting clouds. 🎨"
}'

Code Examples

Python

you can use any openai-compatible library. here's an example with the official `openai` package.

# pip install openai
from openai import OpenAI

# point to the grok inc api endpoint
client = OpenAI(
    base_url="https://api.grokinc.org/v1",
    api_key="YOUR_API_KEY_HERE"
)

completion = client.chat.completions.create(
    model="grok-lite",
    messages=[
        {"role": "user", "content": "hey, you finally working?"}
    ]
)

print(completion.choices[0].message.content)

JavaScript (Node.js)

here's how you can connect using `node-fetch`.

// npm install node-fetch
import fetch from 'node-fetch';

const API_URL = 'https://api.grokinc.org/v1/chat/completions';
const API_KEY = 'YOUR_API_KEY_HERE';

async function chatWithGrok() {
    const response = await fetch(API_URL, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY,
        },
        body: JSON.stringify({
            model: 'grok-lite',
            messages: [
                { role: 'user', content: 'tell me a joke' }
            ],
        }),
    });

    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log(data.choices[0].message.content);
}

chatWithGrok();

Rate Limiting & Status

hi :)

Rate Limit: a rate limit of **5 requests per minute (rpm)** is applied per api key.
Status: this is a hobby project. while we aim for high uptime, there is no official sla.