Quickstart: Make your first Flatkey API call

Make your first Flatkey request in about five minutes. You need one API key and the OpenAI-compatible base URL https://router.flatkey.ai/v1.

Already using the OpenAI SDK? Keep your request code and change the base URL to https://router.flatkey.ai/v1.

Before you begin

You need:

A Flatkey account
cURL, Python 3.8+, Node.js 16+, or PowerShell
Prepaid credit for the model request

Set up your account and API key

Choose a prepaid package in the Flatkey Wallet

Next, open API Keys and select Create API Key.

Give the key a clear name. You can also set a credit limit and expiration time before selecting Save changes.

Configure the name, credit limit, and expiration for a Flatkey API key

Copy the generated secret and store it securely. Flatkey API keys start with sk-fk-.

Never commit an API key to source control or expose it in browser-side code. Use an environment variable or secrets manager.

Send your first request

Set the API key in your current shell:

export FLATKEY_API_KEY="sk-fk-..."

$env:FLATKEY_API_KEY="sk-fk-..."

For Python, install the OpenAI SDK with pip install openai. For TypeScript, run npm install openai. cURL and PowerShell need no SDK.The following examples call the same model through the same Flatkey endpoint:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello! What can you do?"}
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Hello! What can you do?"}
    ],
)

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "user", content: "Hello! What can you do?" },
  ],
});

console.log(response.choices[0].message.content);

$headers = @{
  Authorization = "Bearer $env:FLATKEY_API_KEY"
  "Content-Type" = "application/json"
}

$body = @{
  model = "gpt-4o-mini"
  messages = @(
    @{ role = "user"; content = "Hello! What can you do?" }
  )
} | ConvertTo-Json -Depth 4

$response = Invoke-RestMethod `
  -Uri "https://router.flatkey.ai/v1/chat/completions" `
  -Method Post `
  -Headers $headers `
  -Body $body

$response.choices[0].message.content

After the request completes, open Usage Logs in the Flatkey Console. Enter gpt-4o-mini in Model Name and select Search. The screenshot shows where to apply the filter; your completed request should appear in the table with token counts, latency, and cost.

Use the Model Name filter in Flatkey Usage Logs

If the table still shows No Logs Found, wait a few seconds and search again. If it remains empty, confirm the API key and Base URL used by the request.

Keep building

Connect Flatkey to the coding tool you use:

Claude Code

Configure Claude Code manually or with CC Switch.

Codex CLI

Route Codex CLI requests through Flatkey.

Codex Desktop

Configure the Codex desktop app manually or with CC Switch.

Read the response

For Chat Completions responses, the fields you will use most often are:

choices[0].message.content — generated text
model — the model that handled the request
usage — prompt, completion, and total token counts

See the Chat Completions reference for the complete schema.

Stream the response

Set stream to true when you want tokens as they are generated.

curl --no-buffer https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Write a two-line welcome message."}
    ],
    "stream": true
  }'

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Write a two-line welcome message."}
    ],
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "user", content: "Write a two-line welcome message." },
  ],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Handle common errors

HTTP status	What it usually means	What to do
`401`	The API key is missing, invalid, or revoked	Check the `Authorization: Bearer` header and create a new key if needed
`401 insufficient_balance`	The prepaid balance is empty	Add credit from Wallet
`404 model_not_found`	The model ID is misspelled or unavailable	Check the Model Directory for the exact ID
`429`	The request exceeded a rate limit	Retry with exponential backoff and jitter
`500` or `503`	The provider or route is temporarily unavailable	Retry with backoff and check Model Health

See API errors for response formats and troubleshooting details.

Next steps

Authentication

Learn how Flatkey API keys and authorization headers work.

Model Directory

Find supported model IDs and current pricing.

OpenAI SDK

Use Flatkey with the OpenAI Python and TypeScript SDKs.

Usage Logs

Monitor requests, token usage, latency, and cost.

Billing

Understand prepaid credit and usage charges.

​Before you begin

Claude Code

Codex CLI

Codex Desktop

​Read the response

​Stream the response

​Handle common errors

​Next steps

Authentication

Model Directory

OpenAI SDK

Usage Logs

Billing

Before you begin

Read the response

Stream the response

Handle common errors

Next steps