Ollama REST API: Complete Endpoint Reference for Chat, Generate, Embeddings, and Model Management

TL;DR — Ollama REST API: complete endpoint reference. Ollama GitHub: "11 endpoints: /api/generate, /api/chat, /api/create, /api/tags, /api/show, /api/copy, /api/delete, /api/pull, /api/push, /api/embeddings, /api/ps. Streaming by default, disable with stream: false. Options: temperature, format (json/schema), keep_alive (5m default)." ML Journey: "Eleven native + three OpenAI-compatible /v1 endpoints. Streaming: each line is JSON, final chunk has stats (total_duration, eval_count, tokens/sec = eval_count / (eval_duration / 1e9)). API stable since release — no breaking changes." Ollama Docs: "POST /api/chat — model, messages, format, options, stream, keep_alive, think (reasoning models)." Learn more with Ollama tutorial, VPS setup, model selection, and function calling.

ML Journey provides the overview: "All endpoints at a glance: GET /api/tags to list models, POST /api/chat for chat with message history, POST /api/generate for raw text completion, POST /api/embeddings for embeddings, POST /api/pull to download a model, DELETE /api/delete to remove one, POST /api/copy to duplicate, GET /api/ps to see running models, POST /api/show to inspect a model's Modelfile and metadata, POST /api/create to create a model from a Modelfile, and GET / for a simple health check. These eleven endpoints cover everything you need to build, manage, and monitor a complete local LLM application stack on top of Ollama."

API Architecture

Endpoint Reference

Options Reference

Implementation

from dataclasses import dataclass
from typing import Optional
from enum import Enum

class Endpoint(Enum):
    CHAT = "/api/chat"
    GENERATE = "/api/generate"
    EMBEDDINGS = "/api/embeddings"
    TAGS = "/api/tags"
    PS = "/api/ps"
    SHOW = "/api/show"
    PULL = "/api/pull"
    DELETE = "/api/delete"
    COPY = "/api/copy"
    CREATE = "/api/create"

@dataclass
class OllamaRESTAPIGuide:
    """Ollama REST API implementation guide."""

    def get_chat_endpoint(self) -> str:
        """POST /api/chat examples."""
        return (
            "# === CHAT (streaming) ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/chat -d '{\n"
            "    \"model\": \"llama3.2\",\n"
            "    \"messages\": [\n"
            "      {\"role\": \"system\",\n"
            "       \"content\": \"You are\"\n"
            "        \" helpful.\"},\n"
            "      {\"role\": \"user\",\n"
            "       \"content\": \"Hello!\"}\n"
            "    ]\n"
            "  }'\n"
            "\n"
            "# Response (each line):\n"
            "# {\"model\":\"llama3.2\",\n"
            "#  \"created_at\":\"2026-...\",\n"
            "#  \"message\":{\"role\":\n"
            "#    \"assistant\",\"content\":\n"
            "#    \"Hello\"},\"done\":false}\n"
            "# {\"model\":\"llama3.2\",\n"
            "#  \"message\":{\"content\":\n"
            "#    \" there\"},\"done\":false}\n"
            "# {\"done\":true,\n"
            "#  \"total_duration\":2341000000,\n"
            "#  \"load_duration\":123000000,\n"
            "#  \"prompt_eval_count\":12,\n"
            "#  \"eval_count\":45,\n"
            "#  \"eval_duration\":1980000000}\n"
            "\n"
            "# === CHAT (non-streaming) ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/chat -d '{\n"
            "    \"model\": \"llama3.2\",\n"
            "    \"messages\": [\n"
            "      {\"role\": \"user\",\n"
            "       \"content\": \"Hello!\"}\n"
            "    ],\n"
            "    \"stream\": false\n"
            "  }'\n"
            "\n"
            "# === CHAT with options ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/chat -d '{\n"
            "    \"model\": \"llama3.2\",\n"
            "    \"messages\": [\n"
            "      {\"role\": \"user\",\n"
            "       \"content\": \"Write code\"}\n"
            "    ],\n"
            "    \"options\": {\n"
            "      \"temperature\": 0.7,\n"
            "      \"top_p\": 0.9,\n"
            "      \"num_ctx\": 4096,\n"
            "      \"num_predict\": 500\n"
            "    },\n"
            "    \"keep_alive\": \"10m\"\n"
            "  }'\n"
            "\n"
            "# === CHAT with JSON format ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/chat -d '{\n"
            "    \"model\": \"llama3.2\",\n"
            "    \"messages\": [\n"
            "      {\"role\": \"user\",\n"
            "       \"content\": \"List 3\"\n"
            "        \" fruits as JSON\"}\n"
            "    ],\n"
            "    \"format\": \"json\",\n"
            "    \"stream\": false\n"
            "  }'\n"
            "\n"
            "# === CHAT with images ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/chat -d '{\n"
            "    \"model\": \"llama3.2-vision\",\n"
            "    \"messages\": [\n"
            "      {\"role\": \"user\",\n"
            "       \"content\": \"What is\"\n"
            "        \" in this image?\",\n"
            "       \"images\": [\n"
            "         \"iVBORw0KGgo...\"]\n"
            "      }\n"
            "    ]\n"
            "  }'\n"
            "\n"
            "# === CHAT with reasoning ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/chat -d '{\n"
            "    \"model\": \"deepseek-r1\",\n"
            "    \"messages\": [\n"
            "      {\"role\": \"user\",\n"
            "       \"content\": \"What is\"\n"
            "        \" 1+1?\"}\n"
            "    ],\n"
            "    \"think\": \"low\"\n"
            "  }'"
        )

    def get_generate_endpoint(self) -> str:
        """POST /api/generate examples."""
        return (
            "# === GENERATE (streaming) ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/generate -d '{\n"
            "    \"model\": \"llama3.2\",\n"
            "    \"prompt\": \"Write a\"\n"
            "      \" Python function\"\n"
            "  }'\n"
            "\n"
            "# === GENERATE (non-streaming) ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/generate -d '{\n"
            "    \"model\": \"llama3.2\",\n"
            "    \"prompt\": \"Hello world\",\n"
            "    \"stream\": false\n"
            "  }'\n"
            "\n"
            "# === GENERATE with raw ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/generate -d '{\n"
            "    \"model\": \"llama3.2\",\n"
            "    \"prompt\": \"<|system|>You\"\n"
            "      \" are helpful<|end|>\n"
            "      <|user|>Hi<|end|>\n"
            "      <|assistant|>\",\n"
            "    \"raw\": true,\n"
            "    \"stream\": false\n"
            "  }'\n"
            "\n"
            "# Response includes:\n"
            "# model, created_at, response,\n"
            "# done, total_duration,\n"
            "# load_duration,\n"
            "# prompt_eval_count,\n"
            "# eval_count, eval_duration"
        )

    def get_embeddings_endpoint(self) -> str:
        """POST /api/embeddings examples."""
        return (
            "# === EMBEDDINGS ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/embeddings -d '{\n"
            "    \"model\": \"nomic-embed-text\",\n"
            "    \"prompt\": \"Python is\"\n"
            "      \" great for AI\"\n"
            "  }'\n"
            "\n"
            "# Response:\n"
            "# {\n"
            "#   \"model\": \"nomic-embed-text\",\n"
            "#   \"embeddings\": [[\n"
            "#     0.010071029,\n"
            "#     -0.0017594862,\n"
            "#     0.05007221,\n"
            "#     ...\n"
            "#   ]],\n"
            "#   \"total_duration\": 14143917,\n"
            "#   \"load_duration\": 1019500,\n"
            "#   \"prompt_eval_count\": 8\n"
            "# }\n"
            "\n"
            "# === Python with requests ===\n"
            "import requests\n"
            "\n"
            "resp = requests.post(\n"
            "    'http://localhost:11434'\n"
            "    '/api/embeddings',\n"
            "    json={\n"
            "        'model':\n"
            "          'nomic-embed-text',\n"
            "        'prompt': 'Embed this'\n"
            "    }\n"
            ")\n"
            "embedding = resp.json()\n"
            "  ['embeddings'][0]\n"
            "print(len(embedding))\n"
            "  # e.g., 768 dimensions"
        )

    def get_management_endpoints(self) -> str:
        """Model management endpoints."""
        return (
            "# === LIST MODELS ===\n"
            "curl http://localhost:11434/api/tags\n"
            "# {\"models\":[{\"name\":\n"
            "#   \"llama3.2\",\"model\":\n"
            "#   \"llama3.2\",\"size\":\n"
            "#   2000000000,\"details\":{\n"
            "#   \"format\":\"gguf\",\n"
            "#   \"family\":\"llama\",\n"
            "#   \"parameter_size\":\"3B\",\n"
            "#   \"quantization_level\":\n"
            "#     \"Q4_K_M\"}}]}\n"
            "\n"
            "# === LIST RUNNING MODELS ===\n"
            "curl http://localhost:11434/api/ps\n"
            "# Models currently loaded\n"
            "# in memory\n"
            "\n"
            "# === SHOW MODEL ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/show -d '{\n"
            "    \"model\": \"llama3.2\"\n"
            "  }'\n"
            "# Returns: modelfile,\n"
            "# parameters, template,\n"
            "# details, model_info\n"
            "\n"
            "# === PULL MODEL ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/pull -d '{\n"
            "    \"model\": \"mistral\"\n"
            "  }'\n"
            "# Streaming progress:\n"
            "# {\"status\":\"downloading\",\n"
            "#  \"digest\":\"sha256:...\",\n"
            "#  \"total\":4100000000,\n"
            "#  \"completed\":1234567890}\n"
            "\n"
            "# === DELETE MODEL ===\n"
            "curl -X DELETE \\\n"
            "  http://localhost:11434\\\n"
            "  /api/delete -d '{\n"
            "    \"model\": \"mistral\"\n"
            "  }'\n"
            "\n"
            "# === COPY MODEL ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/copy -d '{\n"
            "    \"source\": \"llama3.2\",\n"
            "    \"destination\":\n"
            "      \"my-llama\"\n"
            "  }'\n"
            "\n"
            "# === CREATE MODEL ===\n"
            "curl http://localhost:11434\\\n"
            "  /api/create -d '{\n"
            "    \"model\": \"my-model\",\n"
            "    \"modelfile\":\n"
            "      \"FROM llama3.2\\n\"\n"
            "      \"SYSTEM You are a\"\n"
            "      \" coding assistant\"\n"
            "  }'\n"
            "\n"
            "# === HEALTH CHECK ===\n"
            "curl http://localhost:11434/\n"
            "# \"Ollama is running\""
        )

    def get_python_client(self) -> str:
        """Python client for all endpoints."""
        return (
            "import requests\n"
            "import json\n"
            "\n"
            "BASE = 'http://localhost'\n"
            "  ':11434'\n"
            "\n"
            "class OllamaClient:\n"
            "    def __init__(self,\n"
            "        base_url=BASE):\n"
            "        self.base = base_url\n"
            "    \n"
            "    def chat(self, model,\n"
            "        messages, **opts):\n"
            "        '''Chat completion.'''\n"
            "        resp = requests.post(\n"
            "            f'{self.base}'\n"
            "            '/api/chat',\n"
            "            json={'model': model,\n"
            "              'messages': messages,\n"
            "              **opts}\n"
            "        )\n"
            "        return resp.json()\n"
            "    \n"
            "    def chat_stream(self,\n"
            "        model, messages):\n"
            "        '''Streaming chat.'''\n"
            "        resp = requests.post(\n"
            "            f'{self.base}'\n"
            "            '/api/chat',\n"
            "            json={'model': model,\n"
            "              'messages': messages},\n"
            "            stream=True\n"
            "        )\n"
            "        for line in resp:\n"
            "            chunk = json\n"
            "              .loads(line)\n"
            "            if chunk['done']:\n"
            "                yield chunk\n"
            "                break\n"
            "            yield chunk[\n"
            "              'message']['content']\n"
            "    \n"
            "    def generate(self, model,\n"
            "        prompt, **opts):\n"
            "        '''Raw completion.'''\n"
            "        resp = requests.post(\n"
            "            f'{self.base}'\n"
            "            '/api/generate',\n"
            "            json={'model': model,\n"
            "              'prompt': prompt,\n"
            "              **opts}\n"
            "        )\n"
            "        return resp.json()\n"
            "    \n"
            "    def embed(self, model,\n"
            "        prompt):\n"
            "        '''Generate embeddings.'''\n"
            "        resp = requests.post(\n"
            "            f'{self.base}'\n"
            "            '/api/embeddings',\n"
            "            json={'model': model,\n"
            "              'prompt': prompt}\n"
            "        )\n"
            "        return resp.json()\n"
            "          ['embeddings'][0]\n"
            "    \n"
            "    def list_models(self):\n"
            "        '''List all models.'''\n"
            "        resp = requests.get(\n"
            "            f'{self.base}'\n"
            "            '/api/tags')\n"
            "        return resp.json()\n"
            "          ['models']\n"
            "    \n"
            "    def pull(self, model):\n"
            "        '''Download model.'''\n"
            "        resp = requests.post(\n"
            "            f'{self.base}'\n"
            "            '/api/pull',\n"
            "            json={'model': model},\n"
            "            stream=True\n"
            "        )\n"
            "        for line in resp:\n"
            "            data = json\n"
            "              .loads(line)\n"
            "            if data.get('status')\n"
            "              == 'success':\n"
            "                return True\n"
            "        return True\n"
            "    \n"
            "    def delete(self, model):\n"
            "        '''Delete model.'''\n"
            "        requests.delete(\n"
            "            f'{self.base}'\n"
            "            '/api/delete',\n"
            "            json={'model': model}\n"
            "        )\n"
            "    \n"
            "    def show(self, model):\n"
            "        '''Model details.'''\n"
            "        resp = requests.post(\n"
            "            f'{self.base}'\n"
            "            '/api/show',\n"
            "            json={'model': model}\n"
            "        )\n"
            "        return resp.json()\n"
            "    \n"
            "    def running(self):\n"
            "        '''Running models.'''\n"
            "        resp = requests.get(\n"
            "            f'{self.base}'\n"
            "            '/api/ps')\n"
            "        return resp.json()\n"
            "          ['models']\n"
            "\n"
            "# Usage\n"
            "client = OllamaClient()\n"
            "result = client.chat(\n"
            "    'llama3.2',\n"
            "    [{'role': 'user',\n"
            "      'content': 'Hello!'}],\n"
            "    stream=False\n"
            ")\n"
            "print(result['message']\n"
            "      ['content'])"
        )

    def get_streaming_stats(self) -> dict:
        """Streaming response statistics."""
        return {
            "total_duration": (
                "Total time for request "
                "in nanoseconds. "
                "Includes load + eval."
            ),
            "load_duration": (
                "Time to load model "
                "into memory in "
                "nanoseconds."
            ),
            "prompt_eval_count": (
                "Number of input "
                "tokens (prompt). "
                "Measures input size."
            ),
            "eval_count": (
                "Number of output "
                "tokens generated. "
                "Measures response size."
            ),
            "eval_duration": (
                "Time for generation "
                "in nanoseconds. "
                "Use for tokens/sec."
            ),
            "tokens_per_second": (
                "eval_count / "
                "(eval_duration / 1e9). "
                "Key performance metric."
            ),
        }

Ollama REST API Checklist

• [ ] 11 native endpoints: /api/chat, /api/generate, /api/embeddings, /api/tags, /api/ps, /api/show, /api/pull, /api/delete, /api/copy, /api/create, /api/push
• [ ] 3 OpenAI-compatible endpoints: /v1/chat/completions, /v1/embeddings, /v1/models
• [ ] Health check: GET / returns "Ollama is running"
• [ ] POST /api/chat: chat completion with message history, streaming by default
• [ ] POST /api/chat parameters: model, messages, format, options, stream, keep_alive, think, system, template, raw
• [ ] POST /api/generate: raw text completion from prompt, streaming by default
• [ ] POST /api/generate parameters: model, prompt, format, options, stream, keep_alive, system, template, raw
• [ ] POST /api/embeddings: generate embedding vector, use nomic-embed-text for RAG
• [ ] GET /api/tags: list all local models with name, size, details (format, family, parameter_size, quantization_level)
• [ ] GET /api/ps: list models currently loaded in memory
• [ ] POST /api/show: show model details, Modelfile, parameters, template, model_info
• [ ] POST /api/pull: download model, streaming progress with status/digest/total/completed
• [ ] DELETE /api/delete: remove model and free disk space
• [ ] POST /api/copy: duplicate/rename model (source, destination)
• [ ] POST /api/create: create custom model from Modelfile string
• [ ] POST /api/push: push model to registry for sharing
• [ ] Streaming: default stream=true, each response line is JSON object
• [ ] Streaming: disable with stream=false for single response object
• [ ] Streaming: each chunk has {model, created_at, message: {role, content}, done: false}
• [ ] Streaming: final chunk has done: true with performance statistics
• [ ] Stats: total_duration, load_duration, prompt_eval_count, eval_count, eval_duration
• [ ] Tokens/sec: eval_count / (eval_duration / 1e9) — key performance metric
• [ ] Options: temperature (0-1), top_p (0.9), top_k (40), num_ctx (2048), seed, num_predict (-1)
• [ ] Options: stop (stop sequences), repeat_penalty (1.1)
• [ ] format: "json" for JSON mode, or JSON schema for structured output
• [ ] keep_alive: model memory retention after request (default "5m")
• [ ] think: "low"/"medium"/"high" for reasoning models (DeepSeek-R1, gpt-oss)
• [ ] system: override Modelfile system message
• [ ] template: override Modelfile prompt template
• [ ] raw: true for no formatting — full templated prompt
• [ ] Images: include base64-encoded images in messages for vision models
• [ ] API stable since initial release — core endpoints have no breaking changes
• [ ] Native API has additional capabilities vs OpenAI-compatible: streaming with full metadata, model loading/unloading, embedding generation, model inspection
• [ ] Use native /api/ for full control, OpenAI /v1/ for drop-in compatibility
• [ ] Python: use requests library or ollama Python SDK or OpenAI SDK with base_url
• [ ] Read Ollama tutorial for setup
• [ ] Read VPS setup for remote deployment
• [ ] Read model selection for choosing models
• [ ] Read function calling for tool use
• [ ] Test: /api/chat returns streaming response with incremental content
• [ ] Test: /api/chat with stream=false returns single JSON response
• [ ] Test: /api/generate returns raw text completion
• [ ] Test: /api/embeddings returns float array with correct dimensions
• [ ] Test: /api/tags lists all downloaded models
• [ ] Test: /api/pull downloads model with streaming progress
• [ ] Test: /api/delete removes model and frees disk
• [ ] Test: options (temperature, num_predict) affect output
• [ ] Test: format: "json" returns valid JSON
• [ ] Test: tokens/sec calculation from final chunk stats
• [ ] Document endpoint usage, options, streaming format, performance metrics

FAQ

What endpoints does the Ollama REST API provide?

Eleven native endpoints plus OpenAI-compatible /v1 endpoints. Ollama GitHub: "Endpoints: Generate a completion (/api/generate), Generate a chat completion (/api/chat), Create a Model (/api/create), List Local Models (/api/tags), Show Model Information (/api/show), Copy a Model (/api/copy), Delete a Model (/api/delete), Pull a Model (/api/pull), Push a Model (/api/push), Generate Embeddings (/api/embeddings), List Running Models (/api/ps), Version." ML Journey: "Eleven endpoints cover everything: GET /api/tags to list models, POST /api/chat for chat, POST /api/generate for raw completion, POST /api/embeddings for embeddings, POST /api/pull to download, DELETE /api/delete to remove, POST /api/copy to duplicate, GET /api/ps for running models, POST /api/show to inspect, POST /api/create to create from Modelfile, GET / for health check. Plus three OpenAI-compatible /v1 endpoints."

How does the Ollama /api/chat endpoint work?

POST /api/chat accepts model name, message history, and optional parameters. Streaming by default. Ollama GitHub: "Generate the next message in a chat with a provided model. This is a streaming endpoint, so there will be a series of responses. Streaming can be disabled using stream: false. The final response object will include statistics and additional data." Ollama Docs: "POST /api/chat — Generate the next chat message in a conversation. Parameters: model, messages, format (json or JSON schema), options (temperature etc), stream, keep_alive (default 5m), think (low/medium/high for reasoning models)." ML Journey: "The main inference endpoint. Accepts model name, message history, and optional parameters. Streaming response: each line is JSON object with message content. Final chunk (done: true) includes total_duration, load_duration, prompt_eval_count, eval_count, eval_duration."

How do you generate embeddings with Ollama?

POST /api/embeddings with model and prompt returns embedding vector. Ollama GitHub: "Generate Embeddings endpoint: POST /api/embeddings. Parameters: model, prompt. Returns embedding array." Ollama Docs OpenAPI: "POST /api/embeddings — generates embeddings from a model. Returns model name, embeddings array, total_duration, load_duration, prompt_eval_count." ML Journey: "POST /api/embeddings for embeddings. Use nomic-embed-text model for RAG pipelines. Returns float array representing text embedding." Usage: curl http://localhost:11434/api/embeddings -d '{"model":"nomic-embed-text","prompt":"Embed this text"}'. Returns: {"embedding":[0.010071,...],"total_duration":14143917,...}. Use for RAG, semantic search, clustering.

What options can you pass to Ollama API endpoints?

Both /api/chat and /api/generate accept an options object with model parameters. Ollama GitHub: "Options: additional model parameters listed in Modelfile documentation such as temperature. Format: json or JSON schema. System: system message (overrides Modelfile). Template: prompt template (overrides Modelfile). Stream: false for single response. Raw: true for no formatting. Keep_alive: how long model stays loaded (default 5m)." ML Journey: "Both inference endpoints accept options object: temperature, top_p, top_k, num_ctx (context window), seed, num_predict (max tokens), stop (stop sequences), repeat_penalty." Options: (1) temperature: randomness (0-1). (2) top_p: nucleus sampling. (3) top_k: top-k sampling. (4) num_ctx: context window size. (5) seed: reproducibility. (6) num_predict: max output tokens. (7) stop: stop sequences. (8) repeat_penalty: penalty for repetition. (9) format: json or JSON schema for structured output. (10) keep_alive: model memory retention.

How does streaming work in the Ollama REST API?

Streaming is default — each response line is a JSON object with incremental content. Ollama GitHub: "Certain endpoints stream responses as JSON objects. Streaming can be disabled by providing stream: false." ML Journey: "When streaming is enabled (default), each response line is a JSON object. For /api/chat: {\"model\":\"llama3.2\",\"created_at\":\"...\",\"message\":{\"role\":\"assistant\",\"content\":\"Hello\"},\"done\":false}. Final chunk (done: true) includes performance statistics: total_duration, load_duration, prompt_eval_count (input tokens), eval_count (output tokens), eval_duration. Calculate tokens per second: eval_count / (eval_duration / 1e9)." Streaming: (1) Default: stream=true, each line is JSON. (2) Disable: stream=false for single response. (3) Each chunk: message with incremental content, done=false. (4) Final chunk: done=true with stats. (5) Stats: total_duration, load_duration, prompt_eval_count, eval_count, eval_duration. (6) Tokens/sec: eval_count / (eval_duration / 1e9).

Want a self-hosted AI company brain that does all of this out of the box?
Book a demo →