---
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: http://localhost:1337/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 http://localhost:1337/v1/chat/completions \
              -H "Content-Type: application/json" \
              -d '{
                "model": "tinyllama-1.1b",
                "messages": [
                  {
                    "role": "system",
                    "content": "You are a helpful assistant."
                  },
                  {
                    "role": "user",
                    "content": "Hello!"
                  }
                ]
              }'
  /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 http://localhost:1337/v1/models
    post:
      operationId: downloadModel
      tags:
        - Models
      summary: Download model
      description: |
        Download a model.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: specs/models.yaml#/components/schemas/DownloadModelResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X POST http://localhost:1337/v1/models
  "/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: zephyr-7b
          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 http://localhost:1337/v1/models/{model_id}
    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
          required: true
          schema:
            type: string
            example: zephyr-7b
          description: |
            The model 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}
  "/models/{model_id}/start":
    put:
      operationId: startModel
      tags:
        - Models
      summary: Start model
      description: |
        Starts an imported model. Loads the model into V/RAM.
      parameters:
        - in: path
          name: model
          required: true
          schema:
            type: string
            example: zephyr-7b
          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/StartModelResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X PUT http://localhost:1337/v1/models/{model_id}/start
  "/models/{model_id}/stop":
    put:
      operationId: stopModel
      tags:
        - Models
      summary: Stop model
      description: |
        Stop an imported model.
      parameters:
        - in: path
          name: model
          required: true
          schema:
            type: string
            example: zephyr-7b
          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/StopModelResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X PUT http://localhost:1337/v1/models/{model_id}/stop
  /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:
              type: object
              properties:
                messages:
                  type: array
                  description: Initial set of messages for the thread.
                  items:
                    $ref: specs/threads.yaml#/components/schemas/ThreadMessageObject
      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
            example: thread_abc123
          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}
    post:
      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
            example: thread_abc123
          description: |
            The ID of the thread to be modified.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  description: Set of messages to update in 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
            example: thread_abc123
          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}
  "/threads/{thread_id}/assistants":
    get:
      operationId: getThreadAssistants
      tags:
        - Threads
      summary: Get Thread.Assistants
      description: |
        Can achieve this goal by calling Get thread API.
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
            example: thread_abc123
          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}/assistants
  "/threads/{thread_id}/assistants/{assistants_id}":
    post:
      operationId: postThreadAssistants
      tags:
        - Threads
      summary: Modify Thread.Assistants
      description: >
        Can achieve this goal by calling Modify Assistant API with
        thread.assistant[].
  "/threads/{thread_id}/":
    get:
      operationId: listThreadMessage
      tags:
        - Threads
      summary: List Thread.Messages
      description: |
        Can achieve this goal by calling Get Thread API.
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
            example: thread_abc123
          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}
  /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 threads 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: {}
        responses: null
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/assistants \
              -H "Content-Type: application/json" \
    post:
      operationId: createAssistant
      tags:
        - Assistants
      summary: Create assistant
      description: >
        Create an assistant with a model and instructions. <a href =
        "https://platform.openai.com/docs/api-reference/assistants/createAssistant">
        Equivalent to OpenAI's create assistants. </a>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                models:
                  type: array
                  description: List of models associated with the assistant. Jan-specific
                    property.
                  items:
                    type: object
                    properties:
                      model_id:
                        type: string
                        example: model_0
      responses:
        "200":
          description: null
          content:
            application/json:
              schema:
                $ref: specs/assistants.yaml#/components/schemas/CreateAssistantResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/assistants \
              -H "Content-Type: application/json" \
              -d '{
                  "models": [
                      {
                          "model_id": "model_0"
                      }
                  ]
              }'
  "/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: asst_abc123
          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" \
    post:
      operationId: modifyAssistant
      tags:
        - Assistants
      summary: Modify assistant
      description: >
        Modifies an assistant. <a href =
        "https://platform.openai.com/docs/api-reference/assistants/modifyAssistant">
        Equivalent to OpenAI's modify assistant. </a>
      parameters:
        - in: path
          name: assistant_id
          required: true
          schema:
            type: string
            example: asst_abc123
          description: |
            The ID of the assistant to modify.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                models:
                  type: array
                  description: List of models associated with the assistant. Jan-specific
                    property.
                  items:
                    type: object
                    properties:
                      model_id:
                        type: string
                        example: model_0
                name:
                  type: string
                  description: Name of the assistant.
                  example: Physics Tutor
                instructions:
                  type: string
                  description: A system prompt for the assistant.
                  example: Be concise!
      responses:
        "200":
          description: null
          content:
            application/json:
              schema:
                $ref: specs/assistants.yaml#/components/schemas/ModifyAssistantResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl http://localhost:1337/v1/assistants/{assistant_id} \
              -H "Content-Type: application/json" \
              -d '{
                  "models": [
                      {
                          "model_id": "model_0"
                      }
                  ],
                  "name": "Physics Tutor",
                  "instructions": "Be concise!",
                }'
    delete:
      operationId: deleteAssistant
      tags:
        - Assistants
      summary: Delete assistant
      description: >
        Delete an assistant. <a href =
        "https://platform.openai.com/docs/api-reference/assistants/deleteAssistant">
        Equivalent to OpenAI's delete assistant. </a>
      parameters:
        - in: path
          name: assistant_id
          required: true
          schema:
            type: string
            example: asst_abc123
          description: |
            The ID of the assistant to delete.
      responses:
        "200":
          description: Deletion status
          content:
            application/json:
              schema:
                $ref: specs/assistants.yaml#/components/schemas/DeleteAssistantResponse
      x-codeSamples:
        - lang: cURL
          source: |
            curl -X DELETE http://localhost:1337/v1/assistants/{assistant_id}
  "/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
            example: thread_abc123
          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
            example: thread_abc123
          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
            example: thread_abc123
          description: |
            The ID of the thread containing the message.
        - in: path
          name: message_id
          required: true
          schema:
            type: string
            example: msg_abc123
          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"
  "/threads/{thread_id}/messages/{message_id}/files":
    get:
      operationId: listMessageFiles
      tags:
        - Messages
      summary: |
        List message files
      description: >
        Returns a list of message files.  <a  href =
        "https://platform.openai.com/docs/api-reference/messages/listMessageFiles">
        Equivalent to OpenAI's list message files. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
            example: thread_abc123
          description: |
            The ID of the thread containing the message.
        - in: path
          name: message_id
          required: true
          schema:
            type: string
            example: msg_abc123
          description: |
            The ID of the message whose files are to be listed.
      responses:
        "200":
          description: List of files retrieved successfully
          content:
            application/json:
              schema:
                $ref: specs/messages.yaml#/components/schemas/ListMessageFilesResponse
      x-codeSamples:
        - lang: cURL
          source: >
            curl
            http://localhost:1337/v1/threads/{thread_id}/messages/{message_id}/files
            \
              -H "Content-Type: application/json"
  "/threads/{thread_id}/messages/{message_id}/files/{file_id}":
    get:
      operationId: retrieveMessageFile
      tags:
        - Messages
      summary: Retrieve message file
      description: >
        Retrieves a file associated with a specific message in a
        thread.  <a  href =
        "https://platform.openai.com/docs/api-reference/messages/getMessageFile">
        Equivalent to OpenAI's retrieve message file. </a>
      parameters:
        - in: path
          name: thread_id
          required: true
          schema:
            type: string
            example: thread_abc123
          description: |
            The ID of the thread containing the message.
        - in: path
          name: message_id
          required: true
          schema:
            type: string
            example: msg_abc123
          description: |
            The ID of the message associated with the file.
        - in: path
          name: file_id
          required: true
          schema:
            type: string
            example: file-abc123
          description: |
            The ID of the file to retrieve.
      responses:
        "200":
          description: File retrieved successfully
          content:
            application/json:
              schema:
                $ref: specs/messages.yaml#/components/schemas/MessageFileObject
      x-codeSamples:
        - lang: cURL
          source: >
            curl
            http://localhost:1337/v1/threads/{thread_id}/messages/{message_id}/files/{file_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