openapi: 3.1.0
info:
  title: Ollama Blobs Chat Completions 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 Completions
  description: Generate chat completions using the OpenAI-compatible chat endpoint with multi-turn conversation support.
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Ollama Create chat completion
      description: Creates a model response for the given chat conversation. Supports streaming, JSON mode, structured output, vision, and tool calling. Compatible with the OpenAI Chat Completions API format.
      tags:
      - Chat Completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatCompletionStreamResponse'
        '400':
          description: Bad Request
        '404':
          description: Model not found
components:
  schemas:
    ChatCompletionRequest:
      type: object
      description: Request body for creating a chat completion in OpenAI-compatible format.
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: The model to use for chat completion.
        messages:
          type: array
          description: A list of messages comprising the conversation so far.
          items:
            $ref: '#/components/schemas/ChatCompletionMessage'
        temperature:
          type: number
          description: Sampling temperature between 0 and 2. Higher values make output more random.
          minimum: 0.0
          maximum: 2.0
        top_p:
          type: number
          description: Nucleus sampling parameter. Considers tokens with top_p probability mass.
          minimum: 0.0
          maximum: 1.0
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate in the response.
        frequency_penalty:
          type: number
          description: Penalty for token frequency to reduce repetition.
          minimum: -2.0
          maximum: 2.0
        presence_penalty:
          type: number
          description: Penalty for token presence to encourage topic diversity.
          minimum: -2.0
          maximum: 2.0
        seed:
          type: integer
          description: Random seed for deterministic generation.
        stop:
          description: Sequences where the API will stop generating further tokens.
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        stream:
          type: boolean
          description: If true, partial message deltas are sent as server-sent events.
          default: false
        stream_options:
          type: object
          description: Options for streaming responses.
          properties:
            include_usage:
              type: boolean
              description: If true, includes usage information in the stream.
        response_format:
          type: object
          description: Specifies the format of the response. Use type json_object for JSON mode or json_schema for structured output.
          properties:
            type:
              type: string
              description: The response format type.
              enum:
              - text
              - json_object
              - json_schema
            json_schema:
              type: object
              description: The JSON Schema for structured output.
              additionalProperties: true
        tools:
          type: array
          description: A list of tools the model may call.
          items:
            $ref: '#/components/schemas/OpenAIToolDefinition'
    OpenAIToolCall:
      type: object
      description: A tool call generated by the model.
      properties:
        id:
          type: string
          description: A unique identifier for the tool call.
        type:
          type: string
          description: The type of tool call.
          enum:
          - function
        function:
          type: object
          description: The function call details.
          properties:
            name:
              type: string
              description: The name of the function to call.
            arguments:
              type: string
              description: The arguments to pass to the function as a JSON string.
    ChatCompletionResponse:
      type: object
      description: Response object from a chat completion request.
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion.
        object:
          type: string
          description: The object type, always chat.completion.
          const: chat.completion
        created:
          type: integer
          description: Unix timestamp of when the completion was created.
        model:
          type: string
          description: The model used for the completion.
        choices:
          type: array
          description: A list of chat completion choices.
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/UsageStats'
    ChatCompletionMessage:
      type: object
      description: A message in the chat conversation.
      required:
      - role
      properties:
        role:
          type: string
          description: The role of the message author.
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          description: The content of the message. Can be a string or an array of content parts for multimodal input.
          oneOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/ContentPart'
        name:
          type: string
          description: An optional name for the participant.
        tool_calls:
          type: array
          description: Tool calls generated by the model.
          items:
            $ref: '#/components/schemas/OpenAIToolCall'
        tool_call_id:
          type: string
          description: Tool call that this message is responding to.
    ContentPart:
      type: object
      description: A content part within a multimodal message.
      required:
      - type
      properties:
        type:
          type: string
          description: The type of content part.
          enum:
          - text
          - image_url
        text:
          type: string
          description: The text content when type is text.
        image_url:
          type: object
          description: The image URL or base64 data when type is image_url.
          properties:
            url:
              type: string
              description: URL of the image or a base64-encoded data URI.
    UsageStats:
      type: object
      description: Token usage statistics for the request.
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the prompt.
        completion_tokens:
          type: integer
          description: Number of tokens in the generated completion.
        total_tokens:
          type: integer
          description: Total number of tokens used in the request.
    OpenAIToolDefinition:
      type: object
      description: A tool definition in OpenAI-compatible format.
      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.
          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: The function parameters as a JSON Schema object.
              additionalProperties: true
    ChatCompletionStreamResponse:
      type: object
      description: A streaming chat completion chunk.
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion.
        object:
          type: string
          description: The object type, always chat.completion.chunk.
          const: chat.completion.chunk
        created:
          type: integer
          description: Unix timestamp of when the chunk was created.
        model:
          type: string
          description: The model used for the completion.
        choices:
          type: array
          description: A list of chat completion chunk choices.
          items:
            type: object
            properties:
              index:
                type: integer
                description: The index of the choice.
              delta:
                type: object
                description: The delta content for this chunk.
                properties:
                  role:
                    type: string
                    description: The role of the author.
                  content:
                    type: string
                    description: The content delta.
                  tool_calls:
                    type: array
                    description: Tool call deltas.
                    items:
                      $ref: '#/components/schemas/OpenAIToolCall'
              finish_reason:
                type:
                - string
                - 'null'
                description: The finish reason, if applicable.
    ChatCompletionChoice:
      type: object
      description: A single chat completion choice.
      properties:
        index:
          type: integer
          description: The index of the choice in the list.
        message:
          $ref: '#/components/schemas/ChatCompletionMessage'
        finish_reason:
          type: string
          description: The reason the model stopped generating tokens.
          enum:
          - stop
          - length
          - tool_calls
externalDocs:
  description: Ollama API Documentation
  url: https://docs.ollama.com/api/introduction