The API docs, in plain language
The official API docs are written for engineers. This page explains what each endpoint does and when you need it, in ordinary language. The authoritative source is api-docs.deepseek.com.
Why this page exists.
The official docs assume you know HTTP, JSON, tokens and streaming. Most people just want to
know "I'm building a support bot — which endpoint do I call". This answers that, without
restating the reference.
Six endpoints, explained
Chat completion
POST /chat/completionsThe one you will use most. Send a list of messages, get the next one back. Chatbots, support, Q&A all use this.
Most applications need only this endpoint.
Text completion
POST /completionsGive it a prefix, it continues. Code completion (FIM: fill in the middle) uses this, because it can fill a gap instead of writing from scratch.
Only needed for IDE completion plugins.
List models
GET /modelsReturns currently available model names. Hardcoding model names goes stale — fetch this at startup.
Run this first when debugging.
Balance
GET /user/balanceReturns account balance. Good for low-balance alerts.
Notify below a threshold so you do not go dark at night.
File upload
POST /filesUpload once, get an id, reference the id instead of resending content.
Useful when reusing the same long document.
Prefix completion
POST /beta/chat/completionsForce the model to continue from a given prefix. Useful for code skeletons and JSON continuation.
Beta endpoint — behaviour may change.
Minimal working example
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "hello"}]
}'
Four common misunderstandings
| Assumption | Reality |
|---|---|
| "I must pin a specific model version" | Use deepseek-chat / deepseek-reasoner; the alias points at the current version |
| "Streaming costs more" | Same price. Streaming only shows tokens sooner |
| "Long context costs more" | You pay per token used, not per limit |
| "Thinking mode is always better" | Slower and pricier; simple tasks do not need it |