API client and types

The api/ package is the public Go client for Ollama. It's published as part of the same module and used by the CLI, by the launcher, and by external Go programs.

Purpose

Provide a typed Go interface for everything the daemon exposes. The same struct definitions (api/types.go) are the contract for the HTTP API, so adding a field means adding it once and seeing it both server-side and client-side.

Key abstractions

Symbol	Location	Purpose
Client	api/client.go	The HTTP client with one method per endpoint.
ClientFromEnvironment	api/client.go	Build a client from OLLAMA_HOST and friends.
Request types: GenerateRequest, ChatRequest, EmbedRequest, EmbeddingsRequest, CreateRequest, PullRequest, PushRequest, CopyRequest, DeleteRequest, ShowRequest, ListRequest, WhoamiRequest, SignoutRequest	api/types.go	One per /api/... endpoint.
Response types: GenerateResponse, ChatResponse, EmbedResponse, EmbeddingsResponse, ShowResponse, ListResponse, ProcessResponse, WhoamiResponse, …	api/types.go	Mirror the request types.
Message, ToolCall, Tool, Options	api/types.go	Building blocks.
Duration	api/types.go	JSON-friendly duration wrapper.

How it works

client, err := api.ClientFromEnvironment()
// or:
client, err := api.NewClient(myURL, myHTTPClient)

req := &api.ChatRequest{
    Model: "gemma3",
    Messages: []api.Message{{Role: "user", Content: "hello"}},
    Stream:   ptr(true),
}
err = client.Chat(ctx, req, func(resp api.ChatResponse) error {
    fmt.Print(resp.Message.Content)
    return nil
})

The client uses NDJSON streaming for Generate, Chat, Pull, Push, and Create; everything else returns single JSON.

Type sharing

Because the daemon imports the same api package as the client, the request/response types are unified. Any non-additive change to a field breaks both server and client at compile time, which is exactly what CONTRIBUTING.md asks for.

A TypeScript port of these types is generated from a test in api/types_typescript_test.go, keeping JS-side users in lockstep without manual translation.

Examples

api/examples/ contains small runnable examples:

• chat/
• generate/
• pull-progress/
• multimodal/

Integration points

• The CLI imports the client through cmd/cmd.go.
• The launcher's helpers in cmd/launch/ build a Client for cloud-state checks (cloudStatusDisabled, whoami, pull).
• External tools that don't want to write HTTP boilerplate can vendor github.com/ollama/ollama/api and use it directly.

Entry points for modification

• New endpoint → add the request/response types in api/types.go and the helper method on Client.
• Stream shape change → update both the client decoder and the server-side gin streaming code in server/routes.go.

Key source files

File	Purpose
api/client.go	The HTTP client.
api/types.go	All shared request/response types.
api/types_typescript_test.go	TypeScript codegen for these types.
api/examples/	Runnable usage examples.