openapi: 3.0.0
info:
  title: API Reference
  description: Please see https://jan.ai for documentation.
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: https://localhost:1337/v1/
tags:
  - name: Models
    description: List and describe the various models available in the API.
  - name: Chat Completion
    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).

      - Users and assistants can send multimedia messages.

      - An [OpenAI Message API](https://platform.openai.com/docs/api-reference/messages) compatible endpoint at `localhost:1337/v1/messages`.

      - Jan's `messages` API is compatible with [OpenAI's Messages API](https://platform.openai.com/docs/api-reference/messages), with additional methods for managing messages locally.

  - name: Threads
    description: |
      Threads are conversations between an `assistant` and the user:
        - Users can tweak `model` params and `assistant` behavior within each thread.
        - Users can import and export threads.
        - An [OpenAI Thread API](https://platform.openai.com/docs/api-reference/threads) compatible endpoint at `localhost:1337/v1/threads`. 
  - name: Assistants
    description: Configures and utilizes different AI assistants for varied tasks
x-tagGroups:
  - name: Endpoints
    tags:
      - Models
      - Chat Completion
  - name: Chat
    tags:
      - Assistants
      - Messages
      - Threads
paths:
  ### MODELS
  /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.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "specs/models.yaml#/components/schemas/ListModelsResponse"
      x-codeSamples:
        - lang: "curl"
          source: |
            curl https://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 https://localhost:1337/v1/models
  /models/{model_id}:          
    get:
      operationId: getModel
      tags:
        - Models
      summary: Get Model
      description: Get a model instance, providing basic information about the model such as the owner and permissioning.
      parameters:
        - in: path
          name: source_url
          required: true
          schema:
            type: string
            # ideally this will be an actual ID, so this will always work from browser
            example: https://huggingface.com/thebloke/example.gguf
          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 https://localhost:1337/v1/models/zephyr-7b
    delete:
      operationId: deleteModel
      tags:
        - Models
      summary: Delete Model
      description: Delete a model.
      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 https://localhost:1337/v1/models/zephyr-7b      
  /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
            # ideally this will be an actual ID, so this will always work from browser
            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 https://localhost:1337/v1/models/zephyr-7b/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
            # ideally this will be an actual ID, so this will always work from browser
            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 https://localhost:1337/v1/models/zephyr-7b/stop

  ### THREADS
  /threads:
    post:
      operationId: createThread
      tags:
        - Threads
      summary: Create thread
      description: Create a thread
      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 {JAN_URL}/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 {JAN_URL}/v1/threads \
                -H "Content-Type: application/json" \
  
  /threads/{thread_id}:
    get:
      operationId: getThread
      tags:
        - Threads
      summary: Get thread
      description: Retrieves detailed information about a specific thread using its thread_id.
      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 {JAN_URL}/v1/threads/{thread_id}
    post:
      operationId: modifyThread
      tags:
        - Threads
      summary: Modify thread
      description: Modifies a thread
      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 {JAN_URL}/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
      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 {JAN_URL}/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 {JAN_URL}/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 {JAN_URL}/v1/threads/{thread_id}

  ### MESSAGES
  /threads/{thread_id}/messages:
    get:
      operationId: listMessages
      tags:
        - Messages
      summary: List messaages
      description: Retrieves all messages from the given thread.
      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 {JAN_URL}/v1/threads/{thread_id}/messages \
              -H "Content-Type: application/json"
    post:
      operationId: createMessage
      tags:
        - Messages
      summary: Create message
      description: Create a message
      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 {JAN_URL}/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.
      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 {JAN_URL}/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 
      securitySchemes:
        petstore_auth:
          description: |
            Get access to data while protecting your account credentials.
            OAuth2 is also a safer and more secure way to give you access.
          type: oauth2
          flows:
            implicit:
              authorizationUrl: 'http://petstore.swagger.io/api/oauth/dialog'
              scopes:
                'write:pets': modify pets in your account
                'read:pets': read your pets
      description: | 
        <a  href = "https://platform.openai.com/docs/api-reference/messages/listMessages">  <button style = "color: #388434"> OpenAI Compatible </button></a>
        <a  href = "https://platform.openai.com/docs/api-reference/messages/listMessages">  <button style = "color: #fec928">Jan.AI Compatible    </button></a>

        Returns a list of message files.

        <a  href = "https://platform.openai.com/docs/api-reference/messages/listMessages">  <button style = "color: #388434">OpenAI Compatible    </button></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. 
            
            <span style="color:#388434">Open.AI Compatible</span>
      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 {JAN_URL}/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.
      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 {JAN_URL}/v1/threads/{thread_id}/messages/{message_id}/files/{file_id} \
              -H "Content-Type: application/json"

x-webhooks:
  ModelObject:
    post:
      summary: The model object
      description: Information about a model in the systems
      operationId: ModelObject
      tags:
        - Models
      requestBody:
        content:
          application/json:
            schema:
              $ref: 'specs/models.yaml#/components/schemas/ModelObject'

  MessageObject:
    post:
      summary: The message object
      description: Information about a message in the thread
      operationId: MessageObject
      tags:
        - Messages
      requestBody:
        content:
          application/json:
            schema:
              $ref: 'specs/messages.yaml#/components/schemas/MessageObject'

  ThreadObject:
    post:
      summary: The thread object
      description: |
        - Each `thread` folder contains a `thread.json` file, which is a representation of a thread.
        - `thread.json` contains metadata and model parameter overrides.
        - There are no required fields.

      operationId: ThreadObject
      tags:
        - Threads
      requestBody:
        content:
          application/json:
            schema:
              $ref: 'specs/threads.yaml#/components/schemas/ThreadObject'