C.W.K.
Stream
More →
Lesson 01 of 05 · published

API Surface

~18 min · api, endpoints

Level 0Downloader
0 XP0/41 lessons0/11 achievements
0/120 XP to next level120 XP to go0% complete

The whole surface in one table

Ollama's HTTP API is a small REST surface — under ten endpoints you'll touch. Streaming is on by default. All durations in responses are in nanoseconds. There is no authentication; the daemon binds to localhost by default, which is the security boundary.

MethodEndpointPurpose
POST/api/chatConversational (messages array). Use this for almost everything.
POST/api/generateRaw completion (single prompt). FIM / autocomplete shape.
GET/api/tagsList installed models.
POST/api/showShow model details.
POST/api/pullDownload a model (streams progress).
DELETE/api/deleteRemove a model.
POST/api/embedGenerate embeddings.
GET/api/psList currently loaded models.
GET/api/versionDaemon version.

Two defaults that bite people

  • Streaming is on. If you send {"model": "...", "messages": [...]} without "stream": false, you get NDJSON back, not a single JSON object. People crash JSON parsers on this constantly.
  • Durations are nanoseconds. total_duration: 1234567890 is 1.23 seconds, not 1234 seconds. Always divide by 1e9 before logging.

OpenAI-compatible endpoint

Ollama also exposes an OpenAI-compatible surface at /v1/chat/completions for drop-in compatibility with the OpenAI Python / TypeScript SDKs. Behavior is mostly compatible but not exact — see the serving track later. For native Ollama features (NDJSON streaming, structured outputs via format, the embed endpoint), use /api/....

Code

Hit every read-only endpoint·bash
# Daemon health
curl -s http://localhost:11434/api/version

# What's installed?
curl -s http://localhost:11434/api/tags | python3 -m json.tool

# What's loaded right now?
curl -s http://localhost:11434/api/ps | python3 -m json.tool

# Model details
curl -s http://localhost:11434/api/show -d '{"model":"qwen2.5:7b"}' | python3 -m json.tool

# One-shot non-streaming chat
curl -s http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role":"user","content":"Say hi in 5 words."}],
  "stream": false
}' | python3 -m json.tool

External links

Exercise

Hit each of the three read-only endpoints (/api/version, /api/tags, /api/ps) with curl and pretty-print the JSON. Then send one non-streaming /api/chat request and identify which fields are durations (in ns) — log each as seconds.

Progress

Progress is local-only — sign in to sync across devices.
← 🦙 Ollama RuntimeQuiz · 5 questionsNext →POST /api/chat — The Conversational Endpoint
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.