# Reference documentation (API ground truth)

This `docs/` directory contains the official Ollama API specification and
documentation, snapshotted from the upstream repos on **2026-09-18** (previous
snapshot: 2026-09-13; the intervening upstream changes were local-server
model-lifecycle only — `/api/blobs/{digest}` and `CreateRequest` GGUF-import
fields — plus repositioning of the cloud docs toward direct API-key access).
It is
the source of ground truth for every endpoint, parameter, and response shape
this extension uses — and it is advertised to the agent itself: the
self-awareness guidelines in every chat point here, so a virgin session can
answer "what can my cloud API do?" by reading instead of guessing.

| File | Contents |
|---|---|
| [`openapi.yaml`](./openapi.yaml) | The official OpenAPI 3.1 spec (docs.ollama.com/openapi.yaml) — every local-server endpoint and schema |
| [`api.md`](./api.md) | The full Ollama HTTP API reference (generate, chat, embed, tags, ps, show, create, copy, pull, push, delete, version) |
| [`api/introduction.mdx`](./api/introduction.mdx) | API surface overview |
| [`api/authentication.mdx`](./api/authentication.mdx) | API key auth (bearer, env, config) |
| [`api/errors.mdx`](./api/errors.mdx) | Error codes and handling |
| [`api/openai-compatibility.mdx`](./api/openai-compatibility.mdx) | The OpenAI-compatible surface at `/v1` — what pi's provider drives |
| [`api/anthropic-compatibility.mdx`](./api/anthropic-compatibility.mdx) | The Anthropic-compatible surface |
| [`api/streaming.mdx`](./api/streaming.mdx) | Streaming responses |
| [`api/usage.mdx`](./api/usage.mdx) | Usage reporting (prompt/completion token counts) |
| [`capabilities/web-search.mdx`](./capabilities/web-search.mdx) | **The cloud web search/fetch API** — governs this extension's `ollama_web_search` / `ollama_web_fetch` tools |
| [`capabilities/thinking.mdx`](./capabilities/thinking.mdx) | Thinking levels (`think`: low/medium/high/max) |
| [`capabilities/tool-calling.mdx`](./capabilities/tool-calling.mdx) | Tool calling formats |
| [`capabilities/structured-outputs.mdx`](./capabilities/structured-outputs.mdx) | JSON/schema-structured outputs |
| [`capabilities/vision.mdx`](./capabilities/vision.mdx) | Image input |
| [`capabilities/embeddings.mdx`](./capabilities/embeddings.mdx) | Embeddings API |
| [`capabilities/streaming.mdx`](./capabilities/streaming.mdx) | Capability-level streaming notes |
| [`cloud.mdx`](./cloud.mdx) | Ollama Cloud overview (plans, retirement policy) |
| [`integrations/pi.mdx`](./integrations/pi.mdx) | Ollama's official `pi` integration docs |
| [`behavior.md`](./behavior.md) | **Empirically confirmed cloud behavior** — what was live-probed, on which date, including the undocumented `/api/usage` shape history and which openapi.yaml endpoints exist on the cloud |

## Re-sync with upstream

When Ollama updates, re-snapshot with:

```bash
git clone --depth 1 --filter=blob:none --sparse https://github.com/ollama/ollama /tmp/ollama \
  && cd /tmp/ollama && git sparse-checkout set docs \
  && cp docs/openapi.yaml docs/api.md docs/cloud.mdx <extension-dir>/docs/ \
  && cp docs/api/*.mdx <extension-dir>/docs/api/ \
  && cp docs/capabilities/*.mdx <extension-dir>/docs/capabilities/ \
  && cp docs/integrations/pi.mdx <extension-dir>/docs/integrations/
```

Since extension v1.1.0 the interactive path does this for you: `/ollama-setup` →
Spec freshness → **Re-sync** downloads all 18 upstream files into `docs/`
(all-or-nothing, `README.md` and `behavior.md` — this extension's own record —
are never touched) and re-arms the freshness check automatically. The manual
clone-and-copy above remains useful for scripted updates.

The official rendered docs live at https://docs.ollama.com; the OpenAPI spec at
https://docs.ollama.com/openapi.yaml.