API Architecture Overview

A product manager at a healthcare startup needed to add AI-powered triage to their patient intake form. She had used ChatGPT daily for months, but when the CTO said "just use the API," she froze. The web interface felt like magic. The API felt like a locked door.

It is not. The OpenAI API is a straightforward HTTP service. You send a JSON request, you get a JSON response. Everything ChatGPT does runs on the same API you are about to learn. The difference is that you control every parameter, every token, every dollar spent.

The Core Mental Model

The OpenAI API follows standard REST conventions. Every interaction is an HTTP request to a specific endpoint, authenticated with a Bearer token, carrying a JSON payload. The server processes your request and returns a JSON response -- or, if you enable streaming, a series of server-sent events.

That is it. No WebSockets, no long-lived connections, no binary protocols. If you have ever called a REST API, you already know the transport layer.

Authentication: API Keys and Scoping

Every request requires an API key passed in the Authorization header:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-proj-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Hello"}]}'

OpenAI uses a hierarchy for access control: Organization > Project > API Key. This matters more than most tutorials acknowledge.

You can pass organization and project IDs as headers if your key spans multiple:

OpenAI-Organization: org-abc123
OpenAI-Project: proj-def456

The Two Main API Surfaces

OpenAI currently offers two primary ways to interact with language models:

Chat Completions is the API most tutorials and SDKs use. It is tested and will continue to be supported. The Responses API is OpenAI's newer surface that adds built-in tools (web search, code interpreter, file search) and first-class reasoning model support. We cover both in this course.

SDKs: Python and Node.js

While you can call the API with raw HTTP requests, the official SDKs handle retry logic, streaming parsing, and type safety for you.

Python:

from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from environment

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Explain REST APIs in one paragraph."}]
)

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

Node.js:

import OpenAI from 'openai';

const client = new OpenAI(); // reads OPENAI_API_KEY from environment

const response = await client.chat.completions.create({
  model: 'gpt-4.1-mini',
  messages: [{ role: 'user', content: 'Explain REST APIs in one paragraph.' }],
});

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

Both SDKs follow the same pattern: create a client, call a method that mirrors the API endpoint, get back a typed response object. The SDK automatically reads your API key from the OPENAI_API_KEY environment variable.

Request and Response Anatomy

Every Chat Completions request has this shape:

{
  "model": "gpt-4.1-mini",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is an API?"}
  ],
  "temperature": 0.7,
  "max_tokens": 500
}

Every response has this shape:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4.1-mini-2025-04-14",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "An API is..."},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 87,
    "total_tokens": 112
  }
}

The usage field tells you exactly how many tokens you consumed. At GPT-4.1-mini's pricing, 112 tokens costs a fraction of a cent. But at scale -- millions of requests per day -- those fractions add up fast. Always log usage.