openapi: 3.0.0
info:
  title: API Reference
  description: >
    # Introduction

    Jan API is compatible with the [OpenAI
    API](https://platform.openai.com/docs/api-reference).
version: 0.1.8
contact:
  name: Jan Discord
  url: https://discord.gg/7EcEz7MrvA
license:
  name: AGPLv3
  url: https://github.com/janhq/nitro/blob/main/LICENSE
servers:
  - url: /v1
tags:
  - name: Models
    description: List and describe the various models available in the API.
  - name: Chat
    description: >
      Given a list of messages comprising a conversation, the model will return
      a response.
  - name: Messages
    description: >
      Messages capture a conversation's content. This can include the content
      from LLM responses and other metadata from [chat
      completions](/specs/chats).
  - name: Threads
  - name: Assistants
    description: Configures and utilizes different AI assistants for varied tasks
x-tagGroups:
  - name: Endpoints
    tags:
      - Models
      - Chat
  - name: Chat
    tags:
      - Assistants
      - Messages
      - Threads
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      tags:
        - Chat
      summary: |
        Create chat completion
      description: >
        Creates a model response for the given chat conversation.  <a  href =
        "https://platform.openai.com/docs/api-reference/chat/create"> Equivalent
        to OpenAI's create chat completion. </a>
      requestBody:
        content:
          application/json:
            schema:
              $ref: specs/chat.yaml#/components/schemas/ChatCompletionRequest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: specs/chat.yaml#/components/schemas/ChatCompletionResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X 'POST' \
              'http://localhost:1337/v1/chat/completions' \
              -H 'accept: application/json' \
              -H 'Content-Type: application/json' \
              -d '{
                "messages": [
                  {
                    "content": "You are a helpful assistant.",
                    "role": "system"
                  },
                  {
                    "content": "Hello!",
                    "role": "user"
                  }
                ],
                "model": "tinyllama-1.1b",
                "stream": true,
                "max_tokens": 2048,
                "stop": [
                  "hello"
                ],
                "frequency_penalty": 0,
                "presence_penalty": 0,
                "temperature": 0.7,
                "top_p": 0.95
              }'
  /models:
    get:
      operationId: listModels
      tags:
        - Models
      summary: List models
      description: >
        Lists the currently available models, and provides basic information
        about each one such as the owner and availability.  <a  href =
        "https://platform.openai.com/docs/api-reference/models/list"> Equivalent
        to OpenAI's list model. </a>
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: specs/models.yaml#/components/schemas/ListModelsResponse
      x-codeSamples:
        - lang: cURL
          source: |-
            curl -X 'GET' \
              'http://localhost:1337/v1/models' \
              -H 'accept: application/json'
        - lang: JavaScript
          source: |-
            const response = await fetch('http://localhost:1337/v1/models', {
              method: 'GET',
              headers: {Accept: 'application/json'}
            });
            const data = await response.json();
        - lang: Python
          source: |-
            import requests

            url = 'http://localhost:1337/v1/models'
            headers = {'Accept': 'application/json'}
            response = requests.get(url, headers=headers)
            data = response.json()
        - lang: Node.js
          source: |-
            const fetch = require('node-fetch');

            const url = 'http://localhost:1337/v1/models';
            const options = {
              method: 'GET',
              headers: { Accept: 'application/json' }
            };

            fetch(url, options)
              .then(res => res.json())
              .then(json => console.log(json));
  /models/download/{model_id}:
    get:
      operationId: downloadModel
      tags:
        - Models
      summary: Download a specific model.
      description: |
        Download a model.
      parameters:
        - in: path
          name: model_id
          required: true
          schema:
            type: string
            example: mistral-ins-7b-q4
          description: |
            The ID of the model to use for this request.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: specs/models.yaml#/components/schemas/DownloadModelResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X 'GET' \
              'http://localhost:1337/v1/models/download/{model_id}' \
              -H 'accept: application/json'
  /models/{model_id}:
    get:
      operationId: retrieveModel
      tags:
        - Models
      summary: Retrieve model
      description: >
        Get a model instance, providing basic information about the model such
        as the owner and permissioning.  <a  href =
        "https://platform.openai.com/docs/api-reference/models/retrieve">
        Equivalent to OpenAI's retrieve model. </a>
      parameters:
        - in: path
          name: model_id
          required: true
          schema:
            type: string
            example: mistral-ins-7b-q4
          description: |
            The ID of the model to use for this request.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: specs/models.yaml#/components/schemas/GetModelResponse
      x-codeSamples:
        - lang: cURL
          source: |-
            curl -X 'GET' \  
              'http://localhost:1337/v1/models/{model_id}' \  
              -H 'accept: application/json'
        - lang: JavaScript
          source: |-
            const fetch = require('node-fetch');

            const modelId = 'mistral-ins-7b-q4';

            fetch(`http://localhost:1337/v1/models/${modelId}`, {
              method: 'GET',
              headers: {'accept': 'application/json'}
            })
            .then(res => res.json())
            .then(json => console.log(json));
        - lang: Node.js
          source: |-
            const fetch = require('node-fetch');

            const modelId = 'mistral-ins-7b-q4';

            fetch(`http://localhost:1337/v1/models/${modelId}`, {
              method: 'GET',
              headers: {'accept': 'application/json'}
            })
            .then(res => res.json())
            .then(json => console.log(json));
        - lang: Python
          source: >-
            import requests


            model_id = 'mistral-ins-7b-q4'


            response =
            requests.get(f'http://localhost:1337/v1/models/{model_id}',
            headers={'accept': 'application/json'})

            print(response.json())
    delete:
      operationId: deleteModel
      tags:
        - Models
      summary: Delete model
      description: >
        Delete a model. <a  href =
        "https://platform.openai.com/docs/api-reference/models/delete">
        Equivalent to OpenAI's delete model. </a>
      parameters:
        - in: path
          name: model_id
          required: true
          schema:
            type: string
            example: mistral-ins-7b-q4
          description: |
            The model id to delete
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: specs/models.yaml#/components/schemas/DeleteModelResponse
      x-codeSamples:
        - lang: cURL
          source: |-
            curl -X 'DELETE' \
              'http://localhost:1337/v1/models/{model_id}' \
              -H 'accept: application/json'
        - lang: JavaScript
          source: |-
            const fetch = require('node-fetch');

            const modelId = 'mistral-ins-7b-q4';

            fetch(`http://localhost:1337/v1/models/${modelId}`, {
              method: 'DELETE',
              headers: { 'accept': 'application/json' }
            })
              .then(res => res.json())
              .then(json => console.log(json));
        - lang: Node.js
          source: |-
            const fetch = require('node-fetch');

            const modelId = 'mistral-ins-7b-q4';

            fetch(`http://localhost:1337/v1/models/${modelId}`, {
              method: 'DELETE',
              headers: { 'accept': 'application/json' }
            })
              .then(res => res.json())
              .then(json => console.log(json));
        - lang: Python
          source: >-
            import requests


            model_id = 'mistral-ins-7b-q4'


            response =
            requests.delete(f'http://localhost:1337/v1/models/{model_id}',
            headers={'accept': 'application/json'})
  /threads:
    post:
      operationId: createThread
      tags:
        - Threads
      summary: Create thread
      description: >
        Create a thread.  <a  href =
        "https://platform.openai.com/docs/api-reference/threads/createThread">
        Equivalent to OpenAI's create thread. </a>
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: specs/threads.yaml#/components/schemas/CreateThreadObject
      responses:
        '200':
          description: Thread created successfully
          content:
            application/json:
              schema:
                $ref: specs/threads.yaml#/components/schemas/CreateThreadResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X POST http://localhost:1337/v1/threads \
              -H "Content-Type: application/json" \
              -d '{
                  "messages": [{
                      "role": "user",
                      "content": "Hello, what is AI?",
                      "file_ids": ["file-abc123"]
                  }, {
                      "role": "user",
                      "content": "How does AI work? Explain it in simple terms."
                  }]
              }'
    get:
      operationId: listThreads
      tags:
        - Threads
      summary: List threads
      description: |
        Retrieves a list of all threads available in the system.
      responses:
        '200':
          description: List of threads retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: specs/threads.yaml#/components/schemas/ThreadObject
                example:
                  - id: thread_abc123
                    object: thread
                    created_at: 1699014083
                    assistants:
                      - assistant-001
                    metadata: {}
                    messages: []
                  - id: thread_abc456
                    object: thread
                    created_at: 1699014083
                    assistants:
                      - assistant-002
                      - assistant-003
                    metadata: {}
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/threads \
              -H "Content-Type: application/json" \
  /threads/{thread_id}:
    get:
      operationId: getThread
      tags:
        - Threads
      summary: Retrieve thread
      description: >
        Retrieves detailed information about a specific thread using its
        thread_id.  <a  href =
        "https://platform.openai.com/docs/api-reference/threads/getThread">
        Equivalent to OpenAI's retrieve thread. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
          description: |
            The ID of the thread to retrieve.
      responses:
        '200':
          description: Thread details retrieved successfully
          content:
            application/json:
              schema:
                $ref: specs/threads.yaml#/components/schemas/GetThreadResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/threads/{thread_id}
    patch:
      operationId: modifyThread
      tags:
        - Threads
      summary: Modify thread
      description: >
        Modifies a thread.  <a  href =
        "https://platform.openai.com/docs/api-reference/threads/modifyThread">
        Equivalent to OpenAI's modify thread. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
          description: |
            The ID of the thread to be modified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Set the title of the thread
                  items:
                    $ref: specs/threads.yaml#/components/schemas/ThreadMessageObject
      responses:
        '200':
          description: Thread modified successfully
          content:
            application/json:
              schema:
                $ref: specs/threads.yaml#/components/schemas/ModifyThreadResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X POST http://localhost:1337/v1/threads/{thread_id} \
              -H "Content-Type: application/json" \
              -d '{
                  "messages": [{
                      "role": "user",
                      "content": "Hello, what is AI?",
                      "file_ids": ["file-abc123"]
                  }, {
                      "role": "user",
                      "content": "How does AI work? Explain it in simple terms."
                  }]
              }'
    delete:
      operationId: deleteThread
      tags:
        - Threads
      summary: Delete thread
      description: >
        Delete a thread.  <a  href =
        "https://platform.openai.com/docs/api-reference/threads/deleteThread">
        Equivalent to OpenAI's delete thread. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
          description: |
            The ID of the thread to be deleted.
      responses:
        '200':
          description: Thread deleted successfully
          content:
            application/json:
              schema:
                $ref: specs/threads.yaml#/components/schemas/DeleteThreadResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X DELETE http://localhost:1337/v1/threads/{thread_id}
  /assistants:
    get:
      operationId: listAssistants
      tags:
        - Assistants
      summary: List assistants
      description: >
        Return a list of assistants. <a href =
        "https://platform.openai.com/docs/api-reference/assistants/listAssistants">
        Equivalent to OpenAI's list assistants. </a>
      responses:
        '200':
          description: List of assistants retrieved successfully
          content:
            application/json:
              schema:
                type: array
                example:
                  - id: asst_abc123
                    object: assistant
                    version: 1
                    created_at: 1698984975
                    name: Math Tutor
                    description: null
                    avatar: https://pic.png
                    models:
                      - model_id: model_0
                    instructions: Be concise
                    events:
                      in: []
                      out: []
                    metadata: {}
                  - id: asst_abc456
                    object: assistant
                    version: 1
                    created_at: 1698984975
                    name: Physics Tutor
                    description: null
                    avatar: https://pic.png
                    models:
                      - model_id: model_1
                    instructions: Be concise!
                    events:
                      in: []
                      out: []
                    metadata: {}
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/assistants \
              -H "Content-Type: application/json" \
  /assistants/{assistant_id}:
    get:
      operationId: getAssistant
      tags:
        - Assistants
      summary: Retrieve assistant
      description: >
        Retrieves an assistant. <a href =
        "https://platform.openai.com/docs/api-reference/assistants/getAssistant">
        Equivalent to OpenAI's retrieve assistants. </a>
      parameters:
        - in: path
          name: assistant_id
          required: true
          schema:
            type: string
            example: jan
          description: |
            The ID of the assistant to retrieve.
      responses:
        '200':
          description: null
          content:
            application/json:
              schema:
                $ref: >-
                  specs/assistants.yaml#/components/schemas/RetrieveAssistantResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/assistants/{assistant_id} \
              -H "Content-Type: application/json" \
  /threads/{thread_id}/messages:
    get:
      operationId: listMessages
      tags:
        - Messages
      summary: List messages
      description: >
        Retrieves all messages from the given thread. <a  href =
        "https://platform.openai.com/docs/api-reference/messages/listMessages">
        Equivalent to OpenAI's list messages. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
          description: |
            The ID of the thread from which to retrieve messages.
      responses:
        '200':
          description: List of messages retrieved successfully
          content:
            application/json:
              schema:
                $ref: specs/messages.yaml#/components/schemas/ListMessagesResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/threads/{thread_id}/messages \
              -H "Content-Type: application/json"
    post:
      operationId: createMessage
      tags:
        - Messages
      summary: Create message
      description: >
        Create a message. <a  href =
        "https://platform.openai.com/docs/api-reference/messages/createMessage">
        Equivalent to OpenAI's list messages. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
          description: |
            The ID of the thread to which the message will be posted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  description: |
                    Role of the sender, either 'user' or 'assistant'.
                  example: user
                  enum:
                    - user
                    - assistant
                content:
                  type: string
                  description: |
                    Text content of the message.
                  example: How does AI work? Explain it in simple terms.
              required:
                - role
                - content
      responses:
        '200':
          description: Message created successfully
          content:
            application/json:
              schema:
                $ref: specs/messages.yaml#/components/schemas/CreateMessageResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X POST http://localhost:1337/v1/threads/{thread_id}/messages \
              -H "Content-Type: application/json" \
              -d '{
                "role": "user",
                "content": "How does AI work? Explain it in simple terms."
              }'
  /threads/{thread_id}/messages/{message_id}:
    get:
      operationId: retrieveMessage
      tags:
        - Messages
      summary: Retrieve message
      description: >
        Retrieve a specific message from a thread using its thread_id and
        message_id. <a  href =
        "https://platform.openai.com/docs/api-reference/messages/getMessage">
        Equivalent to OpenAI's retrieve messages. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
          description: |
            The ID of the thread containing the message.
        - in: path
          name: message_id
          required: true
          schema:
            type: string
          description: |
            The ID of the message to retrieve.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: specs/messages.yaml#/components/schemas/GetMessageResponse
      x-codeSamples:
        - lang: cURL
          source: >
            curl
            http://localhost:1337/v1/threads/{thread_id}/messages/{message_id} \
              -H "Content-Type: application/json"
x-webhooks:
  ModelObject:
    post:
      summary: The model object
      description: >
        Describe a model offering that can be used with the API. <a  href =
        "https://platform.openai.com/docs/api-reference/models/object">
        Equivalent to OpenAI's model object. </a>
      operationId: ModelObject
      tags:
        - Models
      requestBody:
        content:
          application/json:
            schema:
              $ref: specs/models.yaml#/components/schemas/ModelObject
  AssistantObject:
    post:
      summary: The assistant object
      description: >
        Build assistants that can call models and use tools to perform tasks.
        <a  href = "https://platform.openai.com/docs/api-reference/assistants">
        Equivalent to OpenAI's assistants object. </a>
      operationId: AssistantObjects
      tags:
        - Assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: specs/assistants.yaml#/components/schemas/AssistantObject
  MessageObject:
    post:
      summary: The message object
      description: >
        Information about a message in the thread.  <a  href =
        "https://platform.openai.com/docs/api-reference/messages/object">
        Equivalent to OpenAI's message object. </a>
      operationId: MessageObject
      tags:
        - Messages
      requestBody:
        content:
          application/json:
            schema:
              $ref: specs/messages.yaml#/components/schemas/MessageObject
  ThreadObject:
    post:
      summary: The thread object
      description: >-
        Represents a thread that contains messages. <a  href =
        "https://platform.openai.com/docs/api-reference/threads/object">
        Equivalent to OpenAI's thread object. </a>
      operationId: ThreadObject
      tags:
        - Threads
      requestBody:
        content:
          application/json:
            schema:
              $ref: specs/threads.yaml#/components/schemas/ThreadObject