openapi: 3.1.0
info:
  title: Ollama Blobs Chat API
  description: Ollama provides a REST API for running and managing large language models locally. The API supports text generation, chat completions, embeddings, model management, and streaming responses. It serves as the primary interface for interacting with models running on the Ollama inference engine at localhost:11434.
  version: 0.1.0
  contact:
    name: Ollama Team
    url: https://ollama.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://ollama.com/terms
servers:
- url: http://localhost:11434
  description: Local Ollama Server
tags:
- name: Chat
  description: Generate chat completions with multi-turn conversation support.
paths:
  /api/chat:
    post:
      operationId: generateChatCompletion
      summary: Ollama Generate a chat completion
      description: Generate the next message in a chat with a provided model. This is a streaming endpoint that returns a sequence of JSON objects by default. Supports multi-turn conversations, tool calling, vision input, and structured output.
      tags:
      - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Successful chat response. Returns a stream of JSON objects when streaming is enabled, or a single JSON object when disabled.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ChatResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Logprob:
      type: object
      description: Log probability information for a generated token.
      properties:
        token:
          type: string
          description: The token text.
        logprob:
          type: number
          description: The log probability of the token.
        bytes:
          type: array
          description: The byte representation of the token.
          items:
            type: integer
        top_logprobs:
          type: array
          description: The most likely alternative tokens and their log probabilities at this position.
          items:
            type: object
            properties:
              token:
                type: string
                description: The alternative token text.
              logprob:
                type: number
                description: The log probability of the alternative token.
              bytes:
                type: array
                description: The byte representation of the alternative token.
                items:
                  type: integer
    ChatRequest:
      type: object
      description: Request body for generating a chat completion from a conversation.
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: The name of the model to use for chat completion.
        messages:
          type: array
          description: The messages of the chat conversation. Each message has a role and content, with optional images and tool calls.
          items:
            $ref: '#/components/schemas/ChatMessage'
        tools:
          type: array
          description: A list of tool definitions that the model may call during the conversation for function calling.
          items:
            $ref: '#/components/schemas/ToolDefinition'
        format:
          description: The format to return a response in. Accepts the string json for simple JSON mode, or a JSON Schema object for structured output.
          oneOf:
          - type: string
            enum:
            - json
          - type: object
        stream:
          type: boolean
          description: When true, returns a stream of partial responses as newline-delimited JSON. When false, returns a single response object.
          default: true
        think:
          description: When true, returns separate thinking output in addition to the generated content. Can also be set to a string value to control thinking verbosity.
          oneOf:
          - type: boolean
          - type: string
            enum:
            - high
            - medium
            - low
        keep_alive:
          description: How long the model stays loaded in memory after the request.
          oneOf:
          - type: string
          - type: number
        options:
          $ref: '#/components/schemas/ModelOptions'
        logprobs:
          type: boolean
          description: Whether to return log probabilities of the output tokens.
        top_logprobs:
          type: integer
          description: Number of most likely tokens to return at each token position.
          minimum: 0
    ChatMessage:
      type: object
      description: A message in a chat conversation, containing a role, content, and optional images or tool calls.
      required:
      - role
      - content
      properties:
        role:
          type: string
          description: The role of the message sender.
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          type: string
          description: The text content of the message.
        thinking:
          type: string
          description: The thinking content when extended thinking is enabled.
        images:
          type: array
          description: A list of base64-encoded images attached to the message for multimodal models.
          items:
            type: string
            format: byte
        tool_calls:
          type: array
          description: Tool calls requested by the assistant for function calling.
          items:
            $ref: '#/components/schemas/ToolCall'
    ErrorResponse:
      type: object
      description: An error response returned when a request fails.
      properties:
        error:
          type: string
          description: A human-readable error message describing the problem.
    ChatResponse:
      type: object
      description: Response object from a chat completion request. When streaming, partial objects are returned until done is true.
      properties:
        model:
          type: string
          description: The model used to generate the chat response.
        created_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the response was created.
        message:
          $ref: '#/components/schemas/ChatMessage'
        done:
          type: boolean
          description: Indicates whether the chat response has finished.
        done_reason:
          type: string
          description: The reason the generation stopped.
        total_duration:
          type: integer
          description: Total time spent generating the response in nanoseconds.
        load_duration:
          type: integer
          description: Time spent loading the model in nanoseconds.
        prompt_eval_count:
          type: integer
          description: Number of tokens in the prompt that were evaluated.
        prompt_eval_duration:
          type: integer
          description: Time spent evaluating the prompt in nanoseconds.
        eval_count:
          type: integer
          description: Number of tokens generated in the response.
        eval_duration:
          type: integer
          description: Time spent generating output tokens in nanoseconds.
        logprobs:
          type: array
          description: Log probability information for generated tokens.
          items:
            $ref: '#/components/schemas/Logprob'
    ToolDefinition:
      type: object
      description: A definition of a tool that the model may call during conversation for function calling.
      required:
      - type
      - function
      properties:
        type:
          type: string
          description: The type of tool. Currently only function is supported.
          enum:
          - function
        function:
          type: object
          description: The function definition including name, description, and parameter schema.
          required:
          - name
          properties:
            name:
              type: string
              description: The name of the function.
            description:
              type: string
              description: A description of what the function does.
            parameters:
              type: object
              description: A JSON Schema object defining the function parameters.
              additionalProperties: true
    ModelOptions:
      type: object
      description: Runtime options that control text generation behavior. These override the model's default parameter values.
      properties:
        seed:
          type: integer
          description: Random seed for reproducible generation. Set to a specific value for deterministic output.
        temperature:
          type: number
          description: Controls the creativity of responses. Higher values produce more varied output. Range 0.0 to 2.0.
          minimum: 0.0
          maximum: 2.0
        top_k:
          type: integer
          description: Limits token selection to the top K most probable tokens. Lower values produce more focused output.
          minimum: 0
        top_p:
          type: number
          description: Nucleus sampling probability cutoff. Limits selection to the smallest set of tokens whose cumulative probability exceeds this value.
          minimum: 0.0
          maximum: 1.0
        min_p:
          type: number
          description: Minimum probability threshold relative to the most likely token. Tokens below this threshold are filtered out.
          minimum: 0.0
          maximum: 1.0
        stop:
          type: array
          description: A list of stop sequences. Generation halts when any of these strings are produced.
          items:
            type: string
        num_ctx:
          type: integer
          description: The maximum context window size in tokens.
        num_predict:
          type: integer
          description: The maximum number of tokens to generate in the response.
        repeat_penalty:
          type: number
          description: Penalty applied to repeated tokens to reduce repetition.
        repeat_last_n:
          type: integer
          description: Number of recent tokens to consider for repeat penalty.
        tfs_z:
          type: number
          description: Tail-free sampling parameter. Higher values reduce the impact of less probable tokens.
        mirostat:
          type: integer
          description: Enable Mirostat sampling for perplexity control. 0 is disabled, 1 uses Mirostat, 2 uses Mirostat 2.0.
          enum:
          - 0
          - 1
          - 2
        mirostat_tau:
          type: number
          description: Target entropy for Mirostat sampling.
        mirostat_eta:
          type: number
          description: Learning rate for Mirostat sampling.
    ToolCall:
      type: object
      description: A tool call requested by the model during function calling.
      properties:
        function:
          type: object
          description: The function to call with its name and arguments.
          properties:
            name:
              type: string
              description: The name of the function to call.
            arguments:
              type: object
              description: The arguments to pass to the function as key-value pairs.
              additionalProperties: true
externalDocs:
  description: Ollama API Documentation
  url: https://docs.ollama.com/api/introduction